@plurnk/plurnk-providers 1.5.0 → 1.6.0

package/src/aiSdkTransport.ts

@@ -1,10 +1,10 @@
 import { createOpenAICompatible, type ProviderErrorStructure } from "@ai-sdk/openai-compatible";
 import { APICallError, generateText, streamText, type JSONValue, type LanguageModel, type LanguageModelUsage } from "ai";
-import { prepareRetries } from "ai/internal";
 import { z } from "zod/v4";
 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({
@@ -15,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
+        );
     },
 };
 
@@ -41,30 +53,29 @@ 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 => {
@@ -75,6 +86,14 @@ const wireUsageEvidenceOf = (values: readonly unknown[]): unknown => {
     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 => {
     switch (reason?.toLowerCase()) {
         case "stop":
@@ -119,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;
@@ -134,8 +153,8 @@ export type AiSdkTransportRequest = {
     signal?: AbortSignal;
     fetch?: typeof globalThis.fetch;
     fetchTimeoutMs: number;
+    firstContentTimeoutMs?: number;
     streamIdleTimeoutMs?: number;
-    retryAttempts: number;
     streaming: boolean;
     captureRawBody: boolean;
 };
@@ -147,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;
@@ -162,6 +181,7 @@ export type AiSdkTransportResponse = {
 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;
@@ -173,42 +193,68 @@ export type AiSdkModelRequest = Omit<AiSdkTransportRequest, "url" | "model" | "b
     reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "none" | "provider-default";
 };
 
-const isStreamIdleTimeout = (cause: unknown): cause is Error | DOMException =>
-    typeof cause === "object"
-    && cause !== null
-    && (cause as { name?: string }).name === "TimeoutError"
-    && /chunk timeout/i.test(String((cause as { message?: unknown }).message ?? ""));
+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> => {
-    const timeoutSignal = AbortSignal.timeout(request.fetchTimeoutMs);
-    const operationSignal = request.signal === undefined
-        ? timeoutSignal
-        : AbortSignal.any([request.signal, timeoutSignal]);
-    const { retry } = prepareRetries({
-        maxRetries: request.retryAttempts,
-        abortSignal: operationSignal,
-    });
-    return retry(async () => {
-        try {
-            return await executeModelOnce({
-                ...request,
-                signal: operationSignal,
-                retryAttempts: 0,
-            });
-        } catch (cause) {
-            if (operationSignal.aborted) throw operationSignal.reason;
-            if (!isStreamIdleTimeout(cause)) throw cause;
-            throw new APICallError({
-                message: cause.message,
-                url: "model:generation",
-                requestBodyValues: {},
-                cause,
-                isRetryable: true,
-            });
-        }
-    });
+    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 (
@@ -217,6 +263,7 @@ const executeModelOnce = async (
     const {
         languageModel: model,
         providerOptions,
+        systemProviderOptions,
         temperature,
         topP,
         topK,
@@ -244,9 +291,12 @@ const executeModelOnce = 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 = {
@@ -255,12 +305,21 @@ const executeModelOnce = 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 }
                 : {}),
         },
@@ -285,12 +344,14 @@ const executeModelOnce = 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
                     ? {}
@@ -317,7 +378,12 @@ const executeModelOnce = 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;
@@ -334,12 +400,14 @@ const executeModelOnce = async (
         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: {
@@ -378,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,6 +28,7 @@ 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",