@plurnk/plurnk-providers 1.3.4 → 1.3.6

package/src/ProviderRegistry.ts

@@ -3,18 +3,19 @@
 // overrides) lives in @plurnk/plurnk-aliases — the zero-dep parser shared with
 // thin clients (#27); this module resolves the active alias to a Provider.
 //
-// Two-tier resolution (SPEC §5): tier 1 is the closed standard-provider table;
-// tier 2 is a SCOPE-AGNOSTIC node_modules scan (discover()) for packages
-// declaring `plurnk.kind:"provider"` — first-party plugins (installed flat
-// via @plurnk/plurnk-providers-all) AND third-party providers under any scope.
-// The framework is contract-only — it does NOT depend on its plugins; the
-// scan is what surfaces them (#12/#14).
+// Resolution order (SPEC §5): models.dev catalog → PLURNK provider declaration
+// → local protocol adapter → scope-agnostic AI SDK plugin discovery. Generic
+// provider facts belong to models.dev or operator config; PLURNK owns only the
+// stable Provider contract and product-specific local behavior.
 
-import type { Provider, ProviderFactory } from "./types.ts";
-import { isStandardProvider, standardProviderFromEnv } from "./standardProviders.ts";
+import type { AiSdkProviderPlugin, Provider } from "./types.ts";
+import { catalogProviderFromEnv, providerFromSdkModel } from "./catalogProvider.ts";
 import { discover, type DiscoverOptions, type Discovery } from "./discover.ts";
 import { resolveActiveAlias } from "@plurnk/plurnk-aliases";
 import { scopeEnvToAlias } from "./env.ts";
+import { ollamaProviderFromEnv } from "./ollama.ts";
+import { compatibleProviderFromEnv } from "./compatibleProvider.ts";
+import { contextWindowFromEnv } from "./env.ts";
 
 // Two injectable seams, both defaulting to production behavior and never passed
 // by real callers: the module importer (tests exercise the bespoke path without
@@ -33,10 +34,8 @@ const providerPackages = async (discoverFn: DiscoverFn, env: NodeJS.ProcessEnv):
     return discoveredCache;
 };
 
-// Two-tier resolution (SPEC §5): tier 1 standard table → tier 2 discovered
-// package (scope-agnostic scan, trust-gated) → fail-hard. The standard table is
-// authoritative — a scanned package whose name duplicates a standard one is
-// shadowed here (never reached), since tier 1 returns first.
+// Catalog and explicit declarations are authoritative. Discovery is the
+// extensibility seam for an AI SDK provider that neither source describes.
 export const instantiateProvider = async (
     name: string,
     env: NodeJS.ProcessEnv,
@@ -46,14 +45,13 @@ export const instantiateProvider = async (
     baseUrl?: string, // per-alias endpoint override (PLURNK_BASEURL_<alias>); threaded to both tiers
     alias?: string, // the alias this instantiation serves — scopes PLURNK_PROVIDERS_<KNOB>_<alias> overrides
 ): Promise<Provider> => {
-    // Per-alias knob scoping: overlay any _<alias>-suffixed knob onto its bare
-    // name so both tiers (and every fromEnv) read plain vars, per-alias-resolved.
+    // Per-alias knob scoping overlays _<alias>-suffixed knobs onto their bare
+    // names before any resolver reads them.
     if (alias !== undefined) env = scopeEnvToAlias(env, alias);
-    if (isStandardProvider(name)) {
-        const standard = await standardProviderFromEnv(name, env, model, baseUrl);
-        if (standard === null) throw new Error(`provider "${name}": standard registry resolution failed`);
-        return standard;
-    }
+    const catalog = catalogProviderFromEnv(name, env, model, baseUrl);
+    if (catalog !== null) return catalog;
+    if (name === "ollama") return ollamaProviderFromEnv(env, model, baseUrl === undefined ? undefined : { baseUrl });
+    if (name === "openai" || name === "plurnk") return compatibleProviderFromEnv(name, env, model, baseUrl);
     const { registry, skipped } = await providerPackages(discoverFn, env);
     const specifier = registry.get(name);
     if (specifier === undefined) {
@@ -61,7 +59,7 @@ export const instantiateProvider = async (
         if (declined !== undefined) {
             throw new Error(`provider "${name}" resolves to ${declined}, but it is untrusted under PLURNK_PLUGINS_TRUSTED_ONLY — add it to the allowlist (or publish under @plurnk/)`);
         }
-        throw new Error(`unknown provider "${name}": not a standard provider, and no installed package declares plurnk.kind:"provider" with name "${name}"`);
+        throw new Error(`unknown provider "${name}": absent from models.dev, operator declarations, local adapters, and installed AI SDK provider plugins`);
     }
     let mod: unknown;
     try {
@@ -69,11 +67,24 @@ export const instantiateProvider = async (
     } catch (cause) {
         throw new Error(`provider "${name}" resolves to ${specifier}, but importing it failed`, { cause });
     }
-    const factory = (mod as { default?: ProviderFactory }).default;
-    if (factory === undefined || typeof factory.fromEnv !== "function") {
-        throw new Error(`${specifier} default export is not a Provider factory (missing static fromEnv)`);
+    const sdkProvider = (mod as { default?: AiSdkProviderPlugin }).default;
+    if (sdkProvider === undefined || typeof sdkProvider.languageModel !== "function") {
+        throw new Error(`${specifier} default export is not an AI SDK provider (missing languageModel)`);
+    }
+    if (baseUrl !== undefined) {
+        throw new Error(`${specifier}: PLURNK_BASEURL_${alias ?? "<alias>"} cannot reconfigure an installed AI SDK provider; declare the provider through PLURNK_PROVIDERS_PROVIDER_* instead`);
+    }
+    const contextWindow = contextWindowFromEnv(env, name);
+    if (contextWindow === null) {
+        throw new Error(`${specifier}: PLURNK_PROVIDERS_CONTEXT_WINDOW must be set because Models.dev has no metadata for provider "${name}"`);
     }
-    return await factory.fromEnv(env, model, baseUrl !== undefined ? { baseUrl } : undefined);
+    return providerFromSdkModel({
+        name,
+        env,
+        model,
+        languageModel: sdkProvider.languageModel(model),
+        contextWindow,
+    });
 };
 
 // Test-only: drop the memoized discovery so a fresh scan/injection runs next.

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