@plurnk/plurnk-providers 1.7.0 → 1.8.0

package/src/sdkModels.ts

@@ -9,7 +9,13 @@ import { createOpenAI } from "@ai-sdk/openai";
 import { createTogetherAI } from "@ai-sdk/togetherai";
 import { createXai } from "@ai-sdk/xai";
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
-import { lookupProvider, type ProviderInfo } from "@plurnk/plurnk-models";
+import {
+    isProviderCredentialName,
+    lookupProvider,
+    providerCatalogSnapshot,
+    type ProviderInfo,
+} from "@plurnk/plurnk-models";
+import { Validator, type ModelReadiness, type ModelReadinessCause } from "@plurnk/plurnk-contracts";
 import type { LanguageModel } from "ai";
 import { providerCostNormalizer } from "./accounting.ts";
 import type { AiSdkProviderOptions, CacheAffinity } from "./AiSdkProvider.ts";
@@ -30,10 +36,57 @@ export type SdkModel = {
 };
 
 const cacheControl = { type: "ephemeral" as const };
+// The release generator admits only packages implemented by this package.
+// Derive runtime readiness from that same pinned provider projection instead
+// of maintaining a second support list beside the construction switch.
+const supportedSdkPackages = new Set(
+    Object.values(providerCatalogSnapshot()).map(({ npm }) => npm),
+);
+
+const openRouterHeaders = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+): Readonly<Record<string, string>> => {
+    if (catalog.id !== "openrouter") return {};
+    if (env.OPENROUTER_X_TITLE !== undefined) {
+        throw new Error(`${provider} provider: OPENROUTER_X_TITLE was renamed to OPENROUTER_APP_TITLE.`);
+    }
+    const referer = env.OPENROUTER_HTTP_REFERER?.trim();
+    if (referer === undefined || referer === "") return {};
+    let parsed: URL;
+    try {
+        parsed = new URL(referer);
+    } catch (cause) {
+        throw new Error(`${provider} provider: OPENROUTER_HTTP_REFERER must be an absolute HTTP(S) URL.`, { cause });
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`${provider} provider: OPENROUTER_HTTP_REFERER must be an absolute HTTP(S) URL.`);
+    }
+    const title = env.OPENROUTER_APP_TITLE?.trim();
+    return {
+        "HTTP-Referer": parsed.href,
+        ...(title === undefined || title === "" ? {} : { "X-OpenRouter-Title": title }),
+    };
+};
 
 const envPrefix = (provider: string): string =>
     provider.replaceAll(/[^a-zA-Z0-9]/g, "_").toUpperCase();
 
+// {§provider-fact-authority} — one credential declaration holds exactly one
+// name. An ordered fallback list would paper over an operator/catalog naming
+// mismatch; that mismatch belongs at its owning boundary instead.
+const singleCredentialName = (provider: string, value: string): string => {
+    const name = value.trim();
+    if (name.length === 0) throw new Error(`${provider} provider: API_KEY_ENV must name one environment variable.`);
+    if (name.includes(",")) {
+        throw new Error(
+            `${provider} provider: API_KEY_ENV holds one exact name, never an ordered fallback; reconcile the operator environment with the Models.dev contract instead.`,
+        );
+    }
+    return name;
+};
+
 export const configuredProviderInfo = (
     provider: string,
     env: NodeJS.ProcessEnv,
@@ -41,13 +94,14 @@ export const configuredProviderInfo = (
     const prefix = `PLURNK_PROVIDERS_PROVIDER_${envPrefix(provider)}`;
     const npm = env[`${prefix}_NPM`];
     if (npm === undefined || npm.length === 0) return null;
-    const keyNames = env[`${prefix}_API_KEY_ENV`]
-        ?.split(",")
-        .map((name) => name.trim())
-        .filter(Boolean) ?? [];
+    const declared = env[`${prefix}_API_KEY_ENV`];
+    const keyNames = declared === undefined
+        ? []
+        : [singleCredentialName(provider, declared)];
     const api = env[`${prefix}_BASE_URL`];
     return {
         id: provider,
+        name: provider,
         npm,
         env: keyNames,
         ...(api === undefined || api.length === 0 ? {} : { api }),
@@ -62,6 +116,11 @@ const firstSet = (env: NodeJS.ProcessEnv, names: readonly string[]): string | un
     return undefined;
 };
 
+const isSet = (env: NodeJS.ProcessEnv, name: string): boolean => {
+    const value = env[name];
+    return value !== undefined && value.length > 0;
+};
+
 const configuredKeyNames = (
     provider: string,
     env: NodeJS.ProcessEnv,
@@ -70,7 +129,125 @@ const configuredKeyNames = (
     const configured = env[`PLURNK_PROVIDERS_PROVIDER_${envPrefix(provider)}_API_KEY_ENV`];
     return configured === undefined || configured.length === 0
         ? catalog.env
-        : configured.split(",").map((name) => name.trim()).filter(Boolean);
+        : [singleCredentialName(provider, configured)];
+};
+
+const credentialCandidates = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+): readonly string[] => {
+    const names = configuredKeyNames(provider, env, catalog);
+    const credentials = names.filter(isProviderCredentialName);
+    return credentials.length > 0 ? credentials : names;
+};
+
+const configuredBaseUrl = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+    override?: string,
+): string | undefined => {
+    const prefix = envPrefix(provider);
+    return override
+        ?? env[`PLURNK_PROVIDERS_PROVIDER_${prefix}_BASE_URL`]
+        ?? env[`${prefix}_BASE_URL`]
+        ?? catalog.api;
+};
+
+const templateEnvironmentNames = (value: string | undefined): readonly string[] => value === undefined
+    ? []
+    : [...new Set([...value.matchAll(/\$\{([A-Z0-9_]+)\}/g)].map((match) => match[1]!))];
+
+const missingCause = (
+    kind: ModelReadinessCause["kind"],
+    alternatives: readonly (readonly string[])[],
+): ModelReadinessCause => ({
+    kind,
+    alternatives: alternatives.map((alternative) => [...alternative]) as ModelReadinessCause["alternatives"],
+});
+
+const bedrockReadinessCauses = (
+    env: NodeJS.ProcessEnv,
+    hasExplicitBaseUrl: boolean,
+): ModelReadinessCause[] => {
+    const bearer = isSet(env, "AWS_BEARER_TOKEN_BEDROCK");
+    const sigv4 = isSet(env, "AWS_ACCESS_KEY_ID") && isSet(env, "AWS_SECRET_ACCESS_KEY");
+    const region = isSet(env, "AWS_REGION") || isSet(env, "AWS_DEFAULT_REGION");
+    if (bearer) {
+        return hasExplicitBaseUrl || region
+            ? []
+            : [missingCause("configuration", [["AWS_REGION"], ["AWS_DEFAULT_REGION"]])];
+    }
+    if (sigv4) {
+        return region
+            ? []
+            : [missingCause("configuration", [["AWS_REGION"], ["AWS_DEFAULT_REGION"]])];
+    }
+    return [missingCause("credential", hasExplicitBaseUrl
+        ? [
+            ["AWS_BEARER_TOKEN_BEDROCK"],
+            ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
+            ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_DEFAULT_REGION"],
+        ]
+        : [
+            ["AWS_BEARER_TOKEN_BEDROCK", "AWS_REGION"],
+            ["AWS_BEARER_TOKEN_BEDROCK", "AWS_DEFAULT_REGION"],
+            ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
+            ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_DEFAULT_REGION"],
+        ])];
+};
+
+// Local evidence only: this shares the exact environment and endpoint rules
+// used by createSdkModel, but never probes a provider or validates a secret.
+export const providerReadiness = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    baseUrlOverride?: string,
+): ModelReadiness | null => {
+    const catalog = lookupProvider(provider) ?? configuredProviderInfo(provider, env);
+    if (catalog === null) return null;
+    if (!supportedSdkPackages.has(catalog.npm)) return null;
+    const rawUrl = configuredBaseUrl(provider, env, catalog, baseUrlOverride);
+    const missingCoordinates = templateEnvironmentNames(rawUrl).filter((name) => !isSet(env, name));
+    const causes: ModelReadinessCause[] = missingCoordinates.length === 0
+        ? []
+        : [missingCause("configuration", [missingCoordinates])];
+
+    if (catalog.npm === "@ai-sdk/amazon-bedrock") {
+        causes.push(...bedrockReadinessCauses(env, rawUrl !== undefined));
+    } else {
+        const candidates = credentialCandidates(provider, env, catalog);
+        const credentialRequired = catalog.npm !== "@ai-sdk/openai-compatible" || candidates.length > 0;
+        if (credentialRequired && candidates.length === 0) {
+            causes.push(missingCause("configuration", [[
+                `PLURNK_PROVIDERS_PROVIDER_${envPrefix(provider)}_API_KEY_ENV`,
+            ]]));
+        } else if (credentialRequired && firstSet(env, candidates) === undefined) {
+            causes.push(missingCause("credential", candidates.map((name) => [name])));
+        }
+        if (catalog.npm === "@ai-sdk/openai-compatible" && rawUrl === undefined) {
+            const prefix = envPrefix(provider);
+            causes.push(missingCause("configuration", [
+                [`PLURNK_PROVIDERS_PROVIDER_${prefix}_BASE_URL`],
+                [`${prefix}_BASE_URL`],
+            ]));
+        }
+    }
+    return Validator.assertModelReadiness({ ready: causes.length === 0, causes });
+};
+
+const assertProviderReady = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    baseUrlOverride?: string,
+): void => {
+    const readiness = providerReadiness(provider, env, baseUrlOverride);
+    if (readiness === null || readiness.ready) return;
+    const requirements = readiness.causes
+        .map(({ alternatives }) => alternatives.map((group) => group.join(" and ")).join(" or "))
+        .join("; ");
+    throw new Error(`${provider} provider: ${requirements} must be set`);
 };
 
 const expandEnv = (value: string, env: NodeJS.ProcessEnv, provider: string): string =>
@@ -88,11 +265,11 @@ const baseUrl = (
     catalog: ProviderInfo,
     override?: string,
 ): string | undefined => {
-    const prefix = envPrefix(provider);
-    const configured = env[`PLURNK_PROVIDERS_PROVIDER_${prefix}_BASE_URL`]
-        ?? env[`${prefix}_BASE_URL`]
-        ?? catalog.api;
-    const value = override ?? configured;
+    // {§provider-fact-authority} — distinct sources, one precedence: the PLURNK
+    // knob, then the provider-native convention (OPENAI_BASE_URL etc.), then
+    // the catalog. This is not an alias fallback: each source is a different
+    // owner, and the catalog remains the last authority.
+    const value = configuredBaseUrl(provider, env, catalog, override);
     return value === undefined ? undefined : expandEnv(value, env, provider).replace(/\/+$/, "");
 };
 
@@ -101,9 +278,11 @@ const requireApiKey = (
     env: NodeJS.ProcessEnv,
     catalog: ProviderInfo,
 ): string => {
-    const names = configuredKeyNames(provider, env, catalog);
-    const key = firstSet(env, names);
-    if (key === undefined) throw new Error(`${provider} provider: ${names.join(" or ")} must be set`);
+    // {§provider-fact-authority} — a catalog `env` list mixes credentials with
+    // non-secret coordinates; the credential is the credential-named one.
+    const candidates = credentialCandidates(provider, env, catalog);
+    const key = firstSet(env, candidates);
+    if (key === undefined) throw new Error(`${provider} provider: ${candidates.join(" or ")} must be set`);
     return key;
 };
 
@@ -115,6 +294,10 @@ export const createSdkModel = (
 ): SdkModel | null => {
     const catalog = lookupProvider(provider) ?? configuredProviderInfo(provider, env);
     if (catalog === null) return null;
+    if (!supportedSdkPackages.has(catalog.npm)) {
+        throw new Error(`${provider} provider: Models.dev declares unsupported AI SDK package ${catalog.npm}`);
+    }
+    assertProviderReady(provider, env, baseUrlOverride);
     const url = baseUrl(provider, env, catalog, baseUrlOverride);
     const normalizeCost = providerCostNormalizer(catalog.npm);
 
@@ -192,7 +375,9 @@ export const createSdkModel = (
                     apiKey: env.AWS_BEARER_TOKEN_BEDROCK,
                     baseURL: url,
                 }).languageModel(model),
-                additiveReasoningProvider: "bedrock",
+                ...(model.includes("anthropic")
+                    ? { additiveReasoningProvider: "bedrock" as const }
+                    : {}),
                 catalog,
             };
         case "@openrouter/ai-sdk-provider":
@@ -200,10 +385,7 @@ export const createSdkModel = (
                 languageModel: createOpenRouter({
                     apiKey: requireApiKey(provider, env, catalog),
                     baseURL: url,
-                    headers: {
-                        ...(env.OPENROUTER_HTTP_REFERER === undefined ? {} : { "HTTP-Referer": env.OPENROUTER_HTTP_REFERER }),
-                        ...(env.OPENROUTER_X_TITLE === undefined ? {} : { "X-Title": env.OPENROUTER_X_TITLE }),
-                    },
+                    headers: openRouterHeaders(provider, env, catalog),
                 }).languageModel(model),
                 ...(catalog.id === "openrouter"
                     ? { cacheAffinity: { target: "header" as const, name: "x-session-id" } }

package/src/types.ts

@@ -12,6 +12,7 @@ import type {
 import type {
     ProviderCost,
     ProviderRequestAccounting,
+    ReasoningPolicy,
 } from "@plurnk/plurnk-contracts";
 
 export type {
@@ -19,8 +20,21 @@ export type {
     ProviderCost,
     ProviderRequestAccounting,
     ProviderUsage,
+    ReasoningPolicy,
 } from "@plurnk/plurnk-contracts";
 
+export class UnsupportedReasoningPolicyError extends Error {
+    readonly policy: ReasoningPolicy;
+    readonly supported: readonly ReasoningPolicy[];
+
+    constructor(source: string, policy: ReasoningPolicy, supported: readonly ReasoningPolicy[]) {
+        super(`${source}: reasoning policy '${policy}' is unsupported; supported policies: ${supported.join(", ")}`);
+        this.name = "UnsupportedReasoningPolicyError";
+        this.policy = policy;
+        this.supported = supported;
+    }
+}
+
 export interface ChatMessage {
     role: "system" | "user" | "assistant";
     content: string;
@@ -277,6 +291,8 @@ export interface Provider {
     readonly maxOutputTokens: number | null;
     readonly outputBudget: number | null;
     readonly reasoningBudget: number | null;
+    // Exact durable policies this adapter can represent without coercion.
+    readonly supportedReasoningPolicies: readonly ReasoningPolicy[];
     readonly inputCapacity: number | null;
     readonly model: string;
     // Optional: the backend's self-reported served model id, from a