@plurnk/plurnk-providers 1.3.4 → 1.3.6

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",

package/src/catalogProvider.test.ts

@@ -0,0 +1,100 @@
+import test, { mock } from "node:test";
+import { strict as assert } from "node:assert";
+import { catalogProviderFromEnv } from "./catalogProvider.ts";
+import { resetEmittedWarnings } from "./warnings.ts";
+
+const env = {
+    OPENAI_API_KEY: "test-key",
+    OPENAI_BASE_URL: "https://api.openai.com/v1",
+    PLURNK_PROVIDERS_FETCH_TIMEOUT: "1000",
+    PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT: "0",
+    PLURNK_PROVIDERS_REASONING: "off",
+    PLURNK_PROVIDERS_TEMPERATURE: "0.2",
+    PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15",
+    PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0",
+    PLURNK_PROVIDERS_REASONING_RESERVE: "10%",
+    PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
+    PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
+    PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
+};
+
+test.afterEach(() => {
+    mock.restoreAll();
+    resetEmittedWarnings();
+});
+
+test("catalog provider resolves model physics and Models.dev USD rates", () => {
+    const provider = catalogProviderFromEnv("openai", env, "gpt-4.1-mini");
+    assert.notEqual(provider, null);
+    assert.equal(provider?.model, "gpt-4.1-mini");
+    assert.equal(provider?.contextWindow, 1_047_576);
+    assert.equal(provider?.reasoningReserve, 16_384);
+    assert.equal(provider?.completionReserve, 32_768);
+    assert.ok((provider?.calculateCost({
+        prompt: 1_000_000,
+        completion: 1_000_000,
+        reasoning: 0,
+        cached: 0,
+        total: 2_000_000,
+    }) ?? 0) > 0);
+});
+
+test("official AI SDK provider owns the native request while PLURNK owns call settings", async () => {
+    const calls: Array<{ url: string; body: Record<string, unknown> }> = [];
+    mock.method(globalThis, "fetch", async (input: string | URL | Request, init?: RequestInit) => {
+        calls.push({
+            url: String(input),
+            body: JSON.parse(String(init?.body)) as Record<string, unknown>,
+        });
+        const chunks = [
+            `data: ${JSON.stringify({
+                id: "chatcmpl-test",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "gpt-4.1-mini",
+                choices: [{ index: 0, delta: { content: "done" }, finish_reason: "stop" }],
+            })}`,
+            `data: ${JSON.stringify({
+                id: "chatcmpl-test",
+                object: "chat.completion.chunk",
+                created: 2,
+                model: "gpt-4.1-mini",
+                choices: [],
+                usage: { prompt_tokens: 2, completion_tokens: 1, total_tokens: 3 },
+            })}`,
+            "data: [DONE]",
+        ].join("\n\n");
+        return new Response(chunks, {
+            status: 200,
+            headers: { "content-type": "text/event-stream" },
+        });
+    });
+
+    const provider = catalogProviderFromEnv("openai", env, "gpt-4.1-mini");
+    const result = await provider?.generate({
+        workerId: "worker",
+        messages: [{ role: "user", content: "hello" }],
+        maxTokens: 64,
+        sampling: { top_p: 0.8, seed: 7 },
+    });
+
+    assert.equal(result?.assistant.content, "done");
+    assert.equal(result?.assistant.usage.total, 3);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0]?.url, "https://api.openai.com/v1/chat/completions");
+    assert.equal(calls[0]?.body.model, "gpt-4.1-mini");
+    assert.equal(calls[0]?.body.temperature, 0.2);
+    assert.equal(calls[0]?.body.top_p, 0.8);
+    assert.equal(calls[0]?.body.seed, 7);
+    assert.equal(calls[0]?.body.max_tokens, 64);
+});
+
+test("cataloged unknown model fails unless its context is explicit", () => {
+    assert.equal(catalogProviderFromEnv("xai", env, "not-in-the-catalog"), null);
+    const provider = catalogProviderFromEnv("xai", {
+        ...env,
+        XAI_API_KEY: "test-key",
+        PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192",
+    }, "not-in-the-catalog");
+    assert.equal(provider?.contextWindow, 8192);
+});

package/src/catalogProvider.ts

@@ -0,0 +1,151 @@
+import { lookupProvider, resolveModel, type ModelInfo } from "@plurnk/plurnk-models";
+import {
+    contextWindowFromEnv,
+    dataCaptureFromEnv,
+    envelopeFromEnv,
+    parseRequiredFloat,
+    parseRequiredInt,
+    promptCacheKeyFromEnv,
+    reasoningFromEnv,
+    resolveReserve,
+    type ReserveSpec,
+} from "./env.ts";
+import AiSdkProvider, { type ReasoningStyle } from "./AiSdkProvider.ts";
+import { configuredProviderInfo, createSdkModel } from "./sdkModels.ts";
+import { providerSource } from "./telemetry.ts";
+import type { Provider, ProviderUsage } from "./types.ts";
+import { calculateCostUsd } from "./usage.ts";
+import { emitWarningOnce } from "./warnings.ts";
+import type { LanguageModel } from "ai";
+
+const reasoningStyleFromEnv = (
+    env: NodeJS.ProcessEnv,
+    name: string,
+): ReasoningStyle | undefined => {
+    const prefix = name.replaceAll(/[^a-zA-Z0-9]/g, "_").toUpperCase();
+    const value = env[`PLURNK_PROVIDERS_PROVIDER_${prefix}_REASONING_STYLE`];
+    if (value === undefined || value.length === 0) return undefined;
+    const styles: readonly ReasoningStyle[] = [
+        "none", "think", "include_reasoning", "effort",
+        "effort_explicit", "template", "anthropic",
+    ];
+    if (!styles.includes(value as ReasoningStyle)) {
+        throw new Error(`${name} provider: PLURNK_PROVIDERS_PROVIDER_${prefix}_REASONING_STYLE has invalid value "${value}"`);
+    }
+    return value as ReasoningStyle;
+};
+
+export const providerFromSdkModel = ({
+    name,
+    env,
+    model,
+    languageModel,
+    url,
+    headers,
+    contextWindow,
+    info,
+}: {
+    name: string;
+    env: NodeJS.ProcessEnv;
+    model: string;
+    languageModel?: LanguageModel;
+    url?: string;
+    headers?: Readonly<Record<string, string>>;
+    contextWindow: number;
+    info?: ModelInfo;
+}): Provider => {
+    emitWarningOnce(
+        `${name} provider: countTokens is a chars/2 upper bound — exact counts come from the mimetypes tokenizer seam or tokenize()`,
+        "PLURNK_TOKENIZER_HEURISTIC",
+    );
+
+    const reasoning = reasoningFromEnv(env, name);
+    const { reasoningReserve: configuredReasoning, completionReserve: configuredCompletion } = envelopeFromEnv(env, name);
+    const completionReserve: ReserveSpec = "tokens" in configuredCompletion
+        ? configuredCompletion
+        : info?.maxOutput === undefined
+            ? configuredCompletion
+            : { tokens: Math.min(info.maxOutput, Math.round(configuredCompletion.percent * contextWindow)) };
+    const completionTokens = resolveReserve(completionReserve, contextWindow);
+    const reasoningReserve: ReserveSpec = "tokens" in configuredReasoning
+        ? configuredReasoning
+        : reasoning.budget !== null
+            ? { tokens: reasoning.budget }
+            : completionTokens === null
+                ? configuredReasoning
+                : { tokens: Math.round(completionTokens / 2) };
+
+    const cost = info?.cost;
+    const calculateCost = cost === undefined
+        ? undefined
+        : (usage: ProviderUsage): number => calculateCostUsd(usage, {
+            input: cost.inputPer1M,
+            output: cost.outputPer1M,
+            cached: cost.cacheReadPer1M ?? cost.inputPer1M,
+        });
+
+    return new AiSdkProvider({
+        model,
+        ...(languageModel === undefined ? {} : { languageModel }),
+        ...(url === undefined ? {} : { url }),
+        ...(headers === undefined ? {} : { headers: { ...headers } }),
+        contextWindow,
+        fetchTimeoutMs: parseRequiredInt(env.PLURNK_PROVIDERS_FETCH_TIMEOUT, "PLURNK_PROVIDERS_FETCH_TIMEOUT", name),
+        streamIdleTimeoutMs: parseRequiredInt(env.PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT, "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT", name),
+        reasoning,
+        temperature: parseRequiredFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", name, 0),
+        repeatPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", name, 0),
+        frequencyPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_FREQUENCY_PENALTY, "PLURNK_PROVIDERS_FREQUENCY_PENALTY", name, 0),
+        reasoningReserve,
+        completionReserve,
+        retryAttempts: parseRequiredInt(env.PLURNK_PROVIDERS_RETRY_ATTEMPTS, "PLURNK_PROVIDERS_RETRY_ATTEMPTS", name),
+        reasoningStyle: reasoningStyleFromEnv(env, name),
+        promptCacheKey: url === undefined ? false : promptCacheKeyFromEnv(env, name),
+        serviceTier: env.PLURNK_PROVIDERS_SERVICE_TIER,
+        calculateCost,
+        source: providerSource(name),
+        gbnfDebug: env.PLURNK_PROVIDERS_GBNF_DEBUG !== undefined
+            && env.PLURNK_PROVIDERS_GBNF_DEBUG !== ""
+            && env.PLURNK_PROVIDERS_GBNF_DEBUG !== "0",
+        ...dataCaptureFromEnv(env, name),
+    });
+};
+
+export const catalogProviderFromEnv = (
+    name: string,
+    env: NodeJS.ProcessEnv,
+    model: string,
+    baseUrlOverride?: string,
+): Provider | null => {
+    const resolved = resolveModel(name, model);
+    const contextOverride = contextWindowFromEnv(env, name);
+    if (lookupProvider(name) === null && configuredProviderInfo(name, env) === null) return null;
+    if (name === "openai" && resolved === null) return null;
+    if (resolved === null && contextOverride === null) return null;
+    const wireModel = resolved?.id ?? model;
+    const sdk = createSdkModel(name, wireModel, env, baseUrlOverride);
+    if (sdk === null) return null;
+
+    emitWarningOnce(
+        `${name} provider: countTokens is a chars/2 upper bound — exact counts come from the mimetypes tokenizer seam or tokenize()`,
+        "PLURNK_TOKENIZER_HEURISTIC",
+    );
+
+    const info = resolved?.info;
+    const contextWindow = contextOverride ?? info?.contextWindow ?? null;
+    if (contextWindow === null) {
+        throw new Error(
+            `${name} provider: context window unresolved for "${wireModel}" — set PLURNK_PROVIDERS_CONTEXT_WINDOW or update the Models.dev snapshot`,
+        );
+    }
+    return providerFromSdkModel({
+        name,
+        env,
+        model: wireModel,
+        languageModel: sdk.languageModel,
+        url: sdk.compatible?.url,
+        headers: sdk.compatible?.headers,
+        contextWindow,
+        info,
+    });
+};

package/src/compatibleProvider.test.ts

@@ -0,0 +1,44 @@
+import test, { mock } from "node:test";
+import { strict as assert } from "node:assert";
+import { compatibleProviderFromEnv } from "./compatibleProvider.ts";
+
+const env = {
+    OPENAI_BASE_URL: "http://local.test/v1",
+    PLURNK_PROVIDERS_FETCH_TIMEOUT: "1000",
+    PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT: "0",
+    PLURNK_PROVIDERS_REASONING: "off",
+    PLURNK_PROVIDERS_TEMPERATURE: "0.2",
+    PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15",
+    PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0",
+    PLURNK_PROVIDERS_REASONING_RESERVE: "10%",
+    PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
+    PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
+    PLURNK_PROVIDERS_PROBE_ATTEMPTS: "1",
+    PLURNK_PROVIDERS_PROBE_DELAY: "0",
+    PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
+};
+
+test.afterEach(() => mock.restoreAll());
+
+test("compatible endpoints preserve configured prompt-cache affinity", async () => {
+    let body: Record<string, unknown> | undefined;
+    mock.method(globalThis, "fetch", async (input: string | URL | Request, init?: RequestInit) => {
+        if (String(input).endsWith("/models")) {
+            return new Response(JSON.stringify({ data: [{ id: "local", n_ctx: 8192 }] }));
+        }
+        body = JSON.parse(String(init?.body)) as Record<string, unknown>;
+        return new Response(JSON.stringify({
+            model: "local",
+            choices: [{ message: { content: "ok" }, finish_reason: "stop" }],
+            usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+        }), { headers: { "content-type": "application/json" } });
+    });
+
+    const provider = await compatibleProviderFromEnv("openai", env, "local");
+    await provider.generate({
+        workerId: "worker-affinity",
+        messages: [{ role: "user", content: "hello" }],
+    });
+
+    assert.equal(body?.prompt_cache_key, "worker-affinity");
+});