@plurnk/plurnk-providers 1.3.4 → 1.3.6

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 {}
@@ -43,7 +44,7 @@ export type OpenAICompatConfig = {
     contextWindow?: number | null;              // default null; caller resolves-or-fails (#419), narrows to required with the interface
     reasoningStyle?: ReasoningStyle;          // default "none"
     countTokens?: (text: string) => number;   // default chars/2 upper-bound heuristic
-    costFor?: (usage: ProviderUsage) => number; // default () => 0
+    calculateCost?: (usage: ProviderUsage) => number; // default () => 0
     source?: string;                           // telemetry source, e.g. "provider:openai"; default "provider"
     grammarStyle?: GrammarStyle;               // how a GBNF grammar is carried; default "none" (not sent)
     // #518: send the OpenAI-standard `prompt_cache_key` set to workerId, so a
@@ -60,7 +61,6 @@ export type OpenAICompatConfig = {
     firstPartyMetadata?: boolean;              // forward per-turn attributions + client as Plurnk-* headers (plurnk only); default false
     apiKeyRejectedMessage?: string;            // #537: friendly hint when a PRESENT key is 401/403-rejected (distinct from unset); default undefined
     eosText?: string;                          // #539: server-reported eos_token, stripped from the content tail (--special renders it as text); default undefined
-    balanceMetaKey?: string;                    // top-level response field carrying account balance (pico-USD) → validated meta.balancePico (plurnk only, #23); default unset
     // Slot affinity wiring (provider-INTERNAL — never consumer-facing, #11).
     supportsSlotPinning?: boolean;             // backend accepts an `id_slot` body field (llama-server); default false
     slotCount?: number | null;                 // probed slot count for pinning backends; default null
@@ -88,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
@@ -107,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).
@@ -135,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
@@ -154,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";
@@ -235,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>;
@@ -254,10 +210,9 @@ export default class OpenAICompatProvider implements Provider {
     #dryBase: number | undefined;
     #dryAllowedLength: number | undefined;
     #repeatLastN: number | undefined;
-    #retryDelayMs: number;
     #reasoningStyle: ReasoningStyle;
     #countTokens: (text: string) => number;
-    #costFor: (usage: ProviderUsage) => number;
+    #calculateCost: (usage: ProviderUsage) => number;
     #source: string;
     #grammarStyle: GrammarStyle;
     #promptCacheKey: boolean;
@@ -265,7 +220,6 @@ export default class OpenAICompatProvider implements Provider {
     #gbnfDebug: boolean;
     #streaming: boolean;
     #firstPartyMetadata: boolean;
-    #balanceMetaKey: string | undefined;
     #supportsSlotPinning: boolean;
     #slotCount: number | null;
     #retryAttempts: number;
@@ -283,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 ?? {};
@@ -295,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;
@@ -305,11 +263,10 @@ 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;
-        this.#costFor = config.costFor ?? (() => 0);
+        this.#calculateCost = config.calculateCost ?? (() => 0);
         this.#source = config.source ?? "provider";
         this.#grammarStyle = config.grammarStyle ?? "none";
         this.#promptCacheKey = config.promptCacheKey ?? false;
@@ -320,7 +277,6 @@ export default class OpenAICompatProvider implements Provider {
         this.#apiKeyRejectedMessage = config.apiKeyRejectedMessage;
         this.#eosText = config.eosText;
         this.#hasApiKey = "Authorization" in this.#headers;
-        this.#balanceMetaKey = config.balanceMetaKey;
         this.#supportsSlotPinning = config.supportsSlotPinning ?? false;
         this.#slotCount = config.slotCount ?? null;
         this.#topLogprobs = config.topLogprobs ?? null;
@@ -370,7 +326,7 @@ export default class OpenAICompatProvider implements Provider {
     get constrainsOutput(): boolean { return this.#grammarStyle !== "none"; }
 
     countTokens(text: string): number { return this.#countTokens(text); }
-    costFor(usage: ProviderUsage): number { return this.#costFor(usage); }
+    calculateCost(usage: ProviderUsage): number { return this.#calculateCost(usage); }
 
     // Maps the reasoning INTENT (off | adaptive | on+budget, #33) to the
     // backend's wire mechanism — including under a transported grammar. The #32
@@ -566,18 +522,10 @@ export default class OpenAICompatProvider implements Provider {
     }
 
     // Per-turn metadata bag (#23): pass the backend's non-standard top-level fields
-    // (the transport's `chunkMetadata`) through VERBATIM, then normalize the known
-    // keys we hold a contract for — the spec's balance field → a validated
-    // `balancePico` (finite pico-USD; dropped if non-numeric), renamed off its raw
-    // key so the consumer reads one canonical name. Undefined when nothing's there;
-    // the service merges this into its Turn metadata and filters what reaches clients.
+    // through verbatim. Providers do not reinterpret vendor currency or account
+    // metadata; a monetary value carries its own amount and currency.
     #buildMeta(chunkMetadata: Record<string, unknown>): Record<string, unknown> | undefined {
         const meta: Record<string, unknown> = { ...chunkMetadata };
-        if (this.#balanceMetaKey !== undefined) {
-            const raw = meta[this.#balanceMetaKey];
-            delete meta[this.#balanceMetaKey];
-            if (typeof raw === "number" && Number.isFinite(raw)) meta.balancePico = raw;
-        }
         return Object.keys(meta).length > 0 ? meta : undefined;
     }
 
@@ -634,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
@@ -707,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);
@@ -725,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,
@@ -736,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

@@ -31,9 +31,9 @@ test("Mock: countTokens('') is 0; non-empty is a positive integer", () => {
     assert.ok(Number.isInteger(n) && n > 0);
 });
 
-test("Mock: costFor zero usage is 0 (free)", () => {
+test("Mock: calculateCost zero usage is 0 (free)", () => {
     const m = build();
-    assert.equal(m.costFor({ prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 }), 0);
+    assert.equal(m.calculateCost({ prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 }), 0);
 });
 
 // — Transport (SPEC §10.7, §10.10) —
@@ -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/Mock.ts

@@ -68,7 +68,7 @@ export default class Mock implements Provider {
     }
 
     // Mock is free.
-    costFor(_usage: ProviderUsage): number { return 0; }
+    calculateCost(_usage: ProviderUsage): number { return 0; }
 
     async generate({ signal }: { messages: ChatMessage[]; workerId?: string; signal?: AbortSignal }): Promise<{ assistant: MockReturnedAssistant; assistantRaw: unknown }> {
         // Honor abort before consuming the queue — an aborted call makes no

package/src/Pool.test.ts

@@ -28,7 +28,7 @@ const backend = (opts: FakeOpts = {}) => {
         ...(opts.completionReserve !== undefined ? { completionReserve: opts.completionReserve } : {}),
         ...(opts.tokenize ? { tokenize: async (t: string) => [t.length] } : {}),
         countTokens: (t: string) => t.length,
-        costFor: () => opts.cost ?? 0,
+        calculateCost: () => opts.cost ?? 0,
         generate: async (args: Parameters<Provider["generate"]>[0]): Promise<ProviderResponse> => {
             served.push(args.workerId);
             if (opts.throws !== undefined) throw opts.throws;
@@ -88,10 +88,10 @@ test("Pool: tokenize is exposed iff every backend has it", () => {
     assert.equal(new Pool([backend({ tokenize: true }).b, backend({ tokenize: false }).b]).tokenize, undefined);
 });
 
-test("Pool: countTokens + costFor delegate to a backend", () => {
+test("Pool: countTokens + calculateCost delegate to a backend", () => {
     const p = new Pool([backend({ cost: 42 }).b]);
     assert.equal(p.countTokens("abcd"), 4);
-    assert.equal(p.costFor({ prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 }), 42);
+    assert.equal(p.calculateCost({ prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 }), 42);
 });
 
 // --- dispatch: round-robin + affinity ---

package/src/Pool.ts

@@ -83,7 +83,7 @@ export default class Pool implements Provider {
     }
 
     countTokens(text: string): number { return this.#backends[0].countTokens(text); }
-    costFor(usage: ProviderUsage): number { return this.#backends[0].costFor(usage); }
+    calculateCost(usage: ProviderUsage): number { return this.#backends[0].calculateCost(usage); }
 
     // --- dispatch ---
 

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, costFor: () => 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 () => {