@plurnk/plurnk-providers 1.7.0 → 1.9.0

package/src/ProviderRegistry.test.ts

@@ -4,7 +4,7 @@ import { instantiateProvider, loadActiveProvider, resetDiscoveryCache } from "./
 import type { PluginAttributionContext } from "@plurnk/plurnk-meta";
 
 const mapOf = (entries: Record<string, string>, skipped: Record<string, string> = {}) =>
-    async () => ({ registry: new Map(Object.entries(entries)), skipped: new Map(Object.entries(skipped)), attributions: new Map<string, string | string[]>() });
+    async () => ({ registry: new Map(Object.entries(entries)), skipped: new Map(Object.entries(skipped)), attributions: new Map<string, string | string[]>(), grammarStyles: new Map() });
 
 // Alias parsing is tested in @plurnk/plurnk-aliases (its owner). Here we
 // exercise the resolution + two-tier instantiation this module owns; the active
@@ -31,7 +31,7 @@ test("instantiateProvider: cataloged name resolves in-framework, no scan, no imp
     let scanned = false;
     const p = await instantiateProvider("openai", { ...fullEnv }, "m",
         async (s) => { imports.push(s); return {}; },
-        async () => { scanned = true; return { registry: new Map(), skipped: new Map(), attributions: new Map() }; });
+        async () => { scanned = true; return { registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() }; });
     assert.equal(p.model, "m");
     assert.deepEqual(imports, []); // tier 1 never touches the importer…
     assert.equal(scanned, false); // …nor the scan
@@ -77,7 +77,7 @@ test("instantiateProvider: a selected plugin composes its static and runtime att
             registry: new Map([["acme", "@acme/ai-provider"]]),
             skipped: new Map(),
             attributions: new Map([["acme", "static:provider"]]),
-            packageAttributions: new Map([["@acme/ai-provider", ["static:provider"]]]),
+            packageAttributions: new Map([["@acme/ai-provider", ["static:provider"]]]), grammarStyles: new Map(),
         }),
     );
 
@@ -107,7 +107,7 @@ test("instantiateProvider: a per-alias baseUrl drives the standard openai probe
         return new Response(JSON.stringify({ data: [] }), { status: 200 });
     });
     await instantiateProvider("openai", { ...fullEnv }, "m", // fullEnv.OPENAI_BASE_URL is http://x — the override must win
-        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() }),
+        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() }),
         "http://hazel2:8080/v1");
     assert.ok(probed.some((u) => u === "http://hazel2:8080/v1/models"), `probe hit the override host; saw ${probed.join(", ")}`);
     assert.equal(probed.some((u) => u.startsWith("http://x")), false); // never the per-name OPENAI_BASE_URL
@@ -193,13 +193,13 @@ test("instantiateProvider: per-alias knobs scope through to the provider (per-al
     });
     const env = { ...fullEnv, PLURNK_PROVIDERS_CONTEXT_WINDOW_turbo: "12345", PLURNK_PROVIDERS_LLAMA_SERVER_turbo: "1" };
     const p = await instantiateProvider("openai", env, "m",
-        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() }),
+        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() }),
         undefined, "turbo");
     assert.equal(p.contextWindow, 12345); // _turbo CONTEXT_WINDOW reached the provider
     assert.equal(p.constrainsOutput, true); // _turbo LLAMA_SERVER pin reached it too
     // same env, DIFFERENT alias: neither override applies
     const q = await instantiateProvider("openai", env, "m",
-        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() }),
+        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() }),
         undefined, "plain");
     assert.equal(q.contextWindow, null);
     assert.equal(q.constrainsOutput, false);
@@ -310,7 +310,7 @@ test("a catalog provider with unknown model metadata never falls through to plug
             "cloudflare",
             {
                 CLOUDFLARE_ACCOUNT_ID: "account",
-                CLOUDFLARE_API_TOKEN: "token",
+                CLOUDFLARE_API_KEY: "token",
             },
             "vendor/model-outside-snapshot",
             async () => { throw new Error("plugin import must not run"); },
@@ -319,7 +319,7 @@ test("a catalog provider with unknown model metadata never falls through to plug
                 return {
                     registry: new Map([["cloudflare", "@plurnk/plurnk-providers-cloudflare"]]),
                     skipped: new Map(),
-                    attributions: new Map(),
+                    attributions: new Map(), grammarStyles: new Map(),
                 };
             },
         ),
@@ -334,7 +334,7 @@ test("explicit metadata constructs an out-of-snapshot Cloudflare model in the co
         "cloudflare",
         {
             CLOUDFLARE_ACCOUNT_ID: "account",
-            CLOUDFLARE_API_TOKEN: "token",
+            CLOUDFLARE_API_KEY: "token",
             PLURNK_PROVIDERS_CONTEXT_WINDOW: "128000",
         },
         "vendor/model-outside-snapshot",
@@ -344,7 +344,7 @@ test("explicit metadata constructs an out-of-snapshot Cloudflare model in the co
             return {
                 registry: new Map([["cloudflare", "@plurnk/plurnk-providers-cloudflare"]]),
                 skipped: new Map(),
-                attributions: new Map(),
+                attributions: new Map(), grammarStyles: new Map(),
             };
         },
     );
@@ -382,7 +382,7 @@ test("{§provider-tagged-reasoning} a Cloudflare model alias carries its explici
         {
             ...fullEnv,
             CLOUDFLARE_ACCOUNT_ID: "account",
-            CLOUDFLARE_API_TOKEN: "token",
+            CLOUDFLARE_API_KEY: "token",
             PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE: "verbatim",
             PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE_cfds1: "think-tags",
         },
@@ -406,7 +406,17 @@ test("two Fireworks aliases independently select default and priority service ti
     const bodies: Record<string, unknown>[] = [];
     mock.method(globalThis, "fetch", async (_url: string, init?: RequestInit) => {
         bodies.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
-        return new Response(JSON.stringify({ choices: [{ message: { content: "ok" }, finish_reason: "stop" }] }), { status: 200, headers: { "Content-Type": "application/json" } });
+        const chunk = {
+            id: "fireworks-test",
+            object: "chat.completion.chunk",
+            created: 1,
+            model: "fireworks-test",
+            choices: [{ index: 0, delta: { content: "ok" }, finish_reason: "stop" }],
+        };
+        return new Response(`data: ${JSON.stringify(chunk)}\n\ndata: [DONE]\n\n`, {
+            status: 200,
+            headers: { "content-type": "text/event-stream" },
+        });
     });
     const env = {
         ...fullEnv,
@@ -419,7 +429,7 @@ test("two Fireworks aliases independently select default and priority service ti
         PLURNK_PROVIDERS_SERVICE_TIER_standard: "default",
     };
     const imports = async () => ({});
-    const discover = async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() });
+    const discover = async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() });
     const fast = await instantiateProvider("fireworks", env, "accounts/fireworks/routers/glm-5p2-fast", imports, discover, undefined, "fast");
     const standard = await instantiateProvider("fireworks", env, "deepseek-v4-pro", imports, discover, undefined, "standard");
     await fast.generate({ workerId: "fast-worker", messages: [] });
@@ -445,5 +455,8 @@ test("loadActiveProvider: resolves the alias cascade to an installed AI SDK prov
 });
 
 test("loadActiveProvider: throws a named error when no alias is active", async () => {
-    await assert.rejects(() => loadActiveProvider({ ...fullEnv }), /set PLURNK_MODEL to an alias/);
+    await assert.rejects(
+        () => loadActiveProvider({ ...fullEnv }),
+        /set PLURNK_MODEL to a declared alias or provider\/model route/,
+    );
 });

package/src/ProviderRegistry.ts

@@ -1,7 +1,7 @@
-// Provider instantiation + active-alias resolution. Alias PARSING (the
+// Provider instantiation + active model-route resolution. Alias parsing (the
 // PLURNK_MODEL_<alias>=<provider>/<model> cascade + PLURNK_BASEURL_<alias>
-// overrides) lives in @plurnk/plurnk-aliases — the zero-dep parser shared with
-// thin clients; this module resolves the active alias to a Provider.
+// overrides) lives in @plurnk/plurnk-aliases; this module resolves the active
+// alias-or-route selector to a Provider.
 //
 // {§provider-resolution} Models.dev catalog → PLURNK provider declaration
 // → local protocol adapter → scope-agnostic AI SDK plugin discovery. Generic
@@ -11,7 +11,7 @@
 import type { AiSdkProviderPlugin, Provider } from "./types.ts";
 import { catalogProviderFromEnv, providerFromSdkModel } from "./catalogProvider.ts";
 import { discover, type DiscoverOptions, type Discovery } from "./discover.ts";
-import { resolveActiveAlias } from "@plurnk/plurnk-aliases";
+import { resolveActiveRoute } from "@plurnk/plurnk-aliases";
 import { scopeEnvToAlias } from "./env.ts";
 import { ollamaProviderFromEnv } from "./ollama.ts";
 import { compatibleProviderFromEnv } from "./compatibleProvider.ts";
@@ -61,7 +61,7 @@ export const instantiateProvider = async (
     if (catalog !== null) return catalog;
     if (name === "ollama") return ollamaProviderFromEnv(env, model, baseUrl === undefined ? undefined : { baseUrl });
     if (name === "openai" || name === "plurnk") return compatibleProviderFromEnv(name, env, model, baseUrl);
-    const { registry, skipped, packageAttributions = new Map() } = await providerPackages(discoverFn, env);
+    const { registry, skipped, packageAttributions = new Map(), grammarStyles = new Map() } = await providerPackages(discoverFn, env);
     const specifier = registry.get(name);
     if (specifier === undefined) {
         const declined = skipped.get(name);
@@ -99,21 +99,30 @@ export const instantiateProvider = async (
         languageModel: sdkProvider.languageModel(model),
         contextWindow,
         attributions,
+        ...(grammarStyles.get(name) === undefined ? {} : { grammarStyle: grammarStyles.get(name) }),
     });
 };
 
 // Test-only: drop the memoized discovery so a fresh scan/injection runs next.
 export const resetDiscoveryCache = (): void => { discoveredCache = null; };
 
-// Boot convenience: resolve the active alias cascade and instantiate it.
+// Boot convenience: resolve the active selector and instantiate its exact route.
 export const loadActiveProvider = async (
     env: NodeJS.ProcessEnv = process.env,
     importImpl: ImportModule = importModule,
     discoverFn: DiscoverFn = discover,
 ): Promise<Provider> => {
-    const alias = resolveActiveAlias(env);
-    if (alias === null) {
-        throw new Error("no active provider: set PLURNK_MODEL to an alias declared via PLURNK_MODEL_<alias>=<provider>/<model>");
+    const route = resolveActiveRoute(env);
+    if (route === null) {
+        throw new Error("no active provider: set PLURNK_MODEL to a declared alias or provider/model route");
     }
-    return instantiateProvider(alias.provider, env, alias.model, importImpl, discoverFn, alias.baseUrl, alias.alias);
+    return instantiateProvider(
+        route.provider,
+        env,
+        route.model,
+        importImpl,
+        discoverFn,
+        route.baseUrl,
+        route.alias,
+    );
 };

package/src/accounting.test.ts

@@ -89,6 +89,34 @@ test("aggregateProviderAccounting preserves request order and only sums known fi
         },
     ]);
     assert.deepEqual(accounting.requests.map(({ provider }) => provider), ["provider:a", "provider:b"]);
-    assert.equal(accounting.usage, null, "an unknown failed request prevents fabricated totals");
-    assert.equal(accounting.costUsd, null);
+    assert.deepEqual(accounting.usage, {
+        inputTokens: 2,
+        outputTokens: 3,
+        totalTokens: 5,
+    }, "a response-less failure is skipped, never allowed to erase reported usage");
+    assert.equal(accounting.costUsd, "0.25", "a response-less failure is skipped; the expressible cost survives");
+});
+
+test("aggregateProviderAccounting omits unknown nested usage fields from its JSON projection", () => {
+    const accounting = aggregateProviderAccounting([{
+        provider: "provider:a",
+        model: "m",
+        outcome: "response",
+        usage: {
+            inputTokens: 2,
+            outputTokens: 3,
+            totalTokens: 5,
+            inputTokenDetails: { cacheReadTokens: 1 },
+            outputTokenDetails: { reasoningTokens: 2 },
+        },
+        cost: { kind: "unknown", reason: "no direct cost" },
+    }]);
+
+    assert.deepEqual(accounting.usage, {
+        inputTokens: 2,
+        outputTokens: 3,
+        totalTokens: 5,
+        inputTokenDetails: { cacheReadTokens: 1 },
+        outputTokenDetails: { reasoningTokens: 2 },
+    });
 });

package/src/accounting.ts

@@ -126,12 +126,13 @@ const sumKnown = (
     requests: readonly ProviderRequestAccounting[],
     read: (usage: ProviderUsage) => number | undefined,
 ): number | undefined => {
-    const values = requests.map((request) => request.usage === undefined
-        ? undefined
-        : read(request.usage));
-    return values.some((value) => value === undefined)
-        ? undefined
-        : (values as number[]).reduce((sum, value) => sum + value, 0);
+    // {§tokenomics-provider-usage} — aggregate usage sums every reported
+    // quantity; an unreported one (a response-less failure) is skipped, never
+    // invented as zero and never allowed to erase the reported evidence.
+    const known = requests
+        .map((request) => request.usage === undefined ? undefined : read(request.usage))
+        .filter((value): value is number => value !== undefined);
+    return known.length === 0 ? undefined : known.reduce((sum, value) => sum + value, 0);
 };
 
 export const aggregateProviderAccounting = (
@@ -167,10 +168,17 @@ export const aggregateProviderAccounting = (
     const inputTokenDetails = noCacheTokens === undefined
         && cacheReadTokens === undefined && cacheWriteTokens === undefined
         ? undefined
-        : { noCacheTokens, cacheReadTokens, cacheWriteTokens };
+        : {
+            ...(noCacheTokens === undefined ? {} : { noCacheTokens }),
+            ...(cacheReadTokens === undefined ? {} : { cacheReadTokens }),
+            ...(cacheWriteTokens === undefined ? {} : { cacheWriteTokens }),
+        };
     const outputTokenDetails = textTokens === undefined && reasoningTokens === undefined
         ? undefined
-        : { textTokens, reasoningTokens };
+        : {
+            ...(textTokens === undefined ? {} : { textTokens }),
+            ...(reasoningTokens === undefined ? {} : { reasoningTokens }),
+        };
     const usage = inputTokens === undefined && outputTokens === undefined && totalTokens === undefined
         && inputTokenDetails === undefined && outputTokenDetails === undefined
         ? null

package/src/aiSdkTransport.test.ts

@@ -208,6 +208,7 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
     });
 
     await t.test("streamed Fireworks-style channels do not invent an output split", async () => {
+        const reasoning: string[] = [];
         const chunks = [
             {
                 id: "response-1",
@@ -232,6 +233,7 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
         const result = await executeOpenAICompatible({
             ...request,
             streaming: true,
+            observeReasoning: (delta) => reasoning.push(delta),
             fetch: async () => new Response(
                 `${chunks.map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`).join("")}data: [DONE]\n\n`,
                 { headers: { "content-type": "text/event-stream" } },
@@ -242,5 +244,6 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
             outputTokens: 10,
             totalTokens: 12,
         });
+        assert.equal(reasoning.join(""), "bbbbbb", "readable reasoning is observed before transport completion");
     });
 });

package/src/aiSdkTransport.ts

@@ -1,7 +1,7 @@
 import { createOpenAICompatible, type ProviderErrorStructure } from "@ai-sdk/openai-compatible";
-import { APICallError, generateText, streamText, type JSONValue, type LanguageModel, type LanguageModelUsage } from "ai";
+import { APICallError, generateText, streamText, type CallWarning, type JSONValue, type LanguageModel, type LanguageModelUsage } from "ai";
 import { z } from "zod/v4";
-import type { ChatMessage, ProviderAttemptFinishReason, ProviderChargeEvidence, ProviderUsage, TokenLogprob } from "./types.ts";
+import type { ChatMessage, ProviderAttemptFinishReason, ProviderChargeEvidence, ProviderReasoningObserver, ProviderUsage, TokenLogprob } from "./types.ts";
 import { normalizeUsage, type RawUsage } from "./usage.ts";
 import { emitWarningOnce } from "./warnings.ts";
 import { ProviderTimeoutError, providerTimeoutOf } from "./errors.ts";
@@ -157,6 +157,7 @@ export type AiSdkTransportRequest = {
     streamIdleTimeoutMs?: number;
     streaming: boolean;
     captureRawBody: boolean;
+    observeReasoning?: ProviderReasoningObserver;
 };
 
 export type AiSdkTransportResponse = {
@@ -176,6 +177,7 @@ export type AiSdkTransportResponse = {
     logprobs: TokenLogprob[];
     chargeEvidence: ProviderChargeEvidence;
     rawBody?: unknown;
+    warnings: readonly CallWarning[];
 };
 
 export type AiSdkModelRequest = Omit<AiSdkTransportRequest, "url" | "model" | "body" | "fetch"> & {
@@ -221,11 +223,32 @@ const transportTimeout = (
 
 const streamFailureValues = new WeakMap<object, readonly unknown[]>();
 
-const applyRetryDirective = (error: unknown): unknown => {
-    if (!APICallError.isInstance(error)) return error;
+const retainStreamFailureValues = <T extends object>(source: object, target: T): T => {
+    const values = streamFailureValues.get(source);
+    if (values !== undefined) streamFailureValues.set(target, values);
+    return target;
+};
+
+const normalizeRetryAttemptError = (error: unknown): unknown => {
+    if (!APICallError.isInstance(error)) {
+        // Node's Undici stream reader reports a peer-aborted HTTP/2 body as this
+        // raw TypeError after headers have arrived. Normalize it at the attempt
+        // boundary so the owned scheduler sees the same retryability that the
+        // public ProviderError contract would otherwise assign too late.
+        if (error instanceof TypeError && error.message.trim().toLowerCase() === "terminated") {
+            return retainStreamFailureValues(error, new APICallError({
+                message: error.message,
+                url: "model:generation",
+                requestBodyValues: {},
+                cause: error,
+                isRetryable: true,
+            }));
+        }
+        return error;
+    }
     const directed = retryDirective(error.statusCode, error.responseHeaders ?? {});
     if (directed === null || directed === error.isRetryable) return error;
-    return new APICallError({
+    return retainStreamFailureValues(error, new APICallError({
         message: error.message,
         url: error.url,
         requestBodyValues: error.requestBodyValues,
@@ -235,7 +258,7 @@ const applyRetryDirective = (error: unknown): unknown => {
         cause: error,
         isRetryable: directed,
         data: error.data,
-    });
+    }));
 };
 
 const executeModel = async (
@@ -246,7 +269,7 @@ const executeModel = async (
     } catch (cause) {
         if (request.signal?.aborted) throw request.signal.reason;
         const timeout = transportTimeout(cause, request);
-        if (timeout === null) throw applyRetryDirective(cause);
+        if (timeout === null) throw normalizeRetryAttemptError(cause);
         throw new APICallError({
             message: timeout.message,
             url: "model:generation",
@@ -364,6 +387,7 @@ const executeModelOnce = async (
                 },
             },
             ...(request.captureRawBody ? { rawBody } : {}),
+            warnings: result.warnings ?? [],
         };
     }
 
@@ -376,6 +400,9 @@ const executeModelOnce = async (
     let streamError: unknown;
     for await (const part of result.fullStream) {
         if (part.type === "raw") rawChunks.push(part.rawValue);
+        if (part.type === "reasoning-delta" && part.text.length > 0) {
+            request.observeReasoning?.(part.text);
+        }
         if (part.type === "error") streamError ??= part.error;
     }
     if (streamError !== undefined) {
@@ -389,9 +416,10 @@ const executeModelOnce = async (
     const content = await result.text;
     const reasoningText = evidence.reasoning || (await result.reasoningText) || "";
     const rawFinishReason = await result.rawFinishReason;
-    const [response, providerMetadata] = await Promise.all([
+    const [response, providerMetadata, warnings] = await Promise.all([
         result.response,
         result.providerMetadata,
+        result.warnings,
     ]);
     return {
         model: response.modelId,
@@ -416,6 +444,7 @@ const executeModelOnce = async (
             },
         },
         ...(request.captureRawBody ? { rawBody: rawChunks } : {}),
+        warnings: warnings ?? [],
     };
 };
 
@@ -450,6 +479,7 @@ export const executeOpenAICompatible = async (
         streamIdleTimeoutMs: request.streamIdleTimeoutMs,
         streaming: request.streaming,
         captureRawBody: request.captureRawBody,
+        ...(request.observeReasoning === undefined ? {} : { observeReasoning: request.observeReasoning }),
     });
 };