@plurnk/plurnk-providers 1.4.0 → 1.6.0

package/src/aiSdkTransport.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { APICallError } from "ai";
 import { executeOpenAICompatible } from "./aiSdkTransport.ts";
 
 const request = {
@@ -9,29 +10,33 @@ const request = {
     body: {},
     messages: [{ role: "user" as const, content: "question" }],
     fetchTimeoutMs: 1_000,
-    retryAttempts: 2,
     streaming: false,
     captureRawBody: false,
 };
 
-test("X-Should-Retry:false prevents nested retries for a normally retryable status", async () => {
+test("the transport performs exactly one physical request", async () => {
     let calls = 0;
-    await assert.rejects(executeOpenAICompatible({
-        ...request,
-        fetch: async () => {
-            calls += 1;
-            return new Response(
-                JSON.stringify({ error: { message: "upstream attempts exhausted" } }),
-                {
-                    status: 503,
-                    headers: {
-                        "content-type": "application/json",
-                        "x-should-retry": "false",
+    await assert.rejects(
+        executeOpenAICompatible({
+            ...request,
+            fetch: async () => {
+                calls += 1;
+                return new Response(
+                    JSON.stringify({ error: { message: "upstream attempts exhausted" } }),
+                    {
+                        status: 503,
+                        headers: {
+                            "content-type": "application/json",
+                            "x-should-retry": "false",
+                        },
                     },
-                },
-            );
-        },
-    }));
+                );
+            },
+        }),
+        (error) => APICallError.isInstance(error)
+            && error.statusCode === 503
+            && error.isRetryable === false,
+    );
     assert.equal(calls, 1);
 });
 
@@ -64,7 +69,6 @@ test("the adapter preserves PLURNK request extensions and response evidence", as
     };
     const result = await executeOpenAICompatible({
         ...request,
-        retryAttempts: 0,
         captureRawBody: true,
         body: {
             grammar: "root ::= \"answer\"",
@@ -85,11 +89,10 @@ test("the adapter preserves PLURNK request extensions and response evidence", as
     assert.equal(result.reasoning, "because");
     assert.equal(result.finishReason, "stop");
     assert.deepEqual(result.usage, {
-        prompt: 3,
-        completion: 3,
-        reasoning: 2,
-        cached: 0,
-        total: 8,
+        inputTokens: 3,
+        outputTokens: 5,
+        totalTokens: 8,
+        outputTokenDetails: { textTokens: 3, reasoningTokens: 2 },
     });
     assert.equal(result.logprobs[0]?.token, "answer");
     assert.deepEqual(result.metadata.balance, { amount: 1.25, currency: "USD" });
@@ -116,7 +119,6 @@ test("the adapter maps leading system messages to AI SDK instructions", async ()
             { role: "user", content: "hello" },
         ],
         fetchTimeoutMs: 1000,
-        retryAttempts: 0,
         streaming: false,
         captureRawBody: false,
         fetch,
@@ -130,7 +132,6 @@ test("the adapter maps leading system messages to AI SDK instructions", async ()
 test("the adapter preserves nonstandard reasoning accounting after SDK parsing", async (t) => {
     const execute = (responseBody: object) => executeOpenAICompatible({
         ...request,
-        retryAttempts: 0,
         fetch: async () => new Response(JSON.stringify(responseBody), {
             headers: { "content-type": "application/json" },
         }),
@@ -153,25 +154,22 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
             { prompt_tokens: 2, completion_tokens: 3, total_tokens: 9 },
         ));
         assert.deepEqual(result.usage, {
-            prompt: 2,
-            completion: 3,
-            reasoning: 4,
-            cached: 0,
-            total: 9,
+            inputTokens: 2,
+            outputTokens: 7,
+            totalTokens: 9,
+            outputTokenDetails: { textTokens: 3, reasoningTokens: 4 },
         });
     });
 
-    await t.test("Fireworks-style unitemized output is split by returned channels", async () => {
+    await t.test("Fireworks-style channels do not invent token attribution", async () => {
         const result = await execute(response(
             { content: "aa", reasoning_content: "bbbbbb" },
             { prompt_tokens: 2, completion_tokens: 10, total_tokens: 12 },
         ));
         assert.deepEqual(result.usage, {
-            prompt: 2,
-            completion: 2,
-            reasoning: 8,
-            cached: 0,
-            total: 12,
+            inputTokens: 2,
+            outputTokens: 10,
+            totalTokens: 12,
         });
     });
 
@@ -195,7 +193,6 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
         ];
         const result = await executeOpenAICompatible({
             ...request,
-            retryAttempts: 0,
             streaming: true,
             fetch: async () => new Response(
                 `${chunks.map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`).join("")}data: [DONE]\n\n`,
@@ -203,15 +200,14 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
             ),
         });
         assert.deepEqual(result.usage, {
-            prompt: 2,
-            completion: 3,
-            reasoning: 4,
-            cached: 0,
-            total: 9,
+            inputTokens: 2,
+            outputTokens: 7,
+            totalTokens: 9,
+            outputTokenDetails: { textTokens: 3, reasoningTokens: 4 },
         });
     });
 
-    await t.test("streamed Fireworks-style channels preserve the output split", async () => {
+    await t.test("streamed Fireworks-style channels do not invent an output split", async () => {
         const chunks = [
             {
                 id: "response-1",
@@ -235,7 +231,6 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
         ];
         const result = await executeOpenAICompatible({
             ...request,
-            retryAttempts: 0,
             streaming: true,
             fetch: async () => new Response(
                 `${chunks.map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`).join("")}data: [DONE]\n\n`,
@@ -243,11 +238,9 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
             ),
         });
         assert.deepEqual(result.usage, {
-            prompt: 2,
-            completion: 2,
-            reasoning: 8,
-            cached: 0,
-            total: 12,
+            inputTokens: 2,
+            outputTokens: 10,
+            totalTokens: 12,
         });
     });
 });

package/src/aiSdkTransport.ts

@@ -1,9 +1,10 @@
 import { createOpenAICompatible, type ProviderErrorStructure } from "@ai-sdk/openai-compatible";
-import { generateText, streamText, type JSONValue, type LanguageModel, type LanguageModelUsage } from "ai";
+import { APICallError, generateText, streamText, type JSONValue, type LanguageModel, type LanguageModelUsage } from "ai";
 import { z } from "zod/v4";
-import type { ChatMessage, ProviderAttemptFinishReason, ProviderUsage, TokenLogprob } from "./types.ts";
+import type { ChatMessage, ProviderAttemptFinishReason, ProviderChargeEvidence, ProviderUsage, TokenLogprob } from "./types.ts";
 import { normalizeUsage, type RawUsage } from "./usage.ts";
 import { emitWarningOnce } from "./warnings.ts";
+import { ProviderTimeoutError, providerTimeoutOf } from "./errors.ts";
 
 const errorSchema = z.object({
     error: z.object({
@@ -14,18 +15,30 @@ const errorSchema = z.object({
     }).passthrough(),
 }).passthrough();
 
+const retryDirective = (
+    status: number | undefined,
+    headers: Headers | Readonly<Record<string, string>>,
+): boolean | null => {
+    const raw = headers instanceof Headers
+        ? headers.get("x-should-retry")
+        : Object.entries(headers).find(([name]) => name.toLowerCase() === "x-should-retry")?.[1];
+    const directive = raw?.trim().toLowerCase();
+    if (directive === "false") return false;
+    if (directive === "true") return true;
+    if (status !== undefined && status >= 520 && status <= 527) return false;
+    return null;
+};
+
 const errorStructure: ProviderErrorStructure<z.infer<typeof errorSchema>> = {
     errorSchema,
     errorToMessage: ({ error }) => error.message,
     isRetryable(response) {
-        const directive = response.headers.get("x-should-retry")?.trim().toLowerCase();
-        if (directive === "false") return false;
-        if (directive === "true") return true;
-        if (response.status >= 520 && response.status <= 527) return false;
-        return response.status === 408
+        return retryDirective(response.status, response.headers) ?? (
+            response.status === 408
             || response.status === 409
             || response.status === 429
-            || response.status >= 500;
+            || response.status >= 500
+        );
     },
 };
 
@@ -40,30 +53,45 @@ const baseUrl = (completionUrl: string): string => {
 
 const usageOf = (
     usage: LanguageModelUsage,
-    reasoningText: string,
-    contentText: string,
-): ProviderUsage => normalizeUsage({
+): ProviderUsage | undefined => normalizeUsage({
     prompt_tokens: usage.inputTokens,
     completion_tokens: usage.outputTokens,
     total_tokens: usage.totalTokens,
-    prompt_tokens_details: { cached_tokens: usage.inputTokenDetails.cacheReadTokens },
+    prompt_tokens_details: {
+        cached_tokens: usage.inputTokenDetails.cacheReadTokens,
+        cache_write_tokens: usage.inputTokenDetails.cacheWriteTokens,
+    },
     completion_tokens_details: usage.outputTokenDetails.reasoningTokens !== undefined
         ? { reasoning_tokens: usage.outputTokenDetails.reasoningTokens }
         : undefined,
-}, reasoningText, contentText);
+});
 
 const wireUsageOf = (
     values: readonly unknown[],
-    reasoningText: string,
-    contentText: string,
-): ProviderUsage | null => {
+): ProviderUsage | undefined => {
     for (let index = values.length - 1; index >= 0; index -= 1) {
         const usage = recordOf(values[index])?.usage;
         if (usage !== null && typeof usage === "object") {
-            return normalizeUsage(usage as RawUsage, reasoningText, contentText);
+            return normalizeUsage(usage as RawUsage);
         }
     }
-    return null;
+    return undefined;
+};
+
+const wireUsageEvidenceOf = (values: readonly unknown[]): unknown => {
+    for (let index = values.length - 1; index >= 0; index -= 1) {
+        const record = recordOf(values[index]);
+        if (record !== null && record.usage !== undefined) return record.usage;
+    }
+    return undefined;
+};
+
+const wireChargeEvidenceOf = (values: readonly unknown[]): unknown => {
+    for (let index = values.length - 1; index >= 0; index -= 1) {
+        const record = recordOf(values[index]);
+        if (record !== null && record.charge !== undefined) return record.charge;
+    }
+    return undefined;
 };
 
 const finishReasonOf = (reason: string | undefined): ProviderAttemptFinishReason => {
@@ -110,7 +138,7 @@ const metadataOf = (values: readonly unknown[]): Record<string, unknown> => {
         const record = recordOf(value);
         if (record === null) continue;
         for (const [key, item] of Object.entries(record)) {
-            if (key !== "choices" && key !== "usage") metadata[key] = item;
+            if (key !== "choices" && key !== "usage" && key !== "charge") metadata[key] = item;
         }
     }
     return metadata;
@@ -125,8 +153,8 @@ export type AiSdkTransportRequest = {
     signal?: AbortSignal;
     fetch?: typeof globalThis.fetch;
     fetchTimeoutMs: number;
+    firstContentTimeoutMs?: number;
     streamIdleTimeoutMs?: number;
-    retryAttempts: number;
     streaming: boolean;
     captureRawBody: boolean;
 };
@@ -138,7 +166,7 @@ export type AiSdkTransportResponse = {
     reasoningProjected: boolean;
     finishReason: ProviderAttemptFinishReason;
     rawFinishReason?: string;
-    usage: ProviderUsage;
+    usage?: ProviderUsage;
     metadata: Record<string, unknown>;
     reasoningEncrypted: Array<{
         id: string | null;
@@ -146,12 +174,14 @@ export type AiSdkTransportResponse = {
         encrypted: Array<{ data: string; format: string | null }>;
     }>;
     logprobs: TokenLogprob[];
+    chargeEvidence: ProviderChargeEvidence;
     rawBody?: unknown;
 };
 
 export type AiSdkModelRequest = Omit<AiSdkTransportRequest, "url" | "model" | "body" | "fetch"> & {
     languageModel: LanguageModel;
     providerOptions?: Record<string, Record<string, JSONValue | undefined>>;
+    systemProviderOptions?: Record<string, Record<string, JSONValue | undefined>>;
     temperature?: number;
     topP?: number;
     topK?: number;
@@ -163,12 +193,77 @@ export type AiSdkModelRequest = Omit<AiSdkTransportRequest, "url" | "model" | "b
     reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "none" | "provider-default";
 };
 
+const transportTimeout = (
+    cause: unknown,
+    request: AiSdkModelRequest,
+): ProviderTimeoutError | null => {
+    const owned = providerTimeoutOf(cause);
+    if (owned !== null) return owned;
+
+    const seen = new Set<unknown>();
+    let current = cause;
+    while (typeof current === "object" && current !== null && !seen.has(current)) {
+        if ((current as { name?: string }).name === "TimeoutError") break;
+        seen.add(current);
+        current = (current as { cause?: unknown }).cause;
+    }
+    if (typeof current !== "object" || current === null) return null;
+
+    const message = String((current as { message?: unknown }).message ?? "");
+    if (/first chunk timeout/i.test(message)) {
+        return new ProviderTimeoutError("first_content", request.firstContentTimeoutMs ?? 0, cause);
+    }
+    if (/chunk timeout/i.test(message)) {
+        return new ProviderTimeoutError("stream_idle", request.streamIdleTimeoutMs ?? 0, cause);
+    }
+    return new ProviderTimeoutError("attempt", request.fetchTimeoutMs, cause);
+};
+
+const streamFailureValues = new WeakMap<object, readonly unknown[]>();
+
+const applyRetryDirective = (error: unknown): unknown => {
+    if (!APICallError.isInstance(error)) return error;
+    const directed = retryDirective(error.statusCode, error.responseHeaders ?? {});
+    if (directed === null || directed === error.isRetryable) return error;
+    return new APICallError({
+        message: error.message,
+        url: error.url,
+        requestBodyValues: error.requestBodyValues,
+        statusCode: error.statusCode,
+        responseHeaders: error.responseHeaders,
+        responseBody: error.responseBody,
+        cause: error,
+        isRetryable: directed,
+        data: error.data,
+    });
+};
+
 const executeModel = async (
     request: AiSdkModelRequest,
+): Promise<AiSdkTransportResponse> => {
+    try {
+        return await executeModelOnce(request);
+    } catch (cause) {
+        if (request.signal?.aborted) throw request.signal.reason;
+        const timeout = transportTimeout(cause, request);
+        if (timeout === null) throw applyRetryDirective(cause);
+        throw new APICallError({
+            message: timeout.message,
+            url: "model:generation",
+            requestBodyValues: {},
+            cause: timeout,
+            isRetryable: true,
+        });
+    }
+};
+
+const executeModelOnce = async (
+    request: AiSdkModelRequest,
 ): Promise<AiSdkTransportResponse> => {
     const {
         languageModel: model,
         providerOptions,
+        systemProviderOptions,
         temperature,
         topP,
         topK,
@@ -196,9 +291,12 @@ const executeModel = async (
     if (request.messages.slice(instructionCount).some((message) => message.role === "system")) {
         throw new Error("provider messages: system instructions must precede conversational messages");
     }
-    const instructions = request.messages.slice(0, instructionCount).map(({ content }) => ({
+    const instructions = request.messages.slice(0, instructionCount).map(({ content }, index) => ({
         role: "system" as const,
         content,
+        ...(systemProviderOptions !== undefined && index === instructionCount - 1
+            ? { providerOptions: systemProviderOptions }
+            : {}),
     }));
     const messages = request.messages.slice(instructionCount);
     const common = {
@@ -207,12 +305,21 @@ const executeModel = async (
         messages: messages.length > 0
             ? messages
             : [{ role: "user" as const, content: "" }],
-        maxRetries: request.retryAttempts,
+        // AiSdkProvider owns retries so every physical request is independently
+        // observed and accounted. The SDK transport executes exactly once.
+        maxRetries: 0,
         abortSignal: request.signal,
         headers: request.headers,
         timeout: {
-            totalMs: request.fetchTimeoutMs,
-            ...(request.streamIdleTimeoutMs !== undefined && request.streamIdleTimeoutMs > 0
+            ...(request.fetchTimeoutMs > 0 ? { totalMs: request.fetchTimeoutMs } : {}),
+            ...(request.streaming
+                && request.firstContentTimeoutMs !== undefined
+                && request.firstContentTimeoutMs > 0
+                ? { firstChunkMs: request.firstContentTimeoutMs }
+                : {}),
+            ...(request.streaming
+                && request.streamIdleTimeoutMs !== undefined
+                && request.streamIdleTimeoutMs > 0
                 ? { chunkMs: request.streamIdleTimeoutMs }
                 : {}),
         },
@@ -227,6 +334,7 @@ const executeModel = async (
         const rawBody = result.response.body;
         const values = [rawBody];
         const evidence = extractEvidence(values);
+        const accountingUsage = wireUsageEvidenceOf(values);
         const reasoningText = evidence.reasoning || result.reasoningText || "";
         const rawFinishReason = result.rawFinishReason;
         return {
@@ -236,11 +344,25 @@ const executeModel = async (
             reasoningProjected: evidence.reasoningProjected,
             finishReason: finishReasonOf(rawFinishReason),
             ...(rawFinishReason === undefined ? {} : { rawFinishReason }),
-            usage: wireUsageOf(values, reasoningText, result.text)
-                ?? usageOf(result.usage, reasoningText, result.text),
+            usage: wireUsageOf(values) ?? usageOf(result.usage),
             metadata: metadataOf(values),
             reasoningEncrypted: evidence.reasoningEncrypted,
             logprobs: evidence.logprobs,
+            chargeEvidence: {
+                ...(wireChargeEvidenceOf(values) === undefined
+                    ? {}
+                    : { charge: wireChargeEvidenceOf(values) }),
+                ...(accountingUsage === undefined ? {} : { usage: accountingUsage }),
+                ...(result.providerMetadata === undefined
+                    ? {}
+                    : { providerMetadata: result.providerMetadata }),
+                response: {
+                    id: result.response.id,
+                    ...(result.response.headers === undefined
+                        ? {}
+                        : { headers: result.response.headers }),
+                },
+            },
             ...(request.captureRawBody ? { rawBody } : {}),
         };
     }
@@ -256,23 +378,43 @@ const executeModel = async (
         if (part.type === "raw") rawChunks.push(part.rawValue);
         if (part.type === "error") streamError ??= part.error;
     }
-    if (streamError !== undefined) throw streamError;
+    if (streamError !== undefined) {
+        if (typeof streamError === "object" && streamError !== null) {
+            streamFailureValues.set(streamError, [...rawChunks, streamError]);
+        }
+        throw streamError;
+    }
     const evidence = extractEvidence(rawChunks);
+    const accountingUsage = wireUsageEvidenceOf(rawChunks);
     const content = await result.text;
     const reasoningText = evidence.reasoning || (await result.reasoningText) || "";
     const rawFinishReason = await result.rawFinishReason;
+    const [response, providerMetadata] = await Promise.all([
+        result.response,
+        result.providerMetadata,
+    ]);
     return {
-        model: (await result.response).modelId,
+        model: response.modelId,
         content,
         reasoning: reasoningText,
         reasoningProjected: evidence.reasoningProjected,
         finishReason: finishReasonOf(rawFinishReason),
         ...(rawFinishReason === undefined ? {} : { rawFinishReason }),
-        usage: wireUsageOf(rawChunks, reasoningText, content)
-            ?? usageOf(await result.usage, reasoningText, content),
+        usage: wireUsageOf(rawChunks) ?? usageOf(await result.usage),
         metadata: metadataOf(rawChunks),
         reasoningEncrypted: evidence.reasoningEncrypted,
         logprobs: evidence.logprobs,
+        chargeEvidence: {
+            ...(wireChargeEvidenceOf(rawChunks) === undefined
+                ? {}
+                : { charge: wireChargeEvidenceOf(rawChunks) }),
+            ...(accountingUsage === undefined ? {} : { usage: accountingUsage }),
+            ...(providerMetadata === undefined ? {} : { providerMetadata }),
+            response: {
+                id: response.id,
+                ...(response.headers === undefined ? {} : { headers: response.headers }),
+            },
+        },
         ...(request.captureRawBody ? { rawBody: rawChunks } : {}),
     };
 };
@@ -304,13 +446,57 @@ export const executeOpenAICompatible = async (
         messages: request.messages,
         signal: request.signal,
         fetchTimeoutMs: request.fetchTimeoutMs,
+        firstContentTimeoutMs: request.firstContentTimeoutMs,
         streamIdleTimeoutMs: request.streamIdleTimeoutMs,
-        retryAttempts: request.retryAttempts,
         streaming: request.streaming,
         captureRawBody: request.captureRawBody,
     });
 };
 
+const responseBodyValues = (error: APICallError): readonly unknown[] => {
+    if (error.responseBody === undefined || error.responseBody.length === 0) return [];
+    try {
+        return [JSON.parse(error.responseBody)];
+    } catch {
+        return [];
+    }
+};
+
+export type AiSdkTransportFailureEvidence = {
+    readonly usage?: ProviderUsage;
+    readonly chargeEvidence: ProviderChargeEvidence;
+    readonly status?: number;
+};
+
+export const transportFailureEvidence = (
+    error: unknown,
+): AiSdkTransportFailureEvidence => {
+    const values = typeof error === "object" && error !== null
+        ? streamFailureValues.get(error) ?? (APICallError.isInstance(error) ? responseBodyValues(error) : [])
+        : [];
+    const usage = wireUsageOf(values);
+    const usageEvidence = wireUsageEvidenceOf(values);
+    const charge = wireChargeEvidenceOf(values);
+    const wireStatus = values
+        .map(recordOf)
+        .find((record) => Number.isInteger(record?.status))?.status;
+    const apiStatus = APICallError.isInstance(error) ? error.statusCode : undefined;
+    const status = Number.isInteger(apiStatus) && (apiStatus as number) >= 100 && (apiStatus as number) <= 599
+        ? apiStatus as number
+        : Number.isInteger(wireStatus) && (wireStatus as number) >= 100 && (wireStatus as number) <= 599
+            ? wireStatus as number
+            : undefined;
+    return {
+        ...(usage === undefined ? {} : { usage }),
+        chargeEvidence: {
+            ...(charge === undefined ? {} : { charge }),
+            ...(usageEvidence === undefined ? {} : { usage: usageEvidence }),
+            response: {},
+        },
+        ...(status === undefined ? {} : { status }),
+    };
+};
+
 const extractEvidence = (values: unknown[]): {
     reasoningEncrypted: AiSdkTransportResponse["reasoningEncrypted"];
     logprobs: TokenLogprob[];

package/src/boundaries.test.ts

@@ -28,8 +28,10 @@ test("provider source does not import the PLURNK parser", () => {
 
 test("the OpenAI-compatible entrypoint excludes Node-owned provider machinery", () => {
     const allowed = new Set([
+        "accounting.ts",
         "AiSdkProvider.ts",
         "aiSdkTransport.ts",
+        "cost.ts",
         "env.ts",
         "errors.ts",
         "notices.ts",