@tokenbuddy/tokenbuddy 1.0.31 → 1.0.33

package/src/doctor-diagnostics.ts

@@ -18,6 +18,7 @@ import {
   readDoctorClawtipWallet,
   type DoctorClawtipWalletSummary,
 } from "./doctor-clawtip-wallet.js";
+import type { PublicManualProviderConfig } from "./provider-routing-config.js";
 
 /**
  * `tb doctor` 输出里 provider 行的形状。
@@ -55,6 +56,8 @@ export interface DoctorDiagnostics {
   access: DoctorAccessSummary;
   /** Clawtip 钱包信息 */
   clawtipWallet: DoctorClawtipWalletSummary;
+  /** buyer 本地 Manual provider 状态 */
+  manualProviders: DoctorManualProvidersSummary;
   /** 模型目录汇总 */
   models: DoctorModelsSummary;
   /** provider 安装 / 配置状态 */
@@ -108,12 +111,18 @@ interface DoctorModelsResponse {
   sellers?: DoctorSellerEntry[];
 }
 
+interface DoctorManualProvidersResponse {
+  providers: PublicManualProviderConfig[];
+}
+
 /**
  * `tb doctor` 模型表的单行：按 model id 聚合 seller 的折扣 / 价格区间。
  */
 export interface DoctorModelSummaryEntry {
   id: string;
   sellerCount: number;
+  localProviderCount: number;
+  sourceRange: string;
   discountMin?: number;
   discountMax?: number;
   discountRange: string;
@@ -128,6 +137,7 @@ interface DoctorFetchResults {
   healthResult: RemoteJsonResult<Record<string, unknown>>;
   sellersResult: RemoteJsonResult<DoctorSellerResponse>;
   modelsResult: RemoteJsonResult<DoctorModelsResponse>;
+  manualProvidersResult: RemoteJsonResult<DoctorManualProvidersResponse>;
   proxyModelsResult: RemoteJsonResult<{ object?: string; data?: Array<{ id?: string }> }>;
   registryResult: RemoteJsonResult<DoctorRegistryDocument>;
 }
@@ -136,6 +146,7 @@ interface DoctorFetchPromises {
   healthResult: Promise<RemoteJsonResult<Record<string, unknown>>>;
   sellersResult: Promise<RemoteJsonResult<DoctorSellerResponse>>;
   modelsResult: Promise<RemoteJsonResult<DoctorModelsResponse>>;
+  manualProvidersResult: Promise<RemoteJsonResult<DoctorManualProvidersResponse>>;
   proxyModelsResult: Promise<RemoteJsonResult<{ object?: string; data?: Array<{ id?: string }> }>>;
   registryResult: Promise<RemoteJsonResult<DoctorRegistryDocument>>;
 }
@@ -184,6 +195,14 @@ type DoctorSellersSummary = {
   error?: string;
 };
 
+export type DoctorManualProvidersSummary = {
+  available: boolean;
+  count: number;
+  configuredKeyCount: number;
+  providers: PublicManualProviderConfig[];
+  error?: string;
+};
+
 /**
  * `tb doctor` 模型目录汇总：原始 `data` + 聚合后的 `grouped`（按 model id 分组）。
  */
@@ -363,6 +382,14 @@ function formatPriceRange(minMicros?: number, maxMicros?: number): string {
   return `${formatUsdPer1m(minMicros)}~${formatUsdPer1m(maxMicros)}`;
 }
 
+function formatModelSourceRange(marketplaceCount: number, localProviderCount: number): string {
+  const parts = [
+    marketplaceCount > 0 ? `${marketplaceCount} marketplace` : undefined,
+    localProviderCount > 0 ? `${localProviderCount} local` : undefined,
+  ].filter(Boolean);
+  return parts.length > 0 ? parts.join(" + ") : "-";
+}
+
 function modelsHaveExplicitPriceData(models: ModelCatalogEntry[]): boolean {
   return models.some((model) =>
     typeof model.inputPriceMicrosPer1m === "number" ||
@@ -376,6 +403,7 @@ function buildDoctorModelSummaryEntries(
 ): DoctorModelSummaryEntry[] {
   const grouped = new Map<string, {
     sellerIds: Set<string>;
+    localProviderIds: Set<string>;
     discounts: number[];
     inputPrices: number[];
     outputPrices: number[];
@@ -389,12 +417,16 @@ function buildDoctorModelSummaryEntries(
   for (const model of models) {
     const entry = grouped.get(model.id) || {
       sellerIds: new Set<string>(),
+      localProviderIds: new Set<string>(),
       discounts: [],
       inputPrices: [],
       outputPrices: [],
     };
     if (!entry.sellerIds.has(model.sellerId)) {
       entry.sellerIds.add(model.sellerId);
+      if (model.paymentMethods.includes("provider_key")) {
+        entry.localProviderIds.add(model.sellerId);
+      }
       const discount = discountBySellerId.get(model.sellerId);
       if (typeof discount === "number") {
         entry.discounts.push(discount);
@@ -411,6 +443,7 @@ function buildDoctorModelSummaryEntries(
 
   return Array.from(grouped.entries())
     .map(([id, entry]) => {
+      const marketplaceCount = Math.max(0, entry.sellerIds.size - entry.localProviderIds.size);
       const discountMin = entry.discounts.length > 0 ? Math.min(...entry.discounts) : undefined;
       const discountMax = entry.discounts.length > 0 ? Math.max(...entry.discounts) : undefined;
       const inputPriceMinMicrosPer1m = entry.inputPrices.length > 0 ? Math.min(...entry.inputPrices) : undefined;
@@ -428,6 +461,8 @@ function buildDoctorModelSummaryEntries(
       return {
         id,
         sellerCount: entry.sellerIds.size,
+        localProviderCount: entry.localProviderIds.size,
+        sourceRange: formatModelSourceRange(marketplaceCount, entry.localProviderIds.size),
         discountMin,
         discountMax,
         discountRange,
@@ -457,6 +492,7 @@ function startDoctorFetches(
       healthResult: Promise.resolve({ url: `${controlBaseUrl}/health`, available: false, error: unavailableMessage }),
       sellersResult: Promise.resolve({ url: `${controlBaseUrl}/sellers`, available: false, error: unavailableMessage }),
       modelsResult: Promise.resolve({ url: `${controlBaseUrl}/models`, available: false, error: unavailableMessage }),
+      manualProvidersResult: Promise.resolve({ url: `${controlBaseUrl}/routing/manual-providers`, available: false, error: unavailableMessage }),
       proxyModelsResult: Promise.resolve({ url: `${openAiBaseUrl}/models`, available: false, error: unavailableMessage }),
       registryResult: Promise.resolve({ url: sellerRegistryUrl || "", available: false, error: unavailableMessage }),
     };
@@ -466,6 +502,7 @@ function startDoctorFetches(
     healthResult: fetchJsonDocument<Record<string, unknown>>(`${controlBaseUrl}/health`),
     sellersResult: fetchJsonDocument<DoctorSellerResponse>(`${controlBaseUrl}/sellers`),
     modelsResult: fetchJsonDocument<DoctorModelsResponse>(`${controlBaseUrl}/models`),
+    manualProvidersResult: fetchJsonDocument<DoctorManualProvidersResponse>(`${controlBaseUrl}/routing/manual-providers`),
     proxyModelsResult: fetchJsonDocument<{ object?: string; data?: Array<{ id?: string }> }>(`${openAiBaseUrl}/models`),
     registryResult: sellerRegistryUrl
       ? fetchJsonDocument<DoctorRegistryDocument>(sellerRegistryUrl)
@@ -478,12 +515,14 @@ async function resolveDoctorFetches(fetches: DoctorFetchPromises): Promise<Docto
     healthResult,
     sellersResult,
     modelsResult,
+    manualProvidersResult,
     proxyModelsResult,
     registryResult,
   ] = await Promise.all([
     fetches.healthResult,
     fetches.sellersResult,
     fetches.modelsResult,
+    fetches.manualProvidersResult,
     fetches.proxyModelsResult,
     fetches.registryResult,
   ]);
@@ -491,6 +530,7 @@ async function resolveDoctorFetches(fetches: DoctorFetchPromises): Promise<Docto
     healthResult,
     sellersResult,
     modelsResult,
+    manualProvidersResult,
     proxyModelsResult,
     registryResult,
   };
@@ -521,6 +561,19 @@ function buildDoctorSellerSummary(
   };
 }
 
+function buildDoctorManualProvidersSummary(
+  manualProvidersResult: RemoteJsonResult<DoctorManualProvidersResponse>
+): DoctorManualProvidersSummary {
+  const providers = manualProvidersResult.data?.providers || [];
+  return {
+    available: manualProvidersResult.available,
+    count: providers.length,
+    configuredKeyCount: providers.filter((provider) => provider.keyRef?.configured).length,
+    providers,
+    error: manualProvidersResult.error,
+  };
+}
+
 function buildDoctorAccessSummary(
   controlPort: number,
   proxyPort: number,
@@ -674,6 +727,42 @@ function printDoctorSellers(sellers: DoctorSellersSummary, writeLine: (line: str
   }
 }
 
+function printDoctorManualProviders(
+  manualProviders: DoctorManualProvidersSummary,
+  writeLine: (line: string) => void
+): void {
+  writeLine("Manual provider check complete.");
+  if (!manualProviders.available) {
+    writeLine(`❌ Manual providers unavailable: ${manualProviders.error || "unknown error"}`);
+    return;
+  }
+  writeLine(`Manual providers: ${manualProviders.count}`);
+  writeLine(`Configured keys: ${manualProviders.configuredKeyCount}/${manualProviders.count}`);
+  for (const provider of manualProviders.providers) {
+    const icon = provider.enabled && provider.keyRef?.configured
+      ? "✅"
+      : provider.enabled
+        ? "⚠️"
+        : "🔘";
+    const keyRef = provider.keyRef
+      ? `${provider.keyRef.kind}:${provider.keyRef.name} ${provider.keyRef.configured ? "configured" : "missing"}`
+      : "missing";
+    writeLine(`${icon} ${provider.name} (${provider.id}) [${provider.enabled ? "enabled" : "disabled"}]`);
+    writeLine(`   Key: ${keyRef}`);
+    writeLine(`   Models: ${provider.models.length}`);
+    writeLine(`   Protocols: ${formatList(provider.supportedProtocols)}`);
+    if (provider.lastAccess) {
+      writeLine(`   Last access: ${provider.lastAccess}`);
+    }
+    if (provider.status) {
+      writeLine(`   Status: ${provider.status}`);
+    }
+    if (provider.errorMessage) {
+      writeLine(`   Error: ${provider.errorMessage}`);
+    }
+  }
+}
+
 /**
  * 打印模型目录汇总（写到 `writeLine`，默认 stdout）。
  *
@@ -693,7 +782,7 @@ export function printDoctorModelsSummary(
   writeLine(`Seller offers: ${models.count}`);
 
   const table = new Table({
-    head: ["Model ID", "Seller Count", "Discount Range", "Price Range"],
+    head: ["Model ID", "Seller Count", "Sources", "Discount Range", "Price Range"],
     style: {
       head: []
     }
@@ -702,6 +791,7 @@ export function printDoctorModelsSummary(
     table.push([
       entry.id,
       String(entry.sellerCount),
+      entry.sourceRange,
       entry.discountRange,
       entry.priceRange
     ]);
@@ -794,6 +884,7 @@ export async function collectDoctorDiagnostics(options: DoctorCollectOptions): P
     results.modelsResult.data?.sellers || [],
   );
   const models = buildDoctorModelsSummary(results.modelsResult, sellers.sellers);
+  const manualProviders = buildDoctorManualProvidersSummary(results.manualProvidersResult);
 
   return {
     access: buildDoctorAccessSummary(
@@ -809,6 +900,7 @@ export async function collectDoctorDiagnostics(options: DoctorCollectOptions): P
       },
     ),
     clawtipWallet: readDoctorClawtipWallet(),
+    manualProviders,
     models,
     providers: options.providers,
     sellers,
@@ -882,6 +974,12 @@ export async function renderDoctorDiagnosticsProgressively(options: DoctorRender
   );
   printDoctorAccess(access, writeLine);
 
+  writeLine("\n--- Manual Providers ---");
+  writeLine("Reading local custom provider status...");
+  const manualProvidersResult = await fetches.manualProvidersResult;
+  const manualProviders = buildDoctorManualProvidersSummary(manualProvidersResult);
+  printDoctorManualProviders(manualProviders, writeLine);
+
   writeLine("\n--- Sellers ---");
   writeLine("Refreshing seller registry...");
   const [sellersResult, registryResult] = await Promise.all([
@@ -920,6 +1018,7 @@ export async function renderDoctorDiagnosticsProgressively(options: DoctorRender
   return {
     access,
     clawtipWallet,
+    manualProviders,
     models,
     providers: options.providers,
     sellers: finalSellers,

package/src/prewarm-cache.ts

@@ -456,7 +456,7 @@ function toCandidate(input: PrewarmCandidateInput): PrewarmCandidate {
     healthProbeLatencyMs: finiteNonNegative(input.healthProbeLatencyMs),
     ttftMs: finiteNonNegative(input.ttftMs),
     avgInferenceMs: finiteNonNegative(input.avgInferenceMs),
-    avgTokensPerSecond: finiteNonNegative(input.avgTokensPerSecond),
+    avgTokensPerSecond: finitePositive(input.avgTokensPerSecond),
     upstreamStatus: input.upstreamStatus,
     upstreamErrorClass: input.upstreamErrorClass,
     capacityBlockedUntil: finiteNonNegative(input.capacityBlockedUntil)
@@ -467,6 +467,10 @@ function finiteNonNegative(value: number | undefined): number | undefined {
   return Number.isFinite(value) ? Math.max(0, value as number) : undefined;
 }
 
+function finitePositive(value: number | undefined): number | undefined {
+  return Number.isFinite(value) && (value as number) > 0 ? value : undefined;
+}
+
 function clampScore(score: number): number {
   if (!Number.isFinite(score)) {
     return 50;

package/src/provider-routing-config.ts

@@ -0,0 +1,410 @@
+import type { SellerRoutingScorer } from "./seller-routing-strategy.js";
+
+export const PROVIDER_MODE_CONFIG_KEY = "provider-mode";
+export const MANUAL_PROVIDER_CONFIG_KEY = "manual-providers";
+export const AUTO_PROVIDER_CONFIG_KEY = "auto-provider";
+export const MANUAL_PROVIDER_OBSERVATIONS_CONFIG_KEY = "manual-provider-observations";
+
+export type ProviderMode = "manual" | "auto";
+export type ManualProviderKind = "openai-compatible";
+export type ProviderProtocol = "chat_completions" | "responses" | "messages";
+export type AutoProviderRange = "recommended" | "custom";
+export type ManualProviderRoutingPolicy = "fallback" | "locked";
+
+export interface ProviderModeConfig {
+  mode: ProviderMode;
+  updatedAt: string;
+}
+
+export interface ManualProviderConfig {
+  id: string;
+  name: string;
+  kind: ManualProviderKind;
+  baseUrl: string;
+  apiKeyEnv?: string;
+  secretRef?: string;
+  models: string[];
+  supportedProtocols: ProviderProtocol[];
+  enabled: boolean;
+  notes?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ManualProvidersConfig {
+  version: 1;
+  providers: ManualProviderConfig[];
+  routing: ManualProviderRoutingConfig;
+  updatedAt: string;
+}
+
+export interface ManualProviderRoutingConfig {
+  policy: ManualProviderRoutingPolicy;
+  lockedProviderId?: string;
+}
+
+export interface AutoProviderConfig {
+  enabled: boolean;
+  range: AutoProviderRange;
+  scorer: SellerRoutingScorer;
+  modelIds: string[];
+  sellerIds: string[];
+  maxConcurrentProviders: 10;
+  updatedAt: string;
+}
+
+export interface PublicManualProviderConfig extends Omit<ManualProviderConfig, "apiKeyEnv" | "secretRef"> {
+  keyRef?: {
+    kind: "env" | "secret";
+    name: string;
+    configured: boolean;
+  };
+  current?: boolean;
+  lastAccess?: string;
+  status?: "healthy" | "degraded" | "unhealthy" | "unknown";
+  errorClass?: string;
+  errorMessage?: string;
+  ttftMs?: number;
+  avgTokensPerSecond?: number;
+}
+
+export interface ManualProviderObservation {
+  providerId: string;
+  current: boolean;
+  lastAccess: string;
+  status: "healthy" | "degraded" | "unhealthy" | "unknown";
+  errorClass?: string;
+  errorMessage?: string;
+  ttftMs?: number;
+  avgTokensPerSecond?: number;
+}
+
+export interface ManualProviderObservationsConfig {
+  version: 1;
+  observations: ManualProviderObservation[];
+  updatedAt: string;
+}
+
+const VALID_PROTOCOLS = new Set<ProviderProtocol>(["chat_completions", "responses", "messages"]);
+const VALID_SCORERS = new Set<SellerRoutingScorer>(["balanced", "speed", "discount"]);
+
+export function defaultProviderModeConfig(now = new Date().toISOString()): ProviderModeConfig {
+  return {
+    mode: "manual",
+    updatedAt: now
+  };
+}
+
+export function normalizeProviderModeConfig(value: unknown, now = new Date().toISOString()): ProviderModeConfig {
+  if (!isRecord(value)) {
+    return defaultProviderModeConfig(now);
+  }
+  return {
+    mode: readProviderMode(value.mode),
+    updatedAt: readOptionalString(value.updatedAt) ?? now
+  };
+}
+
+export function normalizeManualProvidersConfig(value: unknown, now = new Date().toISOString()): ManualProvidersConfig {
+  if (!isRecord(value)) {
+    return {
+      version: 1,
+      providers: [],
+      routing: defaultManualProviderRoutingConfig(),
+      updatedAt: now
+    };
+  }
+  const providersValue = Array.isArray(value.providers) ? value.providers : [];
+  const seen = new Set<string>();
+  const providers = providersValue.map((providerValue) => {
+    const provider = normalizeManualProviderConfig(providerValue, { now });
+    if (seen.has(provider.id)) {
+      throw new Error(`manual provider id is duplicated: ${provider.id}`);
+    }
+    seen.add(provider.id);
+    return provider;
+  });
+  return {
+    version: 1,
+    providers,
+    routing: normalizeManualProviderRoutingConfig(value.routing),
+    updatedAt: readOptionalString(value.updatedAt) ?? now
+  };
+}
+
+export function defaultManualProviderRoutingConfig(): ManualProviderRoutingConfig {
+  return {
+    policy: "fallback"
+  };
+}
+
+export function normalizeManualProviderRoutingConfig(value: unknown): ManualProviderRoutingConfig {
+  if (!isRecord(value)) {
+    return defaultManualProviderRoutingConfig();
+  }
+  const policy = readManualProviderRoutingPolicy(value.policy);
+  const lockedProviderId = readOptionalString(value.lockedProviderId);
+  if (policy === "locked" && !lockedProviderId) {
+    throw new Error("manual provider locked routing requires lockedProviderId");
+  }
+  return {
+    policy,
+    lockedProviderId: policy === "locked" ? readProviderId(lockedProviderId) : undefined
+  };
+}
+
+export function normalizeManualProviderConfig(
+  value: unknown,
+  options: { now?: string; id?: string; existingIds?: ReadonlySet<string> } = {}
+): ManualProviderConfig {
+  if (!isRecord(value)) {
+    throw new Error("manual provider config must be an object");
+  }
+  if ("apiKey" in value) {
+    throw new Error("manual provider config must not contain a raw apiKey; use apiKeyEnv or secretRef");
+  }
+  const now = options.now ?? new Date().toISOString();
+  const id = readProviderId(options.id ?? value.id);
+  if (options.existingIds?.has(id)) {
+    throw new Error(`manual provider id is duplicated: ${id}`);
+  }
+  const apiKeyEnv = readOptionalString(value.apiKeyEnv);
+  const secretRef = readOptionalString(value.secretRef);
+  if (!apiKeyEnv && !secretRef) {
+    throw new Error("manual provider requires apiKeyEnv or secretRef");
+  }
+  if (apiKeyEnv && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv)) {
+    throw new Error("manual provider apiKeyEnv must be a valid environment variable name");
+  }
+
+  return {
+    id,
+    name: readRequiredString(value.name, "manual provider name"),
+    kind: readManualProviderKind(value.kind),
+    baseUrl: normalizeProviderBaseUrl(value.baseUrl),
+    apiKeyEnv,
+    secretRef,
+    models: readNonEmptyStringList(value.models, "manual provider models"),
+    supportedProtocols: readProtocols(value.supportedProtocols),
+    enabled: value.enabled === undefined ? true : value.enabled === true,
+    notes: readOptionalString(value.notes),
+    createdAt: readOptionalString(value.createdAt) ?? now,
+    updatedAt: now
+  };
+}
+
+export function normalizeAutoProviderConfig(value: unknown, now = new Date().toISOString()): AutoProviderConfig {
+  if (!isRecord(value)) {
+    return defaultAutoProviderConfig(now);
+  }
+  return {
+    enabled: value.enabled === true,
+    range: readAutoProviderRange(value.range),
+    scorer: readScorer(value.scorer),
+    modelIds: readStringList(value.modelIds),
+    sellerIds: readStringList(value.sellerIds),
+    maxConcurrentProviders: 10,
+    updatedAt: readOptionalString(value.updatedAt) ?? now
+  };
+}
+
+export function defaultAutoProviderConfig(now = new Date().toISOString()): AutoProviderConfig {
+  return {
+    enabled: false,
+    range: "recommended",
+    scorer: "balanced",
+    modelIds: [],
+    sellerIds: [],
+    maxConcurrentProviders: 10,
+    updatedAt: now
+  };
+}
+
+export function normalizeManualProviderObservationsConfig(
+  value: unknown,
+  now = new Date().toISOString()
+): ManualProviderObservationsConfig {
+  if (!isRecord(value)) {
+    return {
+      version: 1,
+      observations: [],
+      updatedAt: now
+    };
+  }
+  const observationsValue = Array.isArray(value.observations) ? value.observations : [];
+  const seen = new Set<string>();
+  const observations = observationsValue
+    .filter(isRecord)
+    .map((entry) => normalizeManualProviderObservation(entry, now))
+    .filter((entry) => {
+      if (seen.has(entry.providerId)) {
+        return false;
+      }
+      seen.add(entry.providerId);
+      return true;
+    });
+  return {
+    version: 1,
+    observations,
+    updatedAt: readOptionalString(value.updatedAt) ?? now
+  };
+}
+
+export function publicManualProviderConfig(
+  provider: ManualProviderConfig,
+  observation?: ManualProviderObservation,
+  env: NodeJS.ProcessEnv = process.env
+): PublicManualProviderConfig {
+  const keyRef = provider.apiKeyEnv
+    ? { kind: "env" as const, name: provider.apiKeyEnv, configured: Boolean(env[provider.apiKeyEnv]) }
+    : provider.secretRef
+      ? { kind: "secret" as const, name: provider.secretRef, configured: true }
+      : undefined;
+  const { apiKeyEnv: _apiKeyEnv, secretRef: _secretRef, ...publicProvider } = provider;
+  return {
+    ...publicProvider,
+    keyRef,
+    current: observation?.current,
+    lastAccess: observation?.lastAccess,
+    status: observation?.status,
+    errorClass: observation?.errorClass,
+    errorMessage: observation?.errorMessage,
+    ttftMs: observation?.ttftMs,
+    avgTokensPerSecond: observation?.avgTokensPerSecond
+  };
+}
+
+function normalizeManualProviderObservation(value: Record<string, unknown>, now: string): ManualProviderObservation {
+  return {
+    providerId: readRequiredString(value.providerId, "manual provider observation providerId"),
+    current: value.current === true,
+    lastAccess: readOptionalString(value.lastAccess) ?? now,
+    status: readObservationStatus(value.status),
+    errorClass: readOptionalString(value.errorClass),
+    errorMessage: readOptionalString(value.errorMessage),
+    ttftMs: readOptionalNumber(value.ttftMs),
+    avgTokensPerSecond: readOptionalNumber(value.avgTokensPerSecond)
+  };
+}
+
+function readObservationStatus(value: unknown): ManualProviderObservation["status"] {
+  if (value === "healthy" || value === "degraded" || value === "unhealthy" || value === "unknown") {
+    return value;
+  }
+  return "unknown";
+}
+
+function readProviderMode(value: unknown): ProviderMode {
+  if (value === "manual" || value === "auto") {
+    return value;
+  }
+  throw new Error("provider mode must be manual or auto");
+}
+
+function readManualProviderRoutingPolicy(value: unknown): ManualProviderRoutingPolicy {
+  if (value === undefined || value === null || value === "" || value === "fallback") {
+    return "fallback";
+  }
+  if (value === "locked") {
+    return "locked";
+  }
+  throw new Error("manual provider routing policy must be fallback or locked");
+}
+
+function readManualProviderKind(value: unknown): ManualProviderKind {
+  if (value === undefined || value === null || value === "" || value === "openai-compatible") {
+    return "openai-compatible";
+  }
+  throw new Error("manual provider kind must be openai-compatible");
+}
+
+function readAutoProviderRange(value: unknown): AutoProviderRange {
+  if (value === undefined || value === null || value === "" || value === "recommended") {
+    return "recommended";
+  }
+  if (value === "custom") {
+    return "custom";
+  }
+  throw new Error("auto provider range must be recommended or custom");
+}
+
+function readScorer(value: unknown): SellerRoutingScorer {
+  if (value === undefined || value === null || value === "") {
+    return "balanced";
+  }
+  if (typeof value === "string" && VALID_SCORERS.has(value as SellerRoutingScorer)) {
+    return value as SellerRoutingScorer;
+  }
+  throw new Error("auto provider scorer must be balanced, speed, or discount");
+}
+
+function readProtocols(value: unknown): ProviderProtocol[] {
+  const protocols = readStringList(value);
+  if (protocols.length === 0) {
+    return ["chat_completions"];
+  }
+  const invalid = protocols.find((protocol) => !VALID_PROTOCOLS.has(protocol as ProviderProtocol));
+  if (invalid) {
+    throw new Error(`manual provider protocol is invalid: ${invalid}`);
+  }
+  return protocols as ProviderProtocol[];
+}
+
+function normalizeProviderBaseUrl(value: unknown): string {
+  const raw = readRequiredString(value, "manual provider baseUrl");
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error("manual provider baseUrl must be a valid URL");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("manual provider baseUrl must use http or https");
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+
+function readProviderId(value: unknown): string {
+  const id = readRequiredString(value, "manual provider id");
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/.test(id)) {
+    throw new Error("manual provider id must be 2-64 characters of letters, numbers, underscore, or dash");
+  }
+  return id;
+}
+
+function readRequiredString(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${label} is required`);
+  }
+  return value.trim();
+}
+
+function readOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function readOptionalNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function readNonEmptyStringList(value: unknown, label: string): string[] {
+  const entries = readStringList(value);
+  if (entries.length === 0) {
+    throw new Error(`${label} must contain at least one value`);
+  }
+  return entries;
+}
+
+function readStringList(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter((entry, index, all) => entry.length > 0 && all.indexOf(entry) === index);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}