@plurnk/plurnk-providers 1.3.5 → 1.3.7

package/src/aiSdkTransport.test.ts

@@ -0,0 +1,253 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { executeOpenAICompatible } from "./aiSdkTransport.ts";
+
+const request = {
+    url: "https://example.test/v1/chat/completions",
+    model: "test-model",
+    headers: {},
+    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 () => {
+    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",
+                    },
+                },
+            );
+        },
+    }));
+    assert.equal(calls, 1);
+});
+
+test("the adapter preserves PLURNK request extensions and response evidence", async () => {
+    let body: Record<string, unknown> | undefined;
+    const responseBody = {
+        id: "response-1",
+        object: "chat.completion",
+        created: 1,
+        model: "served-model",
+        choices: [{
+            index: 0,
+            message: {
+                role: "assistant",
+                content: "answer",
+                reasoning_content: "because",
+            },
+            finish_reason: "stop",
+            logprobs: {
+                content: [{ token: "answer", logprob: -0.1, top_logprobs: [] }],
+            },
+        }],
+        usage: {
+            prompt_tokens: 3,
+            completion_tokens: 5,
+            total_tokens: 8,
+            completion_tokens_details: { reasoning_tokens: 2 },
+        },
+        balance: { amount: 1.25, currency: "USD" },
+    };
+    const result = await executeOpenAICompatible({
+        ...request,
+        retryAttempts: 0,
+        captureRawBody: true,
+        body: {
+            grammar: "root ::= \"answer\"",
+            id_slot: 2,
+        },
+        fetch: async (_input, init) => {
+            body = JSON.parse(String(init?.body)) as Record<string, unknown>;
+            return new Response(JSON.stringify(responseBody), {
+                headers: { "content-type": "application/json" },
+            });
+        },
+    });
+
+    assert.equal(body?.grammar, "root ::= \"answer\"");
+    assert.equal(body?.id_slot, 2);
+    assert.equal(result.model, "served-model");
+    assert.equal(result.content, "answer");
+    assert.equal(result.reasoning, "because");
+    assert.equal(result.finishReason, "stop");
+    assert.deepEqual(result.usage, {
+        prompt: 3,
+        completion: 3,
+        reasoning: 2,
+        cached: 0,
+        total: 8,
+    });
+    assert.equal(result.logprobs[0]?.token, "answer");
+    assert.deepEqual(result.metadata.balance, { amount: 1.25, currency: "USD" });
+    assert.deepEqual(result.rawBody, responseBody);
+});
+
+test("the adapter maps leading system messages to AI SDK instructions", async () => {
+    const calls: Record<string, unknown>[] = [];
+    const fetch: typeof globalThis.fetch = async (_url, init) => {
+        calls.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
+        return new Response(JSON.stringify({
+            model: "m",
+            choices: [{ message: { content: "ok" }, finish_reason: "stop" }],
+            usage: { prompt_tokens: 2, completion_tokens: 1, total_tokens: 3 },
+        }), { status: 200, headers: { "content-type": "application/json" } });
+    };
+    await executeOpenAICompatible({
+        url: "https://example.test/v1/chat/completions",
+        model: "m",
+        headers: {},
+        body: {},
+        messages: [
+            { role: "system", content: "system contract" },
+            { role: "user", content: "hello" },
+        ],
+        fetchTimeoutMs: 1000,
+        retryAttempts: 0,
+        streaming: false,
+        captureRawBody: false,
+        fetch,
+    });
+    assert.deepEqual(calls[0]?.messages, [
+        { role: "system", content: "system contract" },
+        { role: "user", content: "hello" },
+    ]);
+});
+
+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" },
+        }),
+    });
+    const response = (
+        message: Record<string, unknown>,
+        usage: Record<string, number>,
+    ) => ({
+        id: "response-1",
+        object: "chat.completion",
+        created: 1,
+        model: "served-model",
+        choices: [{ index: 0, message: { role: "assistant", ...message }, finish_reason: "stop" }],
+        usage,
+    });
+
+    await t.test("Gemini-style total gap becomes reasoning", async () => {
+        const result = await execute(response(
+            { content: "answer" },
+            { prompt_tokens: 2, completion_tokens: 3, total_tokens: 9 },
+        ));
+        assert.deepEqual(result.usage, {
+            prompt: 2,
+            completion: 3,
+            reasoning: 4,
+            cached: 0,
+            total: 9,
+        });
+    });
+
+    await t.test("Fireworks-style unitemized output is split by returned channels", 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,
+        });
+    });
+
+    await t.test("streamed Gemini-style total gap is preserved", async () => {
+        const chunks = [
+            {
+                id: "response-1",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "served-model",
+                choices: [{ index: 0, delta: { content: "answer" }, finish_reason: null }],
+            },
+            {
+                id: "response-1",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "served-model",
+                choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+                usage: { prompt_tokens: 2, completion_tokens: 3, total_tokens: 9 },
+            },
+        ];
+        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`,
+                { headers: { "content-type": "text/event-stream" } },
+            ),
+        });
+        assert.deepEqual(result.usage, {
+            prompt: 2,
+            completion: 3,
+            reasoning: 4,
+            cached: 0,
+            total: 9,
+        });
+    });
+
+    await t.test("streamed Fireworks-style channels preserve the output split", async () => {
+        const chunks = [
+            {
+                id: "response-1",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "served-model",
+                choices: [{
+                    index: 0,
+                    delta: { reasoning_content: "bbbbbb", content: "aa" },
+                    finish_reason: null,
+                }],
+            },
+            {
+                id: "response-1",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "served-model",
+                choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+                usage: { prompt_tokens: 2, completion_tokens: 10, total_tokens: 12 },
+            },
+        ];
+        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`,
+                { headers: { "content-type": "text/event-stream" } },
+            ),
+        });
+        assert.deepEqual(result.usage, {
+            prompt: 2,
+            completion: 2,
+            reasoning: 8,
+            cached: 0,
+            total: 12,
+        });
+    });
+});

package/src/aiSdkTransport.ts

@@ -0,0 +1,369 @@
+import { createOpenAICompatible, type ProviderErrorStructure } from "@ai-sdk/openai-compatible";
+import { generateText, streamText, type JSONValue, type LanguageModel, type LanguageModelUsage } from "ai";
+import { z } from "zod/v4";
+import type { ChatMessage, FinishReason, ProviderUsage, TokenLogprob } from "./types.ts";
+import { normalizeUsage, type RawUsage } from "./usage.ts";
+import { emitWarningOnce } from "./warnings.ts";
+
+const errorSchema = z.object({
+    error: z.object({
+        message: z.string(),
+        type: z.string().nullish(),
+        param: z.unknown().nullish(),
+        code: z.union([z.string(), z.number()]).nullish(),
+    }).passthrough(),
+}).passthrough();
+
+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
+            || response.status === 409
+            || response.status === 429
+            || response.status >= 500;
+    },
+};
+
+const baseUrl = (completionUrl: string): string => {
+    const url = new URL(completionUrl);
+    if (!url.pathname.endsWith("/chat/completions")) {
+        throw new Error(`OpenAI-compatible URL must end in /chat/completions: ${completionUrl}`);
+    }
+    url.pathname = url.pathname.slice(0, -"/chat/completions".length);
+    return url.toString().replace(/\/$/, "");
+};
+
+const usageOf = (
+    usage: LanguageModelUsage,
+    reasoningText: string,
+    contentText: string,
+): ProviderUsage => normalizeUsage({
+    prompt_tokens: usage.inputTokens,
+    completion_tokens: usage.outputTokens,
+    total_tokens: usage.totalTokens,
+    prompt_tokens_details: { cached_tokens: usage.inputTokenDetails.cacheReadTokens },
+    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 => {
+    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 null;
+};
+
+const finishReasonOf = (reason: string | undefined): FinishReason => {
+    switch (reason?.toLowerCase()) {
+        case "stop":
+        case "end_turn":
+        case "stop_sequence":
+        case "eos_token":
+            return "stop";
+        case "length":
+        case "max_tokens":
+        case "model_length":
+        case "max_completion_tokens":
+            return "length";
+        case "tool_calls":
+        case "tool_use":
+            return "tool_calls";
+        case "content_filter":
+        case "safety":
+        case "recitation":
+            return "content_filter";
+        default:
+            if (reason !== undefined && reason.length > 0) {
+                emitWarningOnce(
+                    `unrecognized finish_reason "${reason}"; treated as no-signal (finishReason=null). If it denotes a token-cap hit, core's length-cap detection will miss it.`,
+                    "PLURNK_FINISH_REASON_UNKNOWN",
+                );
+            }
+            return null;
+    }
+};
+
+const recordOf = (value: unknown): Record<string, unknown> | null =>
+    value !== null && typeof value === "object"
+        ? value as Record<string, unknown>
+        : null;
+
+const metadataOf = (values: readonly unknown[]): Record<string, unknown> => {
+    const metadata: Record<string, unknown> = {};
+    for (const value of values) {
+        const record = recordOf(value);
+        if (record === null) continue;
+        for (const [key, item] of Object.entries(record)) {
+            if (key !== "choices" && key !== "usage") metadata[key] = item;
+        }
+    }
+    return metadata;
+};
+
+export type AiSdkTransportRequest = {
+    url: string;
+    model: string;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+    messages: ChatMessage[];
+    signal?: AbortSignal;
+    fetch?: typeof globalThis.fetch;
+    fetchTimeoutMs: number;
+    streamIdleTimeoutMs?: number;
+    retryAttempts: number;
+    streaming: boolean;
+    captureRawBody: boolean;
+};
+
+export type AiSdkTransportResponse = {
+    model: string;
+    content: string;
+    reasoning: string;
+    finishReason: FinishReason;
+    usage: ProviderUsage;
+    metadata: Record<string, unknown>;
+    reasoningEncrypted: Array<{
+        id: string | null;
+        subtype: string;
+        encrypted: Array<{ data: string; format: string | null }>;
+    }>;
+    logprobs: TokenLogprob[];
+    rawBody?: unknown;
+};
+
+export type AiSdkModelRequest = Omit<AiSdkTransportRequest, "url" | "model" | "body" | "fetch"> & {
+    languageModel: LanguageModel;
+    providerOptions?: Record<string, Record<string, JSONValue | undefined>>;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    stopSequences?: string[];
+    seed?: number;
+    maxOutputTokens?: number;
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "none" | "provider-default";
+};
+
+const executeModel = async (
+    request: AiSdkModelRequest,
+): Promise<AiSdkTransportResponse> => {
+    const {
+        languageModel: model,
+        providerOptions,
+        temperature,
+        topP,
+        topK,
+        presencePenalty,
+        frequencyPenalty,
+        stopSequences,
+        seed,
+        maxOutputTokens,
+        reasoning,
+    } = request;
+    const settings = {
+        ...(temperature === undefined ? {} : { temperature }),
+        ...(topP === undefined ? {} : { topP }),
+        ...(topK === undefined ? {} : { topK }),
+        ...(presencePenalty === undefined ? {} : { presencePenalty }),
+        ...(frequencyPenalty === undefined ? {} : { frequencyPenalty }),
+        ...(stopSequences === undefined ? {} : { stopSequences }),
+        ...(seed === undefined ? {} : { seed }),
+        ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
+        ...(reasoning === undefined ? {} : { reasoning }),
+        ...(providerOptions === undefined ? {} : { providerOptions }),
+    };
+    const firstNonSystem = request.messages.findIndex((message) => message.role !== "system");
+    const instructionCount = firstNonSystem === -1 ? request.messages.length : firstNonSystem;
+    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 }) => ({
+        role: "system" as const,
+        content,
+    }));
+    const messages = request.messages.slice(instructionCount);
+    const common = {
+        model,
+        ...(instructions.length === 0 ? {} : { instructions }),
+        messages: messages.length > 0
+            ? messages
+            : [{ role: "user" as const, content: "" }],
+        maxRetries: request.retryAttempts,
+        abortSignal: request.signal,
+        headers: request.headers,
+        timeout: {
+            totalMs: request.fetchTimeoutMs,
+            ...(request.streamIdleTimeoutMs !== undefined && request.streamIdleTimeoutMs > 0
+                ? { chunkMs: request.streamIdleTimeoutMs }
+                : {}),
+        },
+        ...settings,
+    } as const;
+
+    if (!request.streaming) {
+        const result = await generateText({
+            ...common,
+            include: { responseBody: true },
+        });
+        const rawBody = result.response.body;
+        const values = [rawBody];
+        const evidence = extractEvidence(values);
+        const reasoningText = evidence.reasoning || result.reasoningText || "";
+        return {
+            model: result.response.modelId,
+            content: result.text,
+            reasoning: reasoningText,
+            finishReason: finishReasonOf(result.rawFinishReason),
+            usage: wireUsageOf(values, reasoningText, result.text)
+                ?? usageOf(result.usage, reasoningText, result.text),
+            metadata: metadataOf(values),
+            reasoningEncrypted: evidence.reasoningEncrypted,
+            logprobs: evidence.logprobs,
+            ...(request.captureRawBody ? { rawBody } : {}),
+        };
+    }
+
+    const result = streamText({
+        ...common,
+        includeRawChunks: true,
+        onError: () => {},
+    });
+    const rawChunks: unknown[] = [];
+    let streamError: unknown;
+    for await (const part of result.fullStream) {
+        if (part.type === "raw") rawChunks.push(part.rawValue);
+        if (part.type === "error") streamError ??= part.error;
+    }
+    if (streamError !== undefined) throw streamError;
+    const evidence = extractEvidence(rawChunks);
+    const content = await result.text;
+    const reasoningText = evidence.reasoning || (await result.reasoningText) || "";
+    return {
+        model: (await result.response).modelId,
+        content,
+        reasoning: reasoningText,
+        finishReason: finishReasonOf(await result.rawFinishReason),
+        usage: wireUsageOf(rawChunks, reasoningText, content)
+            ?? usageOf(await result.usage, reasoningText, content),
+        metadata: metadataOf(rawChunks),
+        reasoningEncrypted: evidence.reasoningEncrypted,
+        logprobs: evidence.logprobs,
+        ...(request.captureRawBody ? { rawBody: rawChunks } : {}),
+    };
+};
+
+export const executeAiSdkModel = executeModel;
+
+export const executeOpenAICompatible = async (
+    request: AiSdkTransportRequest,
+): Promise<AiSdkTransportResponse> => {
+    const provider = createOpenAICompatible({
+        name: "plurnk",
+        baseURL: baseUrl(request.url),
+        headers: request.headers,
+        fetch: request.fetch,
+        includeUsage: true,
+        transformRequestBody: (sdkBody) => ({
+            ...sdkBody,
+            ...request.body,
+            stream: sdkBody.stream,
+            ...(sdkBody.stream_options !== undefined
+                ? { stream_options: sdkBody.stream_options }
+                : {}),
+        }),
+    });
+    const model = provider.languageModel(request.model, { errorStructure });
+    return executeModel({
+        languageModel: model,
+        headers: {},
+        messages: request.messages,
+        signal: request.signal,
+        fetchTimeoutMs: request.fetchTimeoutMs,
+        streamIdleTimeoutMs: request.streamIdleTimeoutMs,
+        retryAttempts: request.retryAttempts,
+        streaming: request.streaming,
+        captureRawBody: request.captureRawBody,
+    });
+};
+
+const extractEvidence = (values: unknown[]): {
+    reasoningEncrypted: AiSdkTransportResponse["reasoningEncrypted"];
+    logprobs: TokenLogprob[];
+    reasoning: string;
+} => {
+    const encrypted = new Map<string, AiSdkTransportResponse["reasoningEncrypted"][number]>();
+    const logprobs: TokenLogprob[] = [];
+    let reasoning = "";
+    let anonymous = 0;
+    for (const value of values) {
+        const choices = recordOf(value)?.choices;
+        if (!Array.isArray(choices)) continue;
+        const choice = recordOf(choices[0]);
+        if (choice === null) continue;
+        const logprobRecord = recordOf(choice.logprobs);
+        const entries = logprobRecord?.content;
+        if (Array.isArray(entries)) {
+            for (const value of entries) {
+                const entry = recordOf(value);
+                if (typeof entry?.token !== "string" || typeof entry.logprob !== "number") continue;
+                const top = Array.isArray(entry.top_logprobs)
+                    ? entry.top_logprobs.flatMap((value) => {
+                        const item = recordOf(value);
+                        return typeof item?.token === "string" && typeof item.logprob === "number"
+                            ? [{ token: item.token, logprob: item.logprob }]
+                            : [];
+                    })
+                    : undefined;
+                logprobs.push(top === undefined
+                    ? { token: entry.token, logprob: entry.logprob }
+                    : { token: entry.token, logprob: entry.logprob, top });
+            }
+        }
+        const message = recordOf(choice.delta) ?? recordOf(choice.message) ?? {};
+        for (const key of ["reasoning_content", "reasoning", "thinking"]) { // lexicon-allow: backend wire fields
+            if (typeof message[key] === "string") reasoning += message[key];
+        }
+        if (!Array.isArray(message.reasoning_details)) continue;
+        for (const value of message.reasoning_details) {
+            const detail = recordOf(value);
+            if (detail?.type !== "reasoning.encrypted" || typeof detail.data !== "string") continue;
+            const id = typeof detail.id === "string" ? detail.id : null;
+            const key = typeof detail.index === "number"
+                ? `index:${detail.index}`
+                : id === null ? `anonymous:${anonymous++}` : `id:${id}`;
+            const item: AiSdkTransportResponse["reasoningEncrypted"][number] = encrypted.get(key) ?? {
+                id,
+                subtype: "message",
+                encrypted: [],
+            };
+            const format = typeof detail.format === "string" ? detail.format : null;
+            const prior = item.encrypted.at(-1);
+            if (prior !== undefined) {
+                prior.data += detail.data;
+                if (prior.format === null && format !== null) prior.format = format;
+            } else {
+                item.encrypted.push({ data: detail.data, format });
+            }
+            encrypted.set(key, item);
+        }
+    }
+    return {
+        reasoningEncrypted: [...encrypted.values()],
+        logprobs,
+        reasoning,
+    };
+};

package/src/boundaries.test.ts

@@ -25,10 +25,10 @@ test("provider source does not import the PLURNK parser", () => {
 
 test("#608: the OpenAI-compatible entrypoint excludes Node-owned provider machinery", () => {
     const allowed = new Set([
-        "OpenAICompat.ts",
+        "AiSdkProvider.ts",
+        "aiSdkTransport.ts",
         "env.ts",
         "openai.ts",
-        "openaiStream.ts",
         "telemetry.ts",
         "types.ts",
         "usage.ts",