@plurnk/plurnk-providers 1.3.5 → 1.3.6

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");
+});

package/src/compatibleProvider.ts

@@ -0,0 +1,205 @@
+import AiSdkProvider, { type GrammarStyle, type ReasoningStyle } from "./AiSdkProvider.ts";
+import {
+    contextWindowFromEnv,
+    dataCaptureFromEnv,
+    envelopeFromEnv,
+    parseOptionalFloat,
+    parseOptionalInt,
+    parseRequiredFloat,
+    parseRequiredInt,
+    promptCacheKeyFromEnv,
+    reasoningFromEnv,
+} from "./env.ts";
+import { providerSource } from "./telemetry.ts";
+import type { Provider } from "./types.ts";
+import { emitWarningOnce } from "./warnings.ts";
+
+type EndpointProbe = {
+    nCtx: number | null;
+    llamaServer: boolean;
+    servedModel: string | null;
+    failed: boolean;
+};
+
+const chatUrl = (
+    provider: "openai" | "plurnk",
+    env: NodeJS.ProcessEnv,
+    override?: string,
+): string => {
+    const configured = override
+        ?? (provider === "openai"
+            ? env.OPENAI_BASE_URL ?? env.OPENAI_API_BASE
+            : env.PLURNK_BASE_URL);
+    if (configured === undefined || configured.length === 0) {
+        throw new Error(`${provider} provider: ${provider === "openai" ? "OPENAI_BASE_URL or OPENAI_API_BASE" : "PLURNK_BASE_URL"} must be set`);
+    }
+    const base = configured.replace(/\/+$/, "");
+    if (base.endsWith("/chat/completions")) return base;
+    if (provider === "openai") return `${base.replace(/\/v1$/, "")}/v1/chat/completions`;
+    return `${base}/chat/completions`;
+};
+
+const probeModels = async (
+    url: string,
+    headers: Record<string, string>,
+    model: string,
+    timeout: number,
+): Promise<EndpointProbe> => {
+    const modelsUrl = url.replace(/\/chat\/completions$/, "/models");
+    try {
+        const response = await fetch(modelsUrl, { headers, signal: AbortSignal.timeout(timeout) });
+        if (!response.ok) return { nCtx: null, llamaServer: false, servedModel: null, failed: true };
+        const data = await response.json() as {
+            data?: Array<{ id?: string; n_ctx?: number; meta?: { n_ctx?: number } }>;
+        };
+        const rows = data.data ?? [];
+        const row = rows.find((candidate) => candidate.id === model) ?? rows[0];
+        const nCtx = row?.meta?.n_ctx ?? row?.n_ctx;
+        return {
+            nCtx: typeof nCtx === "number" && nCtx > 0 ? nCtx : null,
+            llamaServer: row?.meta !== undefined,
+            servedModel: typeof row?.id === "string" && row.id.length > 0 ? row.id : null,
+            failed: false,
+        };
+    } catch {
+        return { nCtx: null, llamaServer: false, servedModel: null, failed: true };
+    }
+};
+
+const probeModelsRetrying = async (
+    url: string,
+    headers: Record<string, string>,
+    model: string,
+    timeout: number,
+    attempts: number,
+    delay: number,
+): Promise<EndpointProbe> => {
+    let result: EndpointProbe = { nCtx: null, llamaServer: false, servedModel: null, failed: true };
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, delay * 2 ** (attempt - 1)));
+        result = await probeModels(url, headers, model, timeout);
+        if (!result.failed) return result;
+    }
+    return result;
+};
+
+const probeProps = async (
+    url: string,
+    headers: Record<string, string>,
+    timeout: number,
+): Promise<{ slotCount: number | null; eosText: string | null }> => {
+    try {
+        const response = await fetch(url.replace(/\/v1\/chat\/completions$/, "/props"), {
+            headers,
+            signal: AbortSignal.timeout(timeout),
+        });
+        if (!response.ok) return { slotCount: null, eosText: null };
+        const data = await response.json() as { total_slots?: number; eos_token?: string };
+        return {
+            slotCount: typeof data.total_slots === "number" && data.total_slots > 0 ? data.total_slots : null,
+            eosText: typeof data.eos_token === "string" && data.eos_token.length > 0 ? data.eos_token : null,
+        };
+    } catch {
+        return { slotCount: null, eosText: null };
+    }
+};
+
+export const compatibleProviderFromEnv = async (
+    provider: "openai" | "plurnk",
+    env: NodeJS.ProcessEnv,
+    model: string,
+    baseUrlOverride?: string,
+): Promise<Provider> => {
+    const url = chatUrl(provider, env, baseUrlOverride);
+    const apiKey = provider === "openai" ? env.OPENAI_API_KEY : env.PLURNK_API_KEY;
+    const headers: Record<string, string> = apiKey === undefined || apiKey.length === 0
+        ? {}
+        : { Authorization: `Bearer ${apiKey}` };
+    const timeout = parseRequiredInt(env.PLURNK_PROVIDERS_FETCH_TIMEOUT, "PLURNK_PROVIDERS_FETCH_TIMEOUT", provider);
+    const attempts = parseRequiredInt(env.PLURNK_PROVIDERS_PROBE_ATTEMPTS, "PLURNK_PROVIDERS_PROBE_ATTEMPTS", provider);
+    const probe = await probeModelsRetrying(
+        url,
+        headers,
+        model,
+        timeout,
+        attempts,
+        parseRequiredInt(env.PLURNK_PROVIDERS_PROBE_DELAY, "PLURNK_PROVIDERS_PROBE_DELAY", provider),
+    );
+    let contextWindow = contextWindowFromEnv(env, provider) ?? probe.nCtx;
+    const pinRaw = env.PLURNK_PROVIDERS_LLAMA_SERVER;
+    if (pinRaw !== undefined && pinRaw !== "" && pinRaw !== "0" && pinRaw !== "1") {
+        throw new Error(`${provider} provider: PLURNK_PROVIDERS_LLAMA_SERVER must be "1", "0", or unset`);
+    }
+    const pinned = pinRaw === undefined || pinRaw === "" ? null : pinRaw === "1";
+    const llamaServer = provider === "openai" && (pinned ?? probe.llamaServer);
+    if (probe.failed && pinned === null && provider === "openai") {
+        emitWarningOnce(
+            `${provider} provider: llama-server detection failed after ${attempts} attempts; pin PLURNK_PROVIDERS_LLAMA_SERVER=1 when this is a llama-server`,
+            "PLURNK_PROBE_FAILED",
+        );
+    }
+    if (contextWindow === null) {
+        emitWarningOnce(
+            `${provider} provider: context window underivable for "${model}"; set PLURNK_PROVIDERS_CONTEXT_WINDOW`,
+            "PLURNK_CONTEXT_UNKNOWN",
+        );
+    }
+
+    let grammarStyle: GrammarStyle = "none";
+    let reasoningStyle: ReasoningStyle = provider === "openai" ? "think" : "none";
+    let slotCount: number | null = null;
+    let eosText: string | undefined;
+    let tokenizeUrl: string | undefined;
+    if (llamaServer) {
+        grammarStyle = "llamacpp";
+        reasoningStyle = "template";
+        const props = await probeProps(url, headers, timeout);
+        slotCount = props.slotCount;
+        eosText = props.eosText ?? undefined;
+        tokenizeUrl = url.replace(/\/v1\/chat\/completions$/, "/tokenize");
+    }
+
+    emitWarningOnce(
+        `${provider} provider: countTokens is a chars/2 upper bound — exact counts come from the mimetypes tokenizer seam or tokenize()`,
+        "PLURNK_TOKENIZER_HEURISTIC",
+    );
+    const { reasoningReserve, completionReserve } = envelopeFromEnv(env, provider);
+    return new AiSdkProvider({
+        model,
+        url,
+        headers,
+        contextWindow,
+        fetchTimeoutMs: timeout,
+        streamIdleTimeoutMs: parseRequiredInt(env.PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT, "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT", provider),
+        reasoning: reasoningFromEnv(env, provider),
+        reasoningStyle,
+        temperature: parseRequiredFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", provider, 0),
+        repeatPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", provider, 0),
+        frequencyPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_FREQUENCY_PENALTY, "PLURNK_PROVIDERS_FREQUENCY_PENALTY", provider, 0),
+        dryMultiplier: parseOptionalFloat(env.PLURNK_PROVIDERS_DRY_MULTIPLIER, "PLURNK_PROVIDERS_DRY_MULTIPLIER", provider, 0) ?? undefined,
+        dryBase: parseOptionalFloat(env.PLURNK_PROVIDERS_DRY_BASE, "PLURNK_PROVIDERS_DRY_BASE", provider, 0) ?? undefined,
+        dryAllowedLength: parseOptionalInt(env.PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH, "PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH", provider) ?? undefined,
+        repeatLastN: parseOptionalInt(env.PLURNK_PROVIDERS_REPEAT_LAST_N, "PLURNK_PROVIDERS_REPEAT_LAST_N", provider) ?? undefined,
+        reasoningReserve,
+        completionReserve,
+        tuningFloors: provider !== "plurnk",
+        retryAttempts: parseRequiredInt(env.PLURNK_PROVIDERS_RETRY_ATTEMPTS, "PLURNK_PROVIDERS_RETRY_ATTEMPTS", provider),
+        promptCacheKey: promptCacheKeyFromEnv(env, provider),
+        source: providerSource(provider),
+        grammarStyle,
+        gbnfDebug: env.PLURNK_PROVIDERS_GBNF_DEBUG !== undefined
+            && env.PLURNK_PROVIDERS_GBNF_DEBUG !== ""
+            && env.PLURNK_PROVIDERS_GBNF_DEBUG !== "0",
+        ...dataCaptureFromEnv(env, provider),
+        firstPartyMetadata: provider === "plurnk",
+        apiKeyRejectedMessage: provider === "plurnk"
+            ? "PLURNK_API_KEY was rejected by plurnk.ai (invalid or expired)."
+            : undefined,
+        supportsSlotPinning: llamaServer,
+        slotCount,
+        eosText,
+        tokenizeUrl,
+        servedModel: probe.servedModel ?? undefined,
+        requiresMaxTokens: llamaServer || undefined,
+    });
+};

package/src/discover.test.ts

@@ -26,14 +26,14 @@ const buildModules = async (t: TestContext, packages: Record<string, unknown>):
 
 test("discover: the node_modules scan is scope-agnostic — third-party scopes are found", async (t) => {
     const root = await buildModules(t, {
-        "@plurnk/plurnk-providers-openrouter": { name: "@plurnk/plurnk-providers-openrouter", plurnk: { kind: "provider", name: "openrouter" } },
+        "@plurnk/plurnk-provider-native": { name: "@plurnk/plurnk-provider-native", plurnk: { kind: "provider", name: "native" } },
         "@acme/acme-provider-foo": { name: "@acme/acme-provider-foo", plurnk: { kind: "provider", name: "foo" } },
         "unscoped-provider-bar": { name: "unscoped-provider-bar", plurnk: { kind: "provider", name: "bar" } },
         "left-pad": { name: "left-pad" },                                   // no plurnk block → ignored
         "@plurnk/plurnk-execs-git": { name: "@plurnk/plurnk-execs-git", plurnk: { kind: "exec", runtimes: [] } }, // wrong kind → ignored
     });
     const { registry } = await discover({ cwd: root });
-    assert.deepEqual([...registry.keys()].sort(), ["bar", "foo", "openrouter"]);
+    assert.deepEqual([...registry.keys()].sort(), ["bar", "foo", "native"]);
     assert.equal(registry.get("foo"), "@acme/acme-provider-foo");      // third-party scope resolves
     assert.equal(registry.get("bar"), "unscoped-provider-bar");        // unscoped resolves
 });
@@ -49,12 +49,12 @@ test("discover: a provider package missing plurnk.name is ignored, not crashed",
 
 test("discover: a name claimed by two packages is a fail-hard collision", async (t) => {
     const root = await buildModules(t, {
-        "@plurnk/plurnk-providers-xai": { name: "@plurnk/plurnk-providers-xai", plurnk: { kind: "provider", name: "xai" } },
-        "@acme/rival-xai": { name: "@acme/rival-xai", plurnk: { kind: "provider", name: "xai" } },
+        "@plurnk/plurnk-provider-native": { name: "@plurnk/plurnk-provider-native", plurnk: { kind: "provider", name: "native" } },
+        "@acme/rival-native": { name: "@acme/rival-native", plurnk: { kind: "provider", name: "native" } },
     });
     await assert.rejects(
         () => discover({ cwd: root }),
-        /provider name collision: 'xai' claimed by both/,
+        /provider name collision: 'native' claimed by both/,
     );
 });
 
@@ -64,11 +64,11 @@ test("discover: node_modules entries with no package.json or malformed JSON are
     await fs.mkdir(path.join(nm, "no-manifest"), { recursive: true });                  // a dir, no package.json
     await fs.mkdir(path.join(nm, "broken"), { recursive: true });
     await fs.writeFile(path.join(nm, "broken", "package.json"), "{ not json", "utf-8");  // malformed
-    const good = path.join(nm, "@plurnk", "plurnk-providers-ollama");
+    const good = path.join(nm, "@plurnk", "plurnk-provider-native");
     await fs.mkdir(good, { recursive: true });
-    await fs.writeFile(path.join(good, "package.json"), JSON.stringify({ name: "@plurnk/plurnk-providers-ollama", plurnk: { kind: "provider", name: "ollama" } }), "utf-8");
+    await fs.writeFile(path.join(good, "package.json"), JSON.stringify({ name: "@plurnk/plurnk-provider-native", plurnk: { kind: "provider", name: "native" } }), "utf-8");
     const { registry } = await discover({ cwd: root });
-    assert.deepEqual([...registry.keys()], ["ollama"]); // only the well-formed provider survives
+    assert.deepEqual([...registry.keys()], ["native"]); // only the well-formed provider survives
 });
 
 test("discover: surfaces plurnk.attribution (string or string[]) for registered providers (#21)", async (t) => {
@@ -94,7 +94,7 @@ test("discover: missing node_modules yields an empty registry, not an error", as
 // — trust gate (PLURNK_PLUGINS_TRUSTED_ONLY, #15) —
 
 const trustFixture = (t: TestContext) => buildModules(t, {
-    "@plurnk/plurnk-providers-openrouter": { name: "@plurnk/plurnk-providers-openrouter", plurnk: { kind: "provider", name: "openrouter" } },
+    "@plurnk/plurnk-provider-native": { name: "@plurnk/plurnk-provider-native", plurnk: { kind: "provider", name: "native" } },
     "@acme/acme-provider-foo": { name: "@acme/acme-provider-foo", plurnk: { kind: "provider", name: "foo" } },
 });
 
@@ -102,7 +102,7 @@ test("trust gate OFF (unset/empty/0): every provider is trusted", async (t) => {
     const root = await trustFixture(t);
     for (const gate of [undefined, "", "0"]) {
         const { registry, skipped } = await discover({ cwd: root, env: { PLURNK_PLUGINS_TRUSTED_ONLY: gate } as NodeJS.ProcessEnv });
-        assert.deepEqual([...registry.keys()].sort(), ["foo", "openrouter"]);
+        assert.deepEqual([...registry.keys()].sort(), ["foo", "native"]);
         assert.equal(skipped.size, 0);
     }
 });
@@ -110,7 +110,7 @@ test("trust gate OFF (unset/empty/0): every provider is trusted", async (t) => {
 test("trust gate ON: @plurnk/* always trusted; third party declined → skipped, not registered", async (t) => {
     const root = await trustFixture(t);
     const { registry, skipped } = await discover({ cwd: root, env: { PLURNK_PLUGINS_TRUSTED_ONLY: "1" } as NodeJS.ProcessEnv });
-    assert.deepEqual([...registry.keys()], ["openrouter"]);          // @plurnk/* survives
+    assert.deepEqual([...registry.keys()], ["native"]);              // @plurnk/* survives
     assert.equal(registry.has("foo"), false);                        // third party not registered
     assert.equal(skipped.get("foo"), "@acme/acme-provider-foo");     // …recorded for a precise error
 });
@@ -118,6 +118,6 @@ test("trust gate ON: @plurnk/* always trusted; third party declined → skipped,
 test("trust gate ON with an allowlist: a named third-party package is trusted", async (t) => {
     const root = await trustFixture(t);
     const { registry, skipped } = await discover({ cwd: root, env: { PLURNK_PLUGINS_TRUSTED_ONLY: "@acme/acme-provider-foo" } as NodeJS.ProcessEnv });
-    assert.deepEqual([...registry.keys()].sort(), ["foo", "openrouter"]);
+    assert.deepEqual([...registry.keys()].sort(), ["foo", "native"]);
     assert.equal(skipped.size, 0);
 });

package/src/discover.ts

@@ -2,22 +2,19 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import Meta from "@plurnk/plurnk-meta";
 
-// Scope-agnostic discovery of installed provider packages (SPEC §5, #12/#14).
+// Scope-agnostic discovery of installed AI SDK provider packages (SPEC §5).
 // Parallel to @plurnk/plurnk-execs' discover(): scan every installed package
 // under `<cwd>/node_modules` — scoped (`@scope/name`) and unscoped — and keep
 // the ones declaring `plurnk.kind === "provider"`. Scope-agnostic so a THIRD
 // PARTY can publish a provider under their own scope (`@acme/llm-provider-foo`)
-// and have it discovered with no involvement from us; first-party plugins
-// hoist flat via @plurnk/plurnk-providers-all so they land in the same scan.
+// and have it discovered without involvement from PLURNK.
 //
 // A provider package maps ONE name → its package specifier (unlike execs, whose
 // runtime tags are a per-package array). The name is the alias-cascade provider
 // segment (PLURNK_MODEL_<alias>=<name>/<model>). A name collision between two
 // installed packages is a FAIL-HARD ambiguity the operator must resolve.
 //
-// The standard-provider table (./standardProviders.ts) is a separate, closed
-// tier-1 resolved before this scan — discovery covers tier 2 (bespoke + third
-// party) only. Precedence and standard-name shadowing live in ProviderRegistry.
+// Cataloged and operator-declared providers resolve before this scan.
 //
 // Host plugin trust gate (PLURNK_PLUGINS_TRUSTED_ONLY, #15 / plurnk-service#229)
 // — enforced uniformly across the four scope-agnostic families. An untrusted

package/src/env.ts

@@ -1,6 +1,5 @@
-// Env-parsing helpers shared by every provider's fromEnv factory. Each was
-// copy-pasted per sibling with only the error-message prefix differing; the
-// `label` parameter (the provider name) restores that prefix from one source.
+// Env-parsing helpers shared by provider construction. `label` keeps failures
+// local to the selected provider.
 
 export const parseRequiredInt = (raw: string | undefined, name: string, label: string): number => {
     if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set`);
@@ -35,6 +34,15 @@ export const requireEnv = (raw: string | undefined, name: string, label: string)
     return raw;
 };
 
+export const promptCacheKeyFromEnv = (env: NodeJS.ProcessEnv, label: string): boolean => {
+    const name = "PLURNK_PROVIDERS_PROMPT_CACHE_KEY";
+    const value = env[name];
+    if (value !== "0" && value !== "1") {
+        throw new Error(`${label} provider: ${name} must be "0" or "1"`);
+    }
+    return value === "1";
+};
+
 // Old-name shed (the #399/#472 lexicon renames): a still-set retired knob fails
 // hard pointing at its successor — never silently coexists with the new floor.
 // The retired names appear ONLY as this function's ARGUMENTS at the call sites
@@ -169,11 +177,11 @@ export const PROVIDERS_KNOBS = Object.freeze([
     "PLURNK_PROVIDERS_REPEAT_PENALTY",
     "PLURNK_PROVIDERS_FREQUENCY_PENALTY",
     "PLURNK_PROVIDERS_SERVICE_TIER",
+    "PLURNK_PROVIDERS_PROMPT_CACHE_KEY",
     "PLURNK_PROVIDERS_REPEAT_LAST_N",
     "PLURNK_PROVIDERS_DRY_MULTIPLIER",
     "PLURNK_PROVIDERS_DRY_BASE",
     "PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH",
-    "PLURNK_PROVIDERS_RETRY_DELAY",
     "PLURNK_PROVIDERS_PROBE_ATTEMPTS",
     "PLURNK_PROVIDERS_PROBE_DELAY",
     "PLURNK_PROVIDERS_GBNF_DEBUG",
@@ -184,8 +192,8 @@ export const PROVIDERS_KNOBS = Object.freeze([
 // Materialize an alias-scoped VIEW of env: for each known knob with a
 // `_<alias>`-suffixed key (suffix case-folds to the alias, matching the
 // PLURNK_MODEL_/PLURNK_BASEURL_ convention), overlay it onto the bare name.
-// Providers keep reading plain vars — scoping is entirely the caller's overlay,
-// so fromEnv implementations (and plugins) need zero changes.
+// Provider construction keeps reading plain vars; scoping is the registry's
+// single overlay.
 //
 // `knobs` (optional) lets a CONSUMER scope its OWN closed knob list with this
 // same parser — e.g. the service's window-partition vars (PLURNK_SERVICE_CONTEXT_WINDOW/