@plurnk/plurnk-providers 1.3.4 → 1.3.5

package/src/aiSdkAdapter.spike.test.ts

@@ -0,0 +1,242 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { APICallError, streamText } from "ai";
+
+const encoder = new TextEncoder();
+
+const sseResponse = (...chunks: object[]): Response => new Response(
+    new ReadableStream({
+        start(controller) {
+            for (const chunk of chunks) {
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`));
+            }
+            controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+            controller.close();
+        },
+    }),
+    { headers: { "content-type": "text/event-stream" } },
+);
+
+describe("AI SDK adapter spike", () => {
+    it("preserves PLURNK request extensions and complete stream evidence", async () => {
+        let requestBody: Record<string, unknown> | undefined;
+        const rawChunks = [
+            {
+                id: "response-1",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "test-model",
+                choices: [{
+                    index: 0,
+                    delta: { role: "assistant", reasoning_content: "because " },
+                    finish_reason: null,
+                }],
+            },
+            {
+                id: "response-1",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "test-model",
+                choices: [{
+                    index: 0,
+                    delta: { content: "answer" },
+                    finish_reason: null,
+                }],
+            },
+            {
+                id: "response-1",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "test-model",
+                choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+                usage: {
+                    prompt_tokens: 3,
+                    completion_tokens: 5,
+                    total_tokens: 8,
+                    completion_tokens_details: { reasoning_tokens: 2 },
+                },
+            },
+        ];
+        const provider = createOpenAICompatible({
+            name: "spike",
+            baseURL: "https://example.test/v1",
+            apiKey: "test-key",
+            includeUsage: true,
+            fetch: async (_input, init) => {
+                requestBody = JSON.parse(String(init?.body)) as Record<string, unknown>;
+                return sseResponse(...rawChunks);
+            },
+        });
+
+        const result = streamText({
+            model: provider("test-model"),
+            messages: [{ role: "user", content: "question" }],
+            maxOutputTokens: 64,
+            temperature: 0.25,
+            maxRetries: 0,
+            timeout: { totalMs: 1_000, chunkMs: 500 },
+            includeRawChunks: true,
+            providerOptions: {
+                spike: {
+                    grammar: "root ::= \"answer\"",
+                    id_slot: 2,
+                    enable_thinking: true,
+                    service_tier: "flex",
+                },
+            },
+        });
+        const parts = [];
+        for await (const part of result.fullStream) parts.push(part);
+
+        assert.equal(requestBody?.model, "test-model");
+        assert.equal(requestBody?.max_tokens, 64);
+        assert.equal(requestBody?.temperature, 0.25);
+        assert.equal(requestBody?.grammar, "root ::= \"answer\"");
+        assert.equal(requestBody?.id_slot, 2);
+        assert.equal(requestBody?.enable_thinking, true);
+        assert.equal(requestBody?.service_tier, "flex");
+        assert.equal(requestBody?.stream, true);
+        assert.deepEqual(requestBody?.stream_options, { include_usage: true });
+
+        assert.equal(await result.text, "answer");
+        assert.equal(await result.reasoningText, "because ");
+        assert.equal(await result.finishReason, "stop");
+        assert.equal(await result.rawFinishReason, "stop");
+        const usage = await result.usage;
+        assert.equal(usage.inputTokens, 3);
+        assert.equal(usage.outputTokens, 5);
+        assert.equal(usage.outputTokenDetails.reasoningTokens, 2);
+        assert.equal(usage.outputTokenDetails.textTokens, 3);
+        assert.equal(usage.totalTokens, 8);
+        assert.deepEqual(
+            parts.filter((part) => part.type === "raw").map((part) => part.rawValue),
+            rawChunks,
+        );
+    });
+
+    it("surfaces typed HTTP failures without retrying", async () => {
+        let requests = 0;
+        const provider = createOpenAICompatible({
+            name: "spike",
+            baseURL: "https://example.test/v1",
+            apiKey: "test-key",
+            fetch: async () => {
+                requests += 1;
+                return new Response(
+                    JSON.stringify({ error: { message: "rate limited", type: "rate_limit" } }),
+                    {
+                        status: 429,
+                        headers: {
+                            "content-type": "application/json",
+                            "retry-after": "3",
+                            "x-request-id": "request-1",
+                        },
+                    },
+                );
+            },
+        });
+        const result = streamText({
+            model: provider("test-model"),
+            prompt: "question",
+            maxRetries: 0,
+            onError: () => {},
+        });
+
+        const parts = [];
+        for await (const part of result.fullStream) parts.push(part);
+        const errorPart = parts.find((part) => part.type === "error");
+        assert.ok(errorPart?.type === "error");
+        assert.ok(APICallError.isInstance(errorPart.error));
+        assert.equal(errorPart.error.statusCode, 429);
+        assert.equal(errorPart.error.isRetryable, true);
+        assert.equal(errorPart.error.responseHeaders?.["retry-after"], "3");
+        assert.equal(errorPart.error.responseHeaders?.["x-request-id"], "request-1");
+        assert.match(errorPart.error.responseBody ?? "", /rate limited/);
+        assert.equal(requests, 1);
+    });
+
+    it("enforces stream-idle timeout through the transport contract", async () => {
+        const provider = createOpenAICompatible({
+            name: "spike",
+            baseURL: "https://example.test/v1",
+            apiKey: "test-key",
+            fetch: async () => new Response(
+                new ReadableStream({
+                    start(controller) {
+                        controller.enqueue(encoder.encode(`data: ${JSON.stringify({
+                            id: "response-1",
+                            object: "chat.completion.chunk",
+                            created: 1,
+                            model: "test-model",
+                            choices: [{
+                                index: 0,
+                                delta: { role: "assistant", content: "started" },
+                                finish_reason: null,
+                            }],
+                        })}\n\n`));
+                        setTimeout(() => controller.close(), 100);
+                    },
+                }),
+                { headers: { "content-type": "text/event-stream" } },
+            ),
+        });
+        const result = streamText({
+            model: provider("test-model"),
+            prompt: "question",
+            maxRetries: 0,
+            timeout: { totalMs: 500, chunkMs: 25 },
+            onError: () => {},
+        });
+
+        await assert.rejects(
+            () => Promise.resolve(result.text),
+            (error: unknown) => {
+                assert.match(String(error), /timed out|timeout/i);
+                return true;
+            },
+        );
+    });
+
+    it("propagates caller cancellation into the injected transport", async () => {
+        const caller = new AbortController();
+        let transportAborted = false;
+        const provider = createOpenAICompatible({
+            name: "spike",
+            baseURL: "https://example.test/v1",
+            apiKey: "test-key",
+            fetch: async (_input, init) => {
+                const transportSignal = init?.signal as AbortSignal;
+                return await new Promise<Response>((_resolve, reject) => {
+                    transportSignal.addEventListener(
+                        "abort",
+                        () => {
+                            transportAborted = true;
+                            reject(transportSignal.reason);
+                        },
+                        { once: true },
+                    );
+                });
+            },
+        });
+        const result = streamText({
+            model: provider("test-model"),
+            prompt: "question",
+            maxRetries: 0,
+            abortSignal: caller.signal,
+            onError: () => {},
+        });
+        const partsPromise = (async () => {
+            const parts = [];
+            for await (const part of result.fullStream) parts.push(part);
+            return parts;
+        })();
+
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        caller.abort(new Error("caller stopped"));
+        const parts = await partsPromise;
+
+        assert.equal(transportAborted, true);
+        assert.ok(parts.some((part) => part.type === "abort"));
+    });
+});

package/src/index.ts

@@ -40,7 +40,7 @@ export { chatCompletionStream, chatCompletion, OpenAiHttpError, StreamIdleError
 export type { StreamResponse, EncryptedReasoningItem, ProviderFetch } from "./openaiStream.ts";
 export { parseRequiredInt, parseOptionalInt, parseRequiredFloat, parseOptionalFloat, requireEnv, reasoningFromEnv, scopeEnvToAlias, dataCaptureFromEnv, contextWindowFromEnv, envelopeFromEnv, resolveReserve } from "./env.ts";
 export type { Reasoning, ReasoningMode, ReserveSpec } from "./env.ts";
-export { normalizeUsage, computeCost } from "./usage.ts";
+export { normalizeUsage, calculateCostUsd } from "./usage.ts";
 export type { RawUsage, TokenRates } from "./usage.ts";
 export { ProviderError, classifyProviderError, toProviderError, providerSource } from "./telemetry.ts";
 export type { TelemetryEvent, ProviderTelemetryKind } from "./telemetry.ts";

package/src/standardProviders.test.ts

@@ -550,7 +550,7 @@ test("bedrock: contextWindow resolves from the catalog via the inference-profile
     // MECHANISM (non-null, positive), never the literal - a catalog refresh must not break the build.
     assert.ok(p!.contextWindow !== null && p!.contextWindow > 0, `expected a catalog-resolved window, got ${p!.contextWindow}`);
     // cost is NOT taken from the native anthropic rate (bedrock marks up) — stays 0
-    assert.equal(p!.costFor({ prompt: 1_000_000, completion: 1_000_000, reasoning: 0, cached: 0, total: 2_000_000 }), 0);
+    assert.equal(p!.calculateCost({ prompt: 1_000_000, completion: 1_000_000, reasoning: 0, cached: 0, total: 2_000_000 }), 0);
 });
 
 test("bedrock: a publisher the catalog lacks (meta) fails hard (cloud, no probe); PLURNK_PROVIDERS_CONTEXT_WINDOW still wins", async () => {
@@ -585,11 +585,11 @@ test("standard provider: a catalog hit fills contextWindow + cost when there's n
     assert.ok(p !== null);
     assert.equal(p.contextWindow, info.contextWindow); // catalog window, no probe needed
     if (info.cost !== undefined) {
-        // 1M output tokens → outputPer1M USD, in pico-USD (per-1M ×1e6 per token).
-        const c = p.costFor({ prompt: 0, completion: 1_000_000, reasoning: 0, cached: 0, total: 1_000_000 });
-        assert.equal(c, Math.round(info.cost.outputPer1M * 1e6 * 1_000_000));
+        // One million output tokens cost exactly the catalog's per-million USD rate.
+        const c = p.calculateCost({ prompt: 0, completion: 1_000_000, reasoning: 0, cached: 0, total: 1_000_000 });
+        assert.equal(c, info.cost.outputPer1M);
     } else {
-        assert.equal(p.costFor({ prompt: 1, completion: 1, reasoning: 0, cached: 0, total: 2 }), 0);
+        assert.equal(p.calculateCost({ prompt: 1, completion: 1, reasoning: 0, cached: 0, total: 2 }), 0);
     }
 });
 
@@ -828,27 +828,17 @@ test("plurnk: a set-but-rejected key (401) surfaces the distinct #537 rejected h
     assert.equal(seen.filter((s) => s.url.endsWith("/chat/completions")).length, 1); // terminal — never retried, distinct message
 });
 
-test("plurnk: normalizes the endpoint's balance_pico into meta.balancePico (#23)", async () => {
+test("plurnk: passes currency-explicit balance metadata through (#23)", async () => {
     mock.method(globalThis, "fetch", async (url: string) => {
         const u = String(url);
         if (u.endsWith("/models")) return new Response(JSON.stringify({ data: [{ id: "plurnk", meta: { n_ctx: 49152 } }] }), { status: 200 });
         // plurnk has detectLlamaServer:false → streams; balance rides as a top-level field on a chunk.
-        const sse = 'data: {"choices":[{"delta":{"content":"hi"},"finish_reason":"stop"}],"balance_pico":880000000}\n\ndata: [DONE]';
+        const sse = 'data: {"choices":[{"delta":{"content":"hi"},"finish_reason":"stop"}],"balance":{"amount":"0.00000088","currency":"XMR"}}\n\ndata: [DONE]';
         return new Response(new ReadableStream({ start(c) { c.enqueue(new TextEncoder().encode(sse)); c.close(); } }), { status: 200 });
     });
     const p = await standardProviderFromEnv("plurnk", { ...baseEnv, PLURNK_API_KEY: "pk-test" }, "plurnk");
     const res = await p!.generate({ workerId: "r", messages: [] });
-    assert.equal(res.meta?.balancePico, 880000000);
-    mock.restoreAll();
-});
-
-test("a third-party (non-plurnk) provider never NORMALIZES balancePico — only plurnk holds that contract", async () => {
-    mock.method(globalThis, "fetch", async () =>
-        new Response(new ReadableStream({ start(c) { c.enqueue(new TextEncoder().encode('data: {"choices":[{"delta":{"content":"hi"}}],"balance_pico":880000000}\n\ndata: [DONE]')); c.close(); } }), { status: 200 }));
-    const p = await standardProviderFromEnv("groq", { ...baseEnv, GROQ_API_KEY: "k", PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192" }, "m");
-    const res = await p!.generate({ workerId: "r", messages: [] });
-    assert.equal("balancePico" in (res.meta ?? {}), false); // groq has no balanceMetaKey — no normalization
-    assert.equal(res.meta?.balance_pico, 880000000);          // but the raw field still passes through (every-provider meta)
+    assert.deepEqual(res.meta?.balance, { amount: "0.00000088", currency: "XMR" });
     mock.restoreAll();
 });
 

package/src/standardProviders.ts

@@ -14,7 +14,7 @@ import OpenAICompatProvider, { type ReasoningStyle, type GrammarStyle } from "./
 import { parseRequiredInt, parseOptionalInt, parseRequiredFloat, parseOptionalFloat, reasoningFromEnv, dataCaptureFromEnv, contextWindowFromEnv, envelopeFromEnv, resolveReserve, type ReserveSpec } from "./env.ts";
 import { emitWarningOnce } from "./warnings.ts";
 import { providerSource } from "./telemetry.ts";
-import { computeCost } from "./usage.ts";
+import { calculateCostUsd } from "./usage.ts";
 import { lookup } from "@plurnk/plurnk-models";
 
 type StandardProviderSpec = {
@@ -91,9 +91,6 @@ type StandardProviderSpec = {
     // Default ON for standard providers (OpenAI-standard field, broadly accepted);
     // set false to opt a backend out (e.g. anthropic's cache_control mechanism).
     promptCacheKey?: boolean;
-    // Top-level response field the endpoint reports account balance (pico-USD) in,
-    // surfaced as ProviderResponse.balancePico (plurnk only, #23). Absent elsewhere.
-    balanceMetaKey?: string;
     // RETIRED knob (#27→mimetypes#44): exact client-side tokenizer families were
     // removed with the tokenizer shed — the var is kept ONLY to fail hard with a
     // migration pointer when an operator still sets it.
@@ -292,7 +289,7 @@ export const STANDARD_PROVIDERS: Readonly<Record<string, StandardProviderSpec>>
         apiKeyMessage: "PLURNK_API_KEY not found. Acquire one at https://plurnk.ai . Plurnk also supports local models and alternative cloud provider configurations.",
         apiKeyRejectedMessage: "PLURNK_API_KEY was rejected by plurnk.ai (invalid or expired). Verify it at https://plurnk.ai .",
         reasoningStyle: "none", tokenizerEnvVar: "PLURNK_TOKENIZER",
-        probeNctx: true, detectLlamaServer: false, firstPartyMetadata: true, balanceMetaKey: "balance_pico", suppressTuningFloors: true,
+        probeNctx: true, detectLlamaServer: false, firstPartyMetadata: true, suppressTuningFloors: true,
     },
 });
 
@@ -526,7 +523,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
     // window for a known cloud model (groq/deepseek/mistral/…, which don't
     // probe). A local llama-server model misses the catalog and keeps its
     // probed n_ctx. Standard providers carry NO live pricing, so the catalog is
-    // the sole — never shadowing — cost source; per-1M USD → pico-USD/token (×1e6).
+    // the sole — never shadowing — cost source, expressed in USD per 1M tokens.
     // A relay with a catalogContextLookup (bedrock) resolves its window via the
     // underlying model's publisher and carries NO catalog cost (native rate ≠ relay
     // rate, #22); everyone else keys the catalog directly on (name, wireModel).
@@ -551,12 +548,12 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
         );
     }
     const cost = fallback?.cost;
-    const costFor = cost === undefined
+    const calculateCost = cost === undefined
         ? undefined
-        : (usage: ProviderUsage): number => computeCost(usage, {
-            input: cost.inputPer1M * 1e6,
-            output: cost.outputPer1M * 1e6,
-            cached: (cost.cacheReadPer1M ?? cost.inputPer1M) * 1e6,
+        : (usage: ProviderUsage): number => calculateCostUsd(usage, {
+            input: cost.inputPer1M,
+            output: cost.outputPer1M,
+            cached: cost.cacheReadPer1M ?? cost.inputPer1M,
         });
 
     // #507: completion cap — when the catalog reports a maxOutput, use
@@ -610,7 +607,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
         retryDelayMs: parseRequiredInt(env.PLURNK_PROVIDERS_RETRY_DELAY, "PLURNK_PROVIDERS_RETRY_DELAY", name),
         retryAttempts: parseRequiredInt(env.PLURNK_PROVIDERS_RETRY_ATTEMPTS, "PLURNK_PROVIDERS_RETRY_ATTEMPTS", name),
         reasoningStyle,
-        costFor,
+        calculateCost,
         source: providerSource(name),
         grammarStyle,
         // Optional debug toggle (off by default): validate a transported grammar
@@ -624,7 +621,6 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
         apiKeyRejectedMessage: spec.apiKeyRejectedMessage,
         promptCacheKey: spec.promptCacheKey ?? true, // #518: default-on for standard providers (OpenAI-standard field, 6/6 backends verified accept it); per-spec opt-out below
         serviceTier,
-        balanceMetaKey: spec.balanceMetaKey,
         supportsSlotPinning,
         slotCount,
         eosText,

package/src/types.ts

@@ -69,9 +69,9 @@ export interface ProviderResponse {
     readonly assistant: ProviderAssistant;
     readonly assistantRaw: unknown;
     // Per-turn provider→client metadata bag: the backend's non-standard top-level
-    // response fields, passed through verbatim, PLUS validated known keys we hold a
-    // contract for (e.g. `balancePico` — a finite pico-USD number, from the plurnk
-    // endpoint). The consumer (service) merges this into its Turn metadata and
+    // response fields passed through verbatim. Monetary values carry their own
+    // amount and currency; the provider does not reinterpret them. The consumer
+    // (service) merges this into its Turn metadata and
     // filters what reaches the client; it reads `meta`, never mines `assistantRaw`.
     // Absent when the backend reported no extra fields (#23, generalized).
     readonly meta?: Record<string, unknown>;
@@ -191,9 +191,9 @@ export interface Provider {
     // `tokenize === undefined` means the backend can't. Exact-counting
     // consumers (the tokenizer seam) prefer this over any client-side data.
     tokenize?(text: string): Promise<number[]>;
-    // Provider-owned cost calculation. Returns pico-USD (1e-12 USD).
+    // Provider-owned estimated cost calculation. Returns USD.
     // Returns 0 for siblings/models with no known rates.
-    costFor(usage: ProviderUsage): number;
+    calculateCost(usage: ProviderUsage): number;
 }
 
 // ProviderAlias moved to @plurnk/plurnk-aliases (the zero-dep parser, #27);

package/src/usage.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { normalizeUsage, computeCost } from "./usage.ts";
+import { normalizeUsage, calculateCostUsd } from "./usage.ts";
 
 // — normalizeUsage —
 
@@ -115,22 +115,20 @@ test("normalizeUsage: no total reported -> re-split skipped, reasoning stays 0 (
     assert.deepEqual(u, { prompt: 10, completion: 20, reasoning: 0, cached: 0, total: 30 });
 });
 
-// — computeCost —
+// — calculateCostUsd —
 
-test("computeCost: bills reasoning at the output rate", () => {
+test("calculateCostUsd: bills reasoning at the USD-per-million output rate", () => {
     // 100 input, 0 cached, 50 completion + 200 reasoning = 250 output.
     const usage = { prompt: 100, completion: 50, reasoning: 200, cached: 0, total: 350 };
-    // input 1 pico/tok, output 10 pico/tok → 100*1 + 250*10 = 2600
-    assert.equal(computeCost(usage, { input: 1, output: 10, cached: 0 }), 2600);
+    assert.equal(calculateCostUsd(usage, { input: 1, output: 10, cached: 0 }), 0.0026);
 });
 
-test("computeCost: cached prompt billed at the cache rate, remainder at input", () => {
+test("calculateCostUsd: cached prompt billed at the cache rate, remainder at input", () => {
     const usage = { prompt: 1000, completion: 0, reasoning: 0, cached: 400, total: 1000 };
-    // 600 non-cached @5 + 400 cached @1 = 3000 + 400 = 3400
-    assert.equal(computeCost(usage, { input: 5, output: 99, cached: 1 }), 3400);
+    assert.equal(calculateCostUsd(usage, { input: 5, output: 99, cached: 1 }), 0.0034);
 });
 
-test("computeCost: zero rates → 0", () => {
+test("calculateCostUsd: zero rates → 0", () => {
     const usage = { prompt: 9, completion: 9, reasoning: 9, cached: 9, total: 27 };
-    assert.equal(computeCost(usage, { input: 0, output: 0, cached: 0 }), 0);
+    assert.equal(calculateCostUsd(usage, { input: 0, output: 0, cached: 0 }), 0);
 });

package/src/usage.ts

@@ -69,14 +69,18 @@ export const normalizeUsage = (raw: RawUsage | null | undefined, reasoningText =
     return { prompt, completion, reasoning, cached, total };
 };
 
-// Per-token rates in pico-USD (1e-12 USD).
+// Conventional provider pricing: USD per million tokens, matching Models.dev.
 export type TokenRates = { input: number; output: number; cached: number };
 
 // The one cost formula every provider uses: non-cached prompt at the input
 // rate, cached prompt at the cache rate, and billable output (completion +
 // reasoning) at the output rate.
-export const computeCost = (usage: ProviderUsage, rates: TokenRates): number => {
+export const calculateCostUsd = (usage: ProviderUsage, rates: TokenRates): number => {
     const nonCachedPrompt = Math.max(0, usage.prompt - usage.cached);
     const output = usage.completion + usage.reasoning;
-    return Math.round(nonCachedPrompt * rates.input + usage.cached * rates.cached + output * rates.output);
+    return (
+        nonCachedPrompt * rates.input
+        + usage.cached * rates.cached
+        + output * rates.output
+    ) / 1_000_000;
 };