@plurnk/plurnk-providers 1.3.5 → 1.3.7

package/src/{OpenAICompat.ts → AiSdkProvider.ts}

@@ -1,21 +1,21 @@
-// Shared OpenAI-compatible provider. Implements the universal generate()
+// PLURNK adapter over an AI SDK language model. Implements the universal generate()
 // spine — signal merging, the SSE call, usage mapping, finishReason
 // normalization, response assembly — that every sibling had duplicated.
 //
-// Composition, not inheritance: the per-provider deltas (resolved URL, auth
-// headers, reasoning translation style, tokenizer, cost) arrive as config.
-// A sibling's fromEnv probes whatever it needs (catalog, pricing, context
-// window), builds the config, and returns `new OpenAICompatProvider(config)`.
-// Pure-config providers come from ./standardProviders.ts with no sibling at all.
+// Composition, not inheritance: an official AI SDK language model supplies the
+// ordinary vendor protocol. The compatible URL path remains only for PLURNK
+// extensions and local endpoint probes the SDK cannot represent.
 
 import type { ChatMessage, FinishReason, Provider, ProviderResponse, ProviderUsage } from "./types.ts";
 import type { Reasoning, ReserveSpec } from "./env.ts";
-import { chatCompletionStream, chatCompletion, OpenAiHttpError, isEdgeStatus, type ProviderFetch, type StreamResponse } from "./openaiStream.ts";
-import { normalizeUsage } from "./usage.ts";
-import { toProviderError, classifyProviderError, ProviderError, type TelemetryEvent } from "./telemetry.ts";
+import { executeAiSdkModel, executeOpenAICompatible } from "./aiSdkTransport.ts";
+import type { LanguageModel } from "ai";
+import { toProviderError, ProviderError, type TelemetryEvent } from "./telemetry.ts";
 import { validateGbnf, type Verdict } from "@plurnk/gbnf";
 import { emitWarningOnce } from "./warnings.ts";
 
+export type ProviderFetch = typeof globalThis.fetch;
+
 // How the reasoning intent (PLURNK_PROVIDERS_REASONING: off | adaptive | on, plus
 // REASONING_BUDGET iff on — #32/#33) translates to each backend's wire mechanism
 // (SPEC §4); the per-style mapping lives in #reasoningBody. Non-obvious ones:
@@ -33,9 +33,10 @@ export type ReasoningStyle = "none" | "think" | "include_reasoning" | "effort" |
 // service-managed constrained sampling; endpoint-owned settings are not inferred.
 export type GrammarStyle = "none" | "llamacpp";
 
-export type OpenAICompatConfig = {
+export type AiSdkProviderConfig = {
     model: string;
-    url: string;                              // fully-resolved chat-completions URL
+    url?: string;                             // OpenAI-compatible chat-completions URL
+    languageModel?: LanguageModel;            // native AI SDK provider model
     fetchTimeoutMs: number;
     streamIdleTimeoutMs?: number;             // streamed body inter-chunk deadline; zero/unset disables
     headers?: Record<string, string>;         // fully-resolved request headers (incl. auth); default {}
@@ -87,8 +88,7 @@ export type OpenAICompatConfig = {
     // DEFAULT for EVERY request, spread UNDER caller sampling (#30/endpoint#7).
     // `repeatPenalty` is the FLOOR the provider manages wherever a grammar rides
     // (greedy-under-mask loops without it, #9) — the VALUE is operator config;
-    // WHERE it applies stays mechanism. `retryDelayMs` is the transient-retry
-    // backoff base (attempt N waits retryDelayMs * 2^(N-1); Retry-After wins).
+    // WHERE it applies stays mechanism.
     temperature: number;
     repeatPenalty: number;
     // #426: anti-degeneration guard on the CLOUD path (grammarStyle "none"), where the
@@ -106,7 +106,6 @@ export type OpenAICompatConfig = {
     dryBase?: number;
     dryAllowedLength?: number;
     repeatLastN?: number;
-    retryDelayMs: number;
     // Transient-failure retry budget — REQUIRED, no in-code default
     // (PLURNK_PROVIDERS_RETRY_ATTEMPTS, a non-negative int): 0 = surface the
     // first failure; N = up to N retries on a transient error (§4, #18).
@@ -134,13 +133,6 @@ export type OpenAICompatConfig = {
     tuningFloors?: boolean;
 };
 
-// Transient classifications worth retrying: rate_limit (429) and network_failure
-// (5xx, timeout, connection reset) are transport; grammar_invalid (a 422 output
-// reject a fresh sample may satisfy, #548) rides the same bounded budget.
-// unauthorized, quota_exceeded, invalid_response, model_refused are terminal —
-// retrying just burns time and budget.
-const RETRYABLE: ReadonlySet<string> = new Set(["rate_limit", "network_failure", "grammar_invalid"]);
-
 // #539: drop trailing occurrences of a server-rendered EOG marker. llama-server
 // under --special renders EOS as literal text, so a raw-EOS-ended turn carries a
 // trailing <eos> the grammar never sanctioned. Trailing-only + exact-match, so it
@@ -153,42 +145,6 @@ const stripTrailingSpecial = (content: string, marker: string): string => {
     return out;
 };
 
-// Sleep that rejects the moment `signal` aborts (caller cancellation must not
-// wait out a backoff). Resolves normally on timeout.
-const sleepWithAbort = (ms: number, signal: AbortSignal | undefined): Promise<void> =>
-    new Promise((resolve, reject) => {
-        if (signal?.aborted) { reject(signal.reason); return; }
-        const timer = setTimeout(resolve, ms);
-        signal?.addEventListener("abort", () => { clearTimeout(timer); reject(signal.reason); }, { once: true });
-    });
-
-// SPEC §2 closed set. The four canonical values pass through; known per-backend
-// synonyms translate INTO them (anthropic max_tokens/end_turn, gemini MAX_TOKENS/
-// SAFETY/RECITATION) so a token-cap hit canonicalizes to "length" whatever the
-// backend names it -- core's `finishReason === "length"` truncation check (#425)
-// is then an invariant by construction, not a convention each backend must
-// independently honor. A non-empty value outside both the set and the table
-// collapses to null AND warns once, so a new backend's unmapped cap string
-// surfaces instead of silently becoming "no signal" (which would make core miss
-// the truncation entirely). Case-folded: gemini shouts its reasons.
-const FINISH_SYNONYMS = new Map<string, Exclude<FinishReason, null>>([
-    ["stop", "stop"], ["length", "length"], ["tool_calls", "tool_calls"], ["content_filter", "content_filter"],
-    ["max_tokens", "length"], ["model_length", "length"], ["max_completion_tokens", "length"],
-    ["end_turn", "stop"], ["stop_sequence", "stop"], ["eos_token", "stop"],
-    ["tool_use", "tool_calls"],
-    ["safety", "content_filter"], ["recitation", "content_filter"],
-]);
-const normalizeFinishReason = (raw: string | null): FinishReason => {
-    if (raw === null || raw.length === 0) return null;
-    const hit = FINISH_SYNONYMS.get(raw.toLowerCase());
-    if (hit !== undefined) return hit;
-    emitWarningOnce(
-        `unrecognized finish_reason "${raw}"; treated as no-signal (finishReason=null). If it denotes a token-cap hit, core's length-cap detection will miss it -- add it to FINISH_SYNONYMS.`,
-        "PLURNK_FINISH_REASON_UNKNOWN",
-    );
-    return null;
-};
-
 // Shared budget→effort breakpoints (xai and google had identical copies).
 export const effortFromBudget = (budget: number): "low" | "medium" | "high" => {
     if (budget <= 1000) return "low";
@@ -234,9 +190,10 @@ const describeUnenforced = (v: Exclude<Verdict, { status: "accept" }>): string =
     return `grammar not enforced: output is an incomplete match of the transported grammar — a valid prefix of ${v.pos} code points that never terminated`;
 };
 
-export default class OpenAICompatProvider implements Provider {
+export default class AiSdkProvider implements Provider {
     #model: string;
-    #url: string;
+    #url: string | undefined;
+    #languageModel: LanguageModel | undefined;
     #fetchTimeoutMs: number;
     #streamIdleTimeoutMs: number | undefined;
     #headers: Record<string, string>;
@@ -253,7 +210,6 @@ export default class OpenAICompatProvider implements Provider {
     #dryBase: number | undefined;
     #dryAllowedLength: number | undefined;
     #repeatLastN: number | undefined;
-    #retryDelayMs: number;
     #reasoningStyle: ReasoningStyle;
     #countTokens: (text: string) => number;
     #calculateCost: (usage: ProviderUsage) => number;
@@ -281,9 +237,13 @@ export default class OpenAICompatProvider implements Provider {
     // the honest capability signal for every other backend.
     tokenize?: (text: string) => Promise<number[]>;
 
-    constructor(config: OpenAICompatConfig) {
+    constructor(config: AiSdkProviderConfig) {
         this.#model = config.model;
         this.#url = config.url;
+        this.#languageModel = config.languageModel;
+        if ((this.#url === undefined) === (this.#languageModel === undefined)) {
+            throw new Error(`${config.source ?? "provider"}: configure exactly one AI SDK model or OpenAI-compatible URL`);
+        }
         this.#fetchTimeoutMs = config.fetchTimeoutMs;
         this.#streamIdleTimeoutMs = config.streamIdleTimeoutMs;
         this.#headers = config.headers ?? {};
@@ -293,8 +253,8 @@ export default class OpenAICompatProvider implements Provider {
         // Loud guard: an out-of-date consumer (stale plugin dist) omitting the
         // required tuning fields must fail at construction, not silently send
         // undefined sampling on every grammar request.
-        if (typeof config.temperature !== "number" || typeof config.repeatPenalty !== "number" || typeof config.retryDelayMs !== "number") {
-            throw new Error(`${config.source ?? "provider"}: OpenAICompatConfig requires temperature + repeatPenalty + retryDelayMs (PLURNK_PROVIDERS_TEMPERATURE / _REPEAT_PENALTY / _RETRY_DELAY) — rebuild against providers >= 0.33.0`);
+        if (typeof config.temperature !== "number" || typeof config.repeatPenalty !== "number") {
+            throw new Error(`${config.source ?? "provider"}: AiSdkProviderConfig requires temperature + repeatPenalty (PLURNK_PROVIDERS_TEMPERATURE / _REPEAT_PENALTY)`);
         }
         this.#temperature = config.temperature;
         this.#repeatPenalty = config.repeatPenalty;
@@ -303,7 +263,6 @@ export default class OpenAICompatProvider implements Provider {
         this.#dryBase = config.dryBase;
         this.#dryAllowedLength = config.dryAllowedLength;
         this.#repeatLastN = config.repeatLastN;
-        this.#retryDelayMs = config.retryDelayMs;
         this.#retryAttempts = config.retryAttempts;
         this.#reasoningStyle = config.reasoningStyle ?? "none";
         this.#countTokens = config.countTokens ?? heuristicTokens;
@@ -623,61 +582,65 @@ export default class OpenAICompatProvider implements Provider {
             ...(this.#promptCacheKey ? { prompt_cache_key: workerId } : {}),
         };
 
-        // Transient-failure retry (#18). Each attempt gets a FRESH fetch timeout
-        // (the budget is per-request, not shared across retries); the caller's
-        // signal spans them all. Retry only the transient classifications, prefer
-        // a server Retry-After over the backoff, and let the caller's abort cut
-        // through both the in-flight request and the backoff sleep.
-        const transport = this.#streaming ? chatCompletionStream : chatCompletion;
-
         // Per-request headers = static auth/routing + any first-party telemetry.
         const metaHeaders = this.#metadataHeaders(attributions, client, strikes, workerId, primaryWorkerId, workspaceId, loop, turn);
         const headers = Object.keys(metaHeaders).length > 0 ? { ...this.#headers, ...metaHeaders } : this.#headers;
-        const transportRetries: Array<{ attempt: number; kind: string; elapsedMs: number; message: string }> = [];
         let raw;
-        for (let attempt = 0; ; attempt++) {
-            const attemptStarted = performance.now();
-            const timeoutSignal = AbortSignal.timeout(this.#fetchTimeoutMs);
-            const effectiveSignal = signal !== undefined ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-            try {
-                raw = await transport({
-                    url: this.#url,
+        try {
+            raw = this.#languageModel === undefined
+                ? await executeOpenAICompatible({
+                    url: this.#url!,
+                    model: this.#model,
                     headers,
                     body,
-                    signal: effectiveSignal,
+                    messages,
+                    signal,
                     fetch: this.#fetch,
+                    fetchTimeoutMs: this.#fetchTimeoutMs,
+                    streamIdleTimeoutMs: this.#streamIdleTimeoutMs,
+                    retryAttempts: this.#retryAttempts,
+                    streaming: this.#streaming,
                     captureRawBody: this.#rawBody,
+                })
+                : await executeAiSdkModel({
+                    languageModel: this.#languageModel,
+                    headers,
+                    messages,
+                    signal,
+                    fetchTimeoutMs: this.#fetchTimeoutMs,
                     streamIdleTimeoutMs: this.#streamIdleTimeoutMs,
+                    retryAttempts: this.#retryAttempts,
+                    streaming: this.#streaming,
+                    captureRawBody: this.#rawBody,
+                    temperature: this.#tuningFloors
+                        ? (typeof sampling?.temperature === "number" ? sampling.temperature : this.#temperature)
+                        : typeof sampling?.temperature === "number" ? sampling.temperature : undefined,
+                    topP: typeof sampling?.top_p === "number" ? sampling.top_p : undefined,
+                    topK: typeof sampling?.top_k === "number" ? sampling.top_k : undefined,
+                    presencePenalty: typeof sampling?.presence_penalty === "number" ? sampling.presence_penalty : undefined,
+                    frequencyPenalty: typeof sampling?.frequency_penalty === "number"
+                        ? sampling.frequency_penalty
+                        : this.#tuningFloors && this.#frequencyPenalty > 0 ? this.#frequencyPenalty : undefined,
+                    stopSequences: typeof sampling?.stop === "string"
+                        ? [sampling.stop]
+                        : Array.isArray(sampling?.stop) && sampling.stop.every((value) => typeof value === "string")
+                            ? sampling.stop
+                            : undefined,
+                    seed: typeof sampling?.seed === "number" ? sampling.seed : undefined,
+                    maxOutputTokens: maxTokens,
+                    reasoning: this.#reasoning.mode === "off"
+                        ? "none"
+                        : this.#reasoning.mode === "adaptive"
+                            ? "provider-default"
+                            : effortFromBudget(this.#reasoning.budget!),
                 });
-                break;
-            } catch (err) {
-                // Caller-initiated abort is cancellation — never retried or wrapped.
-                if (signal?.aborted) throw err;
-                const { kind } = classifyProviderError(err);
-                // #543: Cloudflare/CDN edge codes (520-527) classify as network_failure
-                // but fail-fast - a retry just re-incurs the same origin/edge timeout.
-                const edgeTimeout = err instanceof OpenAiHttpError && isEdgeStatus(err.status);
-                // Terminal kind, edge failure, or budget spent -> surface the failure.
-                if (!RETRYABLE.has(kind) || edgeTimeout || attempt >= this.#retryAttempts) {
-                    const pe = toProviderError(err, this.#source);
-                    // #537 case 2: a 401/403 with a key PRESENT is a rejected key, not a
-                    // transport failure — surface the distinct, actionable hint (kind stays
-                    // "unauthorized", so core's routing is unchanged) rather than the raw
-                    // upstream JSON. Distinct from the unset-key throw at construction.
-                    if ((pe.status === 401 || pe.status === 403) && this.#hasApiKey && this.#apiKeyRejectedMessage !== undefined) {
-                        throw new ProviderError(this.#source, "unauthorized", this.#apiKeyRejectedMessage, { status: pe.status, cause: err });
-                    }
-                    throw pe;
-                }
-                transportRetries.push({
-                    attempt: attempt + 1,
-                    kind,
-                    elapsedMs: Math.round(performance.now() - attemptStarted),
-                    message: err instanceof Error ? err.message : String(err),
-                });
-                const retryAfter = err instanceof OpenAiHttpError ? err.retryAfter : null;
-                await sleepWithAbort(retryAfter ?? this.#retryDelayMs * 2 ** attempt, signal);
+        } catch (err) {
+            if (signal?.aborted) throw err;
+            const pe = toProviderError(err, this.#source);
+            if ((pe.status === 401 || pe.status === 403) && this.#hasApiKey && this.#apiKeyRejectedMessage !== undefined) {
+                throw new ProviderError(this.#source, "unauthorized", this.#apiKeyRejectedMessage, { status: pe.status, cause: err });
             }
+            throw pe;
         }
 
         // #539: llama-server --special renders EOG tokens as text, so a turn ending
@@ -696,7 +659,7 @@ export default class OpenAICompatProvider implements Provider {
         // Discard/retry/escalate/self-correct is the consumer's policy.
         let telemetry: TelemetryEvent[] | undefined;
         let railsMeta: Record<string, unknown> | undefined;
-        const usage = normalizeUsage(raw.usage, raw.reasoning_content, raw.content);
+        const usage = raw.usage;
         const observedGrammar = sendGrammar ?? (wantGrammar && this.#gbnfDebug ? grammar : undefined);
         if (observedGrammar !== undefined) {
             const verdict = this.#grammarVerdict(observedGrammar, raw.content);
@@ -714,7 +677,7 @@ export default class OpenAICompatProvider implements Provider {
             // invisible, billed (12,288 billed vs 1,033 chars visible, live).
             // countTokens OVERCOUNTS text (chars/2 upper bound), so billed
             // exceeding visible-plus-slack is real vanishing, not estimator noise.
-            const visible = this.#countTokens(raw.content) + this.#countTokens(raw.reasoning_content);
+            const visible = this.#countTokens(raw.content) + this.#countTokens(raw.reasoning);
             if (sendGrammar !== undefined && usage.completion > visible + 64) {
                 (telemetry ??= []).push({
                     source: this.#source,
@@ -725,30 +688,23 @@ export default class OpenAICompatProvider implements Provider {
             }
         }
 
-        const builtMeta = this.#buildMeta(raw.chunkMetadata);
-        const retryMeta = transportRetries.length > 0 ? { transportRetries } : undefined;
-        const meta = railsMeta !== undefined || retryMeta !== undefined
-            ? { ...builtMeta, ...railsMeta, ...retryMeta }
-            : builtMeta;
-
-        // #36: surface per-token logprobs + their mean when the backend returned
-        // them (only possible when the flag requested them). Absent otherwise —
-        // never synthesized.
-        const logprobs = raw.logprobs !== null && raw.logprobs.length > 0 ? raw.logprobs : undefined;
+        const builtMeta = this.#buildMeta(raw.metadata);
+        const meta = railsMeta !== undefined ? { ...builtMeta, ...railsMeta } : builtMeta;
+        const logprobs = raw.logprobs.length > 0 ? raw.logprobs : undefined;
         const meanLogprob = logprobs !== undefined
-            ? logprobs.reduce((sum, t) => sum + t.logprob, 0) / logprobs.length
+            ? logprobs.reduce((sum, token) => sum + token.logprob, 0) / logprobs.length
             : undefined;
 
         return {
             assistant: {
                 content: raw.content,
-                reasoning: raw.reasoning_content.length > 0 ? raw.reasoning_content : null,
-                // #482: sealed relay blobs ride only when present — same absence
-                // discipline as logprobs (never synthesized, never empty-array).
-                ...(raw.reasoning_encrypted.length > 0 ? { reasoningEncrypted: raw.reasoning_encrypted } : {}),
+                reasoning: raw.reasoning.length > 0 ? raw.reasoning : null,
+                ...(raw.reasoningEncrypted.length > 0
+                    ? { reasoningEncrypted: raw.reasoningEncrypted }
+                    : {}),
                 usage,
-                finishReason: normalizeFinishReason(raw.finish_reason),
-                model: raw.model ?? this.#model,
+                finishReason: raw.finishReason,
+                model: raw.model,
                 ...(logprobs !== undefined ? { logprobs, meanLogprob } : {}),
             },
             assistantRaw: raw,

package/src/Mock.test.ts

@@ -109,7 +109,7 @@ test("Mock: exhausted queue throws a specific error", async () => {
 // -- #507: the reserve surface lives on the Provider CONTRACT, and Mock drives core's partition suite --
 
 test("#507 the reserve getters are on the Provider interface (not just the concrete class)", () => {
-    // Typing against the CONTRACT is the check a getter-only-on-OpenAICompat surface fails.
+    // Typing against the contract catches a getter-only concrete surface.
     const prevR = process.env.PLURNK_PROVIDERS_REASONING_RESERVE;
     try {
         process.env.PLURNK_PROVIDERS_REASONING_RESERVE = "10%";

package/src/ProviderRegistry.test.ts

@@ -2,7 +2,6 @@ import test, { mock } from "node:test";
 import { strict as assert } from "node:assert";
 import { instantiateProvider, loadActiveProvider, resetDiscoveryCache } from "./ProviderRegistry.ts";
 
-const fakeProvider = { contextWindow: 1, model: "m", countTokens: () => 0, calculateCost: () => 0, generate: async () => { throw new Error("unused"); } };
 const mapOf = (entries: Record<string, string>, skipped: Record<string, string> = {}) =>
     async () => ({ registry: new Map(Object.entries(entries)), skipped: new Map(Object.entries(skipped)), attributions: new Map<string, string | string[]>() });
 
@@ -10,16 +9,16 @@ const mapOf = (entries: Record<string, string>, skipped: Record<string, string>
 // exercise the resolution + two-tier instantiation this module owns; the active
 // alias is driven end-to-end by loadActiveProvider below.
 
-// — two-tier instantiation (SPEC §5) —
+// — provider resolution (SPEC §5) —
 
 const fullEnv = Object.freeze({
     PLURNK_PROVIDERS_FETCH_TIMEOUT: "600000",
     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.4", PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%", PLURNK_PROVIDERS_RETRY_DELAY: "1", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
+    PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_TEMPERATURE: "0.2", PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15", PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0.4", PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0", PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
     OPENAI_BASE_URL: "http://x",
 });
 
-test("instantiateProvider: standard name resolves in-framework, no scan, no import", async () => {
+test("instantiateProvider: cataloged name resolves in-framework, no scan, no import", async () => {
     resetDiscoveryCache();
     mock.method(globalThis, "fetch", async (url: string) => {
         if (String(url).endsWith("/models")) return new Response(JSON.stringify({ data: [] }), { status: 200 });
@@ -36,24 +35,33 @@ test("instantiateProvider: standard name resolves in-framework, no scan, no impo
     mock.restoreAll();
 });
 
-test("instantiateProvider: bespoke name resolves via the scan and imports the discovered package", async () => {
+test("instantiateProvider: an installed AI SDK provider resolves through discovery", async () => {
     resetDiscoveryCache();
     const calls: unknown[] = [];
-    const p = await instantiateProvider("openrouter", { ...fullEnv }, "anthropic/claude-opus-latest",
-        async (specifier) => { calls.push(specifier); return { default: { fromEnv: async (_e: NodeJS.ProcessEnv, model: string) => { calls.push(model); return fakeProvider; } } }; },
-        mapOf({ openrouter: "@plurnk/plurnk-providers-openrouter" }));
-    assert.equal(p, fakeProvider);
-    assert.deepEqual(calls, ["@plurnk/plurnk-providers-openrouter", "anthropic/claude-opus-latest"]);
+    const p = await instantiateProvider("acme", { ...fullEnv, PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192" }, "model-a",
+        async (specifier) => {
+            calls.push(specifier);
+            return { default: { languageModel: (model: string) => { calls.push(model); return {} as never; } } };
+        },
+        mapOf({ acme: "@acme/ai-provider" }));
+    assert.equal(p.model, "model-a");
+    assert.equal(p.contextWindow, 8192);
+    assert.deepEqual(calls, ["@acme/ai-provider", "model-a"]);
 });
 
-test("instantiateProvider: a per-alias baseUrl is passed to a bespoke factory as the 3rd-arg option", async () => {
+test("instantiateProvider: a per-alias baseUrl drives the built-in Ollama probe", async () => {
     resetDiscoveryCache();
-    let received: unknown;
+    const calls: string[] = [];
+    mock.method(globalThis, "fetch", async (url: string) => {
+        calls.push(String(url));
+        return new Response(JSON.stringify({ model_info: { "qwen.context_length": 32768 } }));
+    });
     await instantiateProvider("ollama", { ...fullEnv }, "qwen2.5-coder",
-        async () => ({ default: { fromEnv: async (_e: NodeJS.ProcessEnv, _m: string, options?: unknown) => { received = options; return fakeProvider; } } }),
-        mapOf({ ollama: "@plurnk/plurnk-providers-ollama" }),
+        async () => ({}),
+        mapOf({}),
         "http://nook:11434");
-    assert.deepEqual(received, { baseUrl: "http://nook:11434" });
+    assert.deepEqual(calls, ["http://nook:11434/api/show"]);
+    mock.restoreAll();
 });
 
 test("instantiateProvider: a per-alias baseUrl drives the standard openai probe to the override host", async () => {
@@ -74,14 +82,14 @@ test("instantiateProvider: a per-alias baseUrl drives the standard openai probe
 test("instantiateProvider: a THIRD-PARTY scope is discovered — name maps to its package", async () => {
     resetDiscoveryCache();
     const imports: string[] = [];
-    const p = await instantiateProvider("foo", { ...fullEnv }, "m",
-        async (specifier) => { imports.push(specifier); return { default: { fromEnv: async () => fakeProvider } }; },
+    const p = await instantiateProvider("foo", { ...fullEnv, PLURNK_PROVIDERS_CONTEXT_WINDOW: "4096" }, "m",
+        async (specifier) => { imports.push(specifier); return { default: { languageModel: () => ({} as never) } }; },
         mapOf({ foo: "@acme/acme-provider-foo" }));
-    assert.equal(p, fakeProvider);
+    assert.equal(p.model, "m");
     assert.deepEqual(imports, ["@acme/acme-provider-foo"]); // not an @plurnk/ specifier
 });
 
-test("instantiateProvider: a standard name is authoritative — a scanned package of the same name is shadowed", async () => {
+test("instantiateProvider: a cataloged name is authoritative — a scanned package of the same name is shadowed", async () => {
     resetDiscoveryCache();
     mock.method(globalThis, "fetch", async (url: string) => {
         if (String(url).endsWith("/models")) return new Response(JSON.stringify({ data: [] }), { status: 200 });
@@ -100,7 +108,7 @@ test("instantiateProvider: unknown provider throws — no standard, no discovere
     resetDiscoveryCache();
     await assert.rejects(
         () => instantiateProvider("nope", { ...fullEnv }, "m", async () => ({}), mapOf({})),
-        /unknown provider "nope": not a standard provider, and no installed package declares plurnk\.kind:"provider" with name "nope"/,
+        /unknown provider "nope"/,
     );
 });
 
@@ -116,13 +124,13 @@ test("instantiateProvider: an untrusted (skipped) provider gives a precise error
     assert.deepEqual(imports, []); // never imported an untrusted package
 });
 
-test("instantiateProvider: discovered package without a fromEnv factory throws (factory shape, SPEC )", async () => {
+test("instantiateProvider: discovered package must export an AI SDK provider", async () => {
     resetDiscoveryCache();
     await assert.rejects(
         () => instantiateProvider("broken", { ...fullEnv }, "m",
             async () => ({ default: {} }),
             mapOf({ broken: "@acme/acme-provider-broken" })),
-        /@acme\/acme-provider-broken default export is not a Provider factory/,
+        /@acme\/acme-provider-broken default export is not an AI SDK provider/,
     );
 });
 
@@ -174,6 +182,8 @@ test("#622: two Fireworks aliases independently select default and priority serv
         FIREWORKS_BASE_URL: "https://api.fireworks.ai/inference/v1",
         FIREWORKS_API_KEY: "fw",
         PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192",
+        PLURNK_PROVIDERS_PROVIDER_FIREWORKS_REASONING_STYLE: "effort_explicit",
+        PLURNK_PROVIDERS_TOP_LOGPROBS: "2",
         PLURNK_PROVIDERS_SERVICE_TIER_fast: "priority",
         PLURNK_PROVIDERS_SERVICE_TIER_standard: "default",
     };
@@ -184,6 +194,9 @@ test("#622: two Fireworks aliases independently select default and priority serv
     await fast.generate({ workerId: "fast-worker", messages: [] });
     await standard.generate({ workerId: "standard-worker", messages: [] });
     assert.deepEqual(bodies.map((body) => body.service_tier), ["priority", "default"]);
+    assert.deepEqual(bodies.map((body) => body.prompt_cache_key), ["fast-worker", "standard-worker"]);
+    assert.deepEqual(bodies.map((body) => body.reasoning_effort), ["none", "none"]);
+    assert.deepEqual(bodies.map((body) => body.top_logprobs), [2, 2]);
     assert.deepEqual(bodies.map((body) => body.model), [
         "accounts/fireworks/routers/glm-5p2-fast",
         "accounts/fireworks/models/deepseek-v4-pro",
@@ -191,13 +204,13 @@ test("#622: two Fireworks aliases independently select default and priority serv
     mock.restoreAll();
 });
 
-test("loadActiveProvider: resolves the alias cascade end-to-end via the scan", async () => {
+test("loadActiveProvider: resolves the alias cascade to an installed AI SDK provider", async () => {
     resetDiscoveryCache();
-    const env = { ...fullEnv, PLURNK_MODEL: "opus", PLURNK_MODEL_opus: "openrouter/anthropic/claude-opus-latest" } as NodeJS.ProcessEnv;
+    const env = { ...fullEnv, PLURNK_PROVIDERS_CONTEXT_WINDOW: "4096", PLURNK_MODEL: "custom", PLURNK_MODEL_custom: "acme/model-a" } as NodeJS.ProcessEnv;
     const p = await loadActiveProvider(env,
-        async () => ({ default: { fromEnv: async () => fakeProvider } }),
-        mapOf({ openrouter: "@plurnk/plurnk-providers-openrouter" }));
-    assert.equal(p, fakeProvider);
+        async () => ({ default: { languageModel: () => ({} as never) } }),
+        mapOf({ acme: "@acme/ai-provider" }));
+    assert.equal(p.model, "model-a");
 });
 
 test("loadActiveProvider: throws a named error when no alias is active", async () => {

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.