@tokenbuddy/tokenbuddy 1.0.30 → 1.0.33

package/src/daemon.ts

@@ -63,6 +63,27 @@ import {
   ROUTING_CONFIG_KEY,
   type BuyerSellerRoutingConfig
 } from "./seller-routing-config.js";
+import {
+  AUTO_PROVIDER_CONFIG_KEY,
+  MANUAL_PROVIDER_CONFIG_KEY,
+  MANUAL_PROVIDER_OBSERVATIONS_CONFIG_KEY,
+  PROVIDER_MODE_CONFIG_KEY,
+  defaultAutoProviderConfig,
+  defaultProviderModeConfig,
+  normalizeAutoProviderConfig,
+  normalizeManualProviderObservationsConfig,
+  normalizeManualProviderConfig,
+  normalizeManualProvidersConfig,
+  normalizeProviderModeConfig,
+  publicManualProviderConfig,
+  type AutoProviderConfig,
+  type ManualProviderConfig,
+  type ManualProviderObservation,
+  type ManualProviderObservationsConfig,
+  type ManualProvidersConfig,
+  type ProviderMode,
+  type ProviderModeConfig
+} from "./provider-routing-config.js";
 import {
   assertInitSetupSteps,
   buildCompletedInitSetupMarker,
@@ -86,6 +107,18 @@ const PROXY_JSON_BODY_LIMIT = "10mb";
 const SELLER_CAPACITY_BLOCK_MS = 2_000;
 const CLAWTIP_STATIC_ROUTE = "/static/clawtip";
 const CLAWTIP_RECHARGE_QR_FILE = "recharge.png";
+const MANUAL_PROVIDER_SECRET_CONFIG_KEY = "manual-provider-secrets";
+
+interface ManualProviderSecretsConfig {
+  version: 1;
+  secrets: Array<{
+    secretRef: string;
+    apiKey: string;
+    createdAt: string;
+    updatedAt: string;
+  }>;
+  updatedAt: string;
+}
 
 function currentModuleDir(): string {
   if (typeof __dirname !== "undefined") {
@@ -263,6 +296,8 @@ export interface DaemonConfig {
 
 interface SellerRoute {
   seller: RegistrySeller;
+  transport: "tokenbuddy_seller" | "manual_provider";
+  manualProvider?: ManualProviderConfig;
   manifest: SellerManifest | null;
   protocol: string;
   modelId: string;
@@ -276,6 +311,7 @@ interface SellerRoute {
 interface UsageSummary {
   promptTokens: number;
   completionTokens: number;
+  cacheReadTokens: number;
   billedMicros: number;
 }
 
@@ -325,6 +361,19 @@ interface SellerSettlementSummary {
   reservedBalanceMicros?: number;
   spentMicros?: number;
   priceVersion?: string;
+  billingBreakdown?: BillingBreakdownSummary;
+}
+
+interface BillingBreakdownSummary {
+  inputPriceMicrosPer1m: number;
+  outputPriceMicrosPer1m: number;
+  cacheReadPriceMicrosPer1m: number;
+  inputCostMicros: number;
+  outputCostMicros: number;
+  cacheReadCostMicros: number;
+  originalUsdMicros: number;
+  billingMultiplier: number;
+  serviceTier?: string;
 }
 
 interface SellerAttemptRequestContext {
@@ -339,6 +388,12 @@ interface SellerBalanceSnapshot {
   availableMicros: number;
 }
 
+interface PurchasePaymentSummary {
+  paymentAmount?: string;
+  paymentAmountMinor?: number;
+  paymentCurrency?: string;
+}
+
 function numericHeaderField(value: unknown): number | undefined {
   if (typeof value === "number" && Number.isFinite(value)) {
     return value;
@@ -350,6 +405,77 @@ function numericHeaderField(value: unknown): number | undefined {
   return undefined;
 }
 
+function nonNegativeIntegerField(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function nonNegativeFiniteField(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function usageRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function safeBillingServiceTier(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > 64) return undefined;
+  return /^[A-Za-z0-9 _.-]+$/.test(trimmed) ? trimmed : undefined;
+}
+
+function billingBreakdownSummary(value: unknown): BillingBreakdownSummary | undefined {
+  const data = usageRecord(value);
+  if (!data) return undefined;
+  const inputPriceMicrosPer1m = nonNegativeIntegerField(data.inputPriceMicrosPer1m ?? data.input_price_micros_per_1m);
+  const outputPriceMicrosPer1m = nonNegativeIntegerField(data.outputPriceMicrosPer1m ?? data.output_price_micros_per_1m);
+  const cacheReadPriceMicrosPer1m = nonNegativeIntegerField(data.cacheReadPriceMicrosPer1m ?? data.cache_read_price_micros_per_1m);
+  const inputCostMicros = nonNegativeIntegerField(data.inputCostMicros ?? data.input_cost_micros);
+  const outputCostMicros = nonNegativeIntegerField(data.outputCostMicros ?? data.output_cost_micros);
+  const cacheReadCostMicros = nonNegativeIntegerField(data.cacheReadCostMicros ?? data.cache_read_cost_micros);
+  const originalUsdMicros = nonNegativeIntegerField(data.originalUsdMicros ?? data.original_usd_micros);
+  const billingMultiplier = nonNegativeFiniteField(data.billingMultiplier ?? data.billing_multiplier);
+  if (
+    inputPriceMicrosPer1m === undefined ||
+    outputPriceMicrosPer1m === undefined ||
+    cacheReadPriceMicrosPer1m === undefined ||
+    inputCostMicros === undefined ||
+    outputCostMicros === undefined ||
+    cacheReadCostMicros === undefined ||
+    originalUsdMicros === undefined ||
+    billingMultiplier === undefined
+  ) {
+    return undefined;
+  }
+  return {
+    inputPriceMicrosPer1m,
+    outputPriceMicrosPer1m,
+    cacheReadPriceMicrosPer1m,
+    inputCostMicros,
+    outputCostMicros,
+    cacheReadCostMicros,
+    originalUsdMicros,
+    billingMultiplier,
+    serviceTier: safeBillingServiceTier(data.serviceTier ?? data.service_tier)
+  };
+}
+
+function purchasePaymentSummaryFromQuote(value: unknown): PurchasePaymentSummary {
+  const quote = usageRecord(value);
+  if (!quote) return {};
+  const paymentAmount = typeof quote.paymentAmount === "string" && quote.paymentAmount.trim().length > 0
+    ? quote.paymentAmount.trim()
+    : undefined;
+  const paymentCurrency = typeof quote.paymentCurrency === "string" && quote.paymentCurrency.trim().length > 0
+    ? quote.paymentCurrency.trim().toUpperCase()
+    : undefined;
+  return {
+    paymentAmount,
+    paymentAmountMinor: nonNegativeIntegerField(quote.paymentAmountMinor),
+    paymentCurrency
+  };
+}
+
 class SellerSettlementStreamExtractor {
   private pending = "";
   private settlement: SellerSettlementSummary | undefined;
@@ -422,7 +548,8 @@ function parseSellerSettlementObject(raw: string): SellerSettlementSummary | und
         ? parsed.priceVersion
         : typeof parsed.price_version === "string"
           ? parsed.price_version
-          : undefined
+          : undefined,
+      billingBreakdown: billingBreakdownSummary(parsed.billingBreakdown ?? parsed.billing_breakdown)
     };
   } catch {
     return undefined;
@@ -483,6 +610,11 @@ function finiteNumber(value: unknown): number | undefined {
   return undefined;
 }
 
+function finitePositiveNumber(value: unknown): number | undefined {
+  const number = finiteNumber(value);
+  return number !== undefined && number > 0 ? number : undefined;
+}
+
 function readErrorCode(bodyText: string): string | undefined {
   try {
     const parsed = JSON.parse(bodyText) as { error?: { code?: unknown }; code?: unknown };
@@ -668,7 +800,7 @@ export class TokenbuddyDaemon {
           httpStatus: res.status,
           ttftMs: finiteNumber(latency?.ttftMs ?? latency?.ttft_ms),
           avgInferenceMs: finiteNumber(latency?.avgInferenceMs ?? latency?.avg_inference_ms),
-          avgTokensPerSecond: finiteNumber(latency?.avgTokensPerSecond ?? latency?.avg_tokens_per_second),
+          avgTokensPerSecond: finitePositiveNumber(latency?.avgTokensPerSecond ?? latency?.avg_tokens_per_second),
           upstreamStatus: typeof upstream?.status === "string"
             ? upstream.status as "healthy" | "degraded" | "unhealthy" | "unknown"
             : undefined,
@@ -1049,6 +1181,187 @@ export class TokenbuddyDaemon {
     return this.tokenStore.listPayments().map((payment) => withLiveClawtipWalletState(payment, this.config.clawtipHomeDir));
   }
 
+  private providerPaymentState(): { paymentReady: boolean; paymentLabel?: string } {
+    const payment = this.livePayments().find((entry) => entry.enabled && entry.method !== "mock");
+    return {
+      paymentReady: Boolean(payment),
+      paymentLabel: payment ? paymentLabel(payment.method) : undefined
+    };
+  }
+
+  private currentProviderMode(): ProviderModeConfig {
+    return normalizeProviderModeConfig(
+      this.tokenStore.getDaemonRuntimeConfig<unknown>(PROVIDER_MODE_CONFIG_KEY)?.config
+    );
+  }
+
+  private saveProviderMode(mode: ProviderMode): ProviderModeConfig {
+    const config = {
+      ...defaultProviderModeConfig(),
+      mode
+    };
+    this.tokenStore.saveDaemonRuntimeConfig(PROVIDER_MODE_CONFIG_KEY, config);
+    return config;
+  }
+
+  private currentManualProviders(): ManualProvidersConfig {
+    return normalizeManualProvidersConfig(
+      this.tokenStore.getDaemonRuntimeConfig<unknown>(MANUAL_PROVIDER_CONFIG_KEY)?.config
+    );
+  }
+
+  private saveManualProviders(config: ManualProvidersConfig): void {
+    this.tokenStore.saveDaemonRuntimeConfig(MANUAL_PROVIDER_CONFIG_KEY, {
+      ...config,
+      updatedAt: new Date().toISOString()
+    });
+  }
+
+  private currentManualProviderSecrets(): ManualProviderSecretsConfig {
+    const value = this.tokenStore.getDaemonRuntimeConfig<unknown>(MANUAL_PROVIDER_SECRET_CONFIG_KEY)?.config;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return { version: 1, secrets: [], updatedAt: new Date().toISOString() };
+    }
+    const record = value as { secrets?: unknown[]; updatedAt?: unknown };
+    const secrets = (Array.isArray(record.secrets) ? record.secrets : [])
+      .filter((entry): entry is Record<string, unknown> => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)))
+      .flatMap((entry) => {
+        const secretRef = typeof entry.secretRef === "string" ? entry.secretRef.trim() : "";
+        const apiKey = typeof entry.apiKey === "string" ? entry.apiKey : "";
+        if (!secretRef || !apiKey) return [];
+        return [{
+          secretRef,
+          apiKey,
+          createdAt: typeof entry.createdAt === "string" ? entry.createdAt : new Date().toISOString(),
+          updatedAt: typeof entry.updatedAt === "string" ? entry.updatedAt : new Date().toISOString()
+        }];
+      });
+    return {
+      version: 1,
+      secrets,
+      updatedAt: typeof record.updatedAt === "string" ? record.updatedAt : new Date().toISOString()
+    };
+  }
+
+  private saveManualProviderSecret(secretRef: string, apiKey: string): void {
+    const now = new Date().toISOString();
+    const current = this.currentManualProviderSecrets();
+    const existing = current.secrets.find((entry) => entry.secretRef === secretRef);
+    this.tokenStore.saveDaemonRuntimeConfig(MANUAL_PROVIDER_SECRET_CONFIG_KEY, {
+      version: 1,
+      secrets: [
+        ...current.secrets.filter((entry) => entry.secretRef !== secretRef),
+        {
+          secretRef,
+          apiKey,
+          createdAt: existing?.createdAt ?? now,
+          updatedAt: now
+        }
+      ],
+      updatedAt: now
+    });
+  }
+
+  private removeManualProviderSecret(secretRef: string | undefined): void {
+    if (!secretRef) return;
+    const current = this.currentManualProviderSecrets();
+    const secrets = current.secrets.filter((entry) => entry.secretRef !== secretRef);
+    if (secrets.length === current.secrets.length) return;
+    this.tokenStore.saveDaemonRuntimeConfig(MANUAL_PROVIDER_SECRET_CONFIG_KEY, {
+      version: 1,
+      secrets,
+      updatedAt: new Date().toISOString()
+    });
+  }
+
+  private currentManualProviderObservations(): ManualProviderObservationsConfig {
+    return normalizeManualProviderObservationsConfig(
+      this.tokenStore.getDaemonRuntimeConfig<unknown>(MANUAL_PROVIDER_OBSERVATIONS_CONFIG_KEY)?.config
+    );
+  }
+
+  private recordManualProviderObservation(input: Omit<ManualProviderObservation, "lastAccess"> & { lastAccess?: string }): void {
+    const now = input.lastAccess ?? new Date().toISOString();
+    const current = this.currentManualProviderObservations();
+    const observations = current.observations
+      .filter((entry) => entry.providerId !== input.providerId)
+      .map((entry) => ({
+        ...entry,
+        current: input.current ? false : entry.current
+      }));
+    observations.push({
+      providerId: input.providerId,
+      current: input.current,
+      lastAccess: now,
+      status: input.status,
+      errorClass: input.errorClass,
+      errorMessage: input.errorMessage,
+      ttftMs: input.ttftMs,
+      avgTokensPerSecond: input.avgTokensPerSecond
+    });
+    this.tokenStore.saveDaemonRuntimeConfig(MANUAL_PROVIDER_OBSERVATIONS_CONFIG_KEY, {
+      version: 1,
+      observations,
+      updatedAt: now
+    });
+  }
+
+  private currentAutoProviderConfig(): AutoProviderConfig {
+    return normalizeAutoProviderConfig(
+      this.tokenStore.getDaemonRuntimeConfig<unknown>(AUTO_PROVIDER_CONFIG_KEY)?.config
+    );
+  }
+
+  private saveAutoProviderConfig(config: AutoProviderConfig): void {
+    this.tokenStore.saveDaemonRuntimeConfig(AUTO_PROVIDER_CONFIG_KEY, {
+      ...config,
+      updatedAt: new Date().toISOString()
+    });
+  }
+
+  private applyAutoProviderRoutingConfig(config: AutoProviderConfig): BuyerSellerRoutingConfig {
+    const routing: BuyerSellerRoutingConfig = config.range === "custom"
+      ? {
+          mode: "fixedSet",
+          scorer: config.scorer,
+          sellerIds: config.sellerIds
+        }
+      : {
+          mode: "fullAuto",
+          scorer: config.scorer
+        };
+    assertSellerRoutingConfig(routing);
+    this.tokenStore.saveDaemonRuntimeConfig(ROUTING_CONFIG_KEY, routing);
+    const current = this.refreshSellerRoutingConfig();
+    if (config.modelIds.length > 0) {
+      this.applyFocusSet(config.modelIds);
+    }
+    return current;
+  }
+
+  private autoProviderCanRoute(config: AutoProviderConfig): boolean {
+    return config.enabled && (config.range !== "custom" || config.sellerIds.length > 0);
+  }
+
+  private providerModePayload(): Record<string, unknown> {
+    const mode = this.currentProviderMode();
+    const autoProvider = this.currentAutoProviderConfig();
+    const payment = this.providerPaymentState();
+    return {
+      mode: mode.mode,
+      updatedAt: mode.updatedAt,
+      active: mode.mode,
+      manualEnabled: mode.mode === "manual",
+      autoEnabled: mode.mode === "auto" && this.autoProviderCanRoute(autoProvider) && payment.paymentReady,
+      paymentReady: payment.paymentReady,
+      paymentRequired: !payment.paymentReady,
+      paymentLabel: payment.paymentLabel,
+      locked: {
+        auto: !payment.paymentReady
+      }
+    };
+  }
+
   private clientToolsSummary(): { clients: ClientToolStatus[]; summary: { configuredCount: number; detectedCount: number; totalCount: number; installCommand: string } } {
     const providerStatuses = detectProviders({ home: this.config.providerHomeDir }).map(clientToolStatusFromProvider);
     const clients = [
@@ -1289,7 +1602,7 @@ export class TokenbuddyDaemon {
       this.sellerPool.recordRuntimeMetrics(route.seller.id, {
         ttftMs: finiteNumber(latency?.ttftMs ?? latency?.ttft_ms),
         avgInferenceMs: finiteNumber(latency?.avgInferenceMs ?? latency?.avg_inference_ms),
-        avgTokensPerSecond: finiteNumber(latency?.avgTokensPerSecond ?? latency?.avg_tokens_per_second)
+        avgTokensPerSecond: finitePositiveNumber(latency?.avgTokensPerSecond ?? latency?.avg_tokens_per_second)
       });
     } catch (error: unknown) {
       logger.warn("pool.runtime_metrics.refresh_failed", "seller health refresh failed after inference", {
@@ -1393,6 +1706,91 @@ export class TokenbuddyDaemon {
     return payments.find((payment) => payment.isDefault)?.method || payments.find((payment) => payment.method === "mock")?.method;
   }
 
+  private selectManualProviderRoutes(endpoint: string, modelId: string): { routes: SellerRoute[]; plan: SellerRoutePlan; paymentMethod: string } {
+    const protocol = this.endpointProtocol(endpoint);
+    if (!protocol) {
+      throw new Error(`unsupported proxy endpoint: ${endpoint}`);
+    }
+    const config = this.currentManualProviders();
+    let providers: ManualProviderConfig[];
+    let reason: string;
+    if (config.routing.policy === "locked") {
+      const provider = config.providers.find((entry) => entry.id === config.routing.lockedProviderId);
+      if (!provider) {
+        throw new Error(`locked manual provider is not configured: ${config.routing.lockedProviderId}`);
+      }
+      if (!provider.enabled) {
+        throw new Error(`locked manual provider is disabled: ${provider.id}`);
+      }
+      if (!provider.supportedProtocols.includes(protocol as ManualProviderConfig["supportedProtocols"][number])) {
+        throw new Error(`locked manual provider ${provider.id} does not support ${endpoint}`);
+      }
+      if (!provider.models.includes(modelId)) {
+        throw new Error(`locked manual provider ${provider.id} does not support model ${modelId}`);
+      }
+      providers = [provider];
+      reason = `manual:locked:${provider.id}`;
+    } else {
+      providers = config.providers.filter((provider) => (
+      provider.enabled &&
+      provider.models.includes(modelId) &&
+      provider.supportedProtocols.includes(protocol as ManualProviderConfig["supportedProtocols"][number])
+      ));
+      reason = `manual:fallback:routes_${providers.length}`;
+    }
+    if (providers.length === 0) {
+      throw new Error(`no compatible manual provider for ${endpoint} model ${modelId}`);
+    }
+    const routes: SellerRoute[] = providers.map((provider) => ({
+      seller: {
+        id: provider.id,
+        name: provider.name,
+        url: provider.baseUrl,
+        status: "active",
+        supportedProtocols: provider.supportedProtocols,
+        paymentMethods: ["provider_key"],
+        models: provider.models
+      },
+      transport: "manual_provider",
+      manualProvider: provider,
+      manifest: null,
+      protocol,
+      modelId,
+      paymentMethod: "provider_key",
+      planSource: "registry_fallback",
+      planReason: reason,
+      planSellerCount: providers.length
+    }));
+    return {
+      routes,
+      paymentMethod: "provider_key",
+      plan: {
+        routes: [],
+        source: "registry_fallback",
+        sourceReason: "manual_provider_config",
+        reason,
+        mode: "fixedSet",
+        scorer: "balanced",
+        candidateCount: providers.length,
+        diagnostics: {
+          registryVisibleCount: providers.length,
+          prewarmCandidateCount: 0,
+          prewarmUsableCount: 0,
+          prewarmMissingSellerIds: [],
+          prewarmBlockedSellerIds: [],
+          prewarmIncompatibleSellerIds: [],
+          sourceCandidateCount: providers.length,
+          blockedOpenCircuitCount: 0,
+          blockedCapacityCount: 0,
+          blockedLocalConcurrencyCount: 0,
+          blockedSellerIds: [],
+          incompatibleCount: 0,
+          incompatibleSellerIds: []
+        }
+      }
+    };
+  }
+
   private async selectSellerRoutes(endpoint: string, modelId: string, requestId?: string): Promise<{ routes: SellerRoute[]; plan: SellerRoutePlan; paymentMethod: string }> {
     const protocol = this.endpointProtocol(endpoint);
     if (!protocol) {
@@ -1458,6 +1856,7 @@ export class TokenbuddyDaemon {
 
     const routes: SellerRoute[] = planned.routes.map((route) => ({
       seller: route.seller,
+      transport: "tokenbuddy_seller",
       manifest: null,
       protocol,
       modelId,
@@ -1713,6 +2112,9 @@ export class TokenbuddyDaemon {
     status: string;
     creditMicros: number;
     currency: string;
+    paymentAmount?: string;
+    paymentAmountMinor?: number;
+    paymentCurrency?: string;
     durationMs: number;
   }): void {
     logger.info("purchase.ledger.recorded", "safe purchase ledger recorded", {
@@ -1724,6 +2126,9 @@ export class TokenbuddyDaemon {
       ledgerStatus: input.status,
       creditMicros: input.creditMicros,
       currency: input.currency,
+      paymentAmount: input.paymentAmount,
+      paymentAmountMinor: input.paymentAmountMinor,
+      paymentCurrency: input.paymentCurrency,
       durationMs: input.durationMs
     });
   }
@@ -1752,6 +2157,32 @@ export class TokenbuddyDaemon {
     models: ModelCatalogEntry[];
     sellers: SellerCatalogEntry[];
   }> {
+    const manualConfig = this.currentManualProviders();
+    if (this.currentProviderMode().mode === "manual" && manualConfig.providers.some((provider) => provider.enabled)) {
+      const observations = new Map(this.currentManualProviderObservations().observations.map((entry) => [entry.providerId, entry]));
+      const providers = manualConfig.providers.filter((provider) => provider.enabled);
+      return {
+        models: providers.flatMap((provider) => provider.models.map((modelId) => ({
+          id: modelId,
+          sellerId: provider.id,
+          sellerName: provider.name,
+          sellerUrl: provider.baseUrl,
+          supportedProtocols: provider.supportedProtocols,
+          paymentMethods: ["provider_key"]
+        }))),
+        sellers: providers.map((provider) => {
+          const observation = observations.get(provider.id);
+          return {
+            id: provider.id,
+            name: provider.name,
+            url: provider.baseUrl,
+            status: observation?.status ?? "active",
+            ttftMs: observation?.ttftMs,
+            avgTokensPerSecond: observation?.avgTokensPerSecond
+          };
+        })
+      };
+    }
     try {
       const catalog = await discoverSellerBackedModels(this.config.sellerRegistryUrl);
       this.lastRegistrySnapshot = catalog.registry ?? sellerCatalogResultToRegistrySnapshot(catalog);
@@ -1786,7 +2217,7 @@ export class TokenbuddyDaemon {
       return {
         ...seller,
         ttftMs: runtime?.ttftMs ?? seller.ttftMs,
-        avgTokensPerSecond: runtime?.avgTokensPerSecond ?? seller.avgTokensPerSecond ?? 0
+        avgTokensPerSecond: runtime?.avgTokensPerSecond ?? seller.avgTokensPerSecond
       };
     });
   }
@@ -1824,25 +2255,28 @@ export class TokenbuddyDaemon {
     const fallback: UsageSummary = {
       promptTokens: 0,
       completionTokens: 0,
+      cacheReadTokens: 0,
       billedMicros: 0
     };
     if (!bodyText.trim()) {
       return fallback;
     }
     try {
-      const data = JSON.parse(bodyText) as {
-        usage?: {
-          prompt_tokens?: number;
-          completion_tokens?: number;
-          input_tokens?: number;
-          output_tokens?: number;
-        };
-      };
-      const promptTokens = data.usage?.prompt_tokens ?? data.usage?.input_tokens ?? 0;
-      const completionTokens = data.usage?.completion_tokens ?? data.usage?.output_tokens ?? 0;
+      const data = usageRecord(JSON.parse(bodyText));
+      const usage = usageRecord(data?.usage) ?? usageRecord(usageRecord(data?.response)?.usage);
+      const promptDetails = usageRecord(usage?.prompt_tokens_details);
+      const inputDetails = usageRecord(usage?.input_tokens_details);
+      const promptTokens = nonNegativeIntegerField(usage?.prompt_tokens) ?? nonNegativeIntegerField(usage?.input_tokens) ?? 0;
+      const completionTokens = nonNegativeIntegerField(usage?.completion_tokens) ?? nonNegativeIntegerField(usage?.output_tokens) ?? 0;
+      const cacheReadTokens = nonNegativeIntegerField(promptDetails?.cached_tokens)
+        ?? nonNegativeIntegerField(inputDetails?.cached_tokens)
+        ?? nonNegativeIntegerField(usage?.cache_read_input_tokens)
+        ?? nonNegativeIntegerField(usage?.cache_read_tokens)
+        ?? 0;
       return {
         promptTokens,
         completionTokens,
+        cacheReadTokens,
         billedMicros: (promptTokens + completionTokens) * 4
       };
     } catch {
@@ -1891,6 +2325,7 @@ export class TokenbuddyDaemon {
     const sellerRequestId = settlement?.requestId && settlement.requestId !== requestId
       ? settlement.requestId
       : undefined;
+    const billingBreakdown = settlement?.billingBreakdown;
     this.tokenStore.recordInferenceLedger({
       requestId,
       sellerKey: route.seller.id,
@@ -1899,11 +2334,21 @@ export class TokenbuddyDaemon {
       status: settlement ? "settled" : "estimated",
       promptTokens: usage.promptTokens,
       completionTokens: usage.completionTokens,
+      cacheReadTokens: usage.cacheReadTokens,
       billedMicros: settledMicros ?? usage.billedMicros,
       estimatedMicros: usage.billedMicros,
       settledMicros,
       settledUsdMicros: settlement?.settledUsdMicros,
       priceVersion: settlement?.priceVersion,
+      inputPriceMicrosPer1m: billingBreakdown?.inputPriceMicrosPer1m,
+      outputPriceMicrosPer1m: billingBreakdown?.outputPriceMicrosPer1m,
+      cacheReadPriceMicrosPer1m: billingBreakdown?.cacheReadPriceMicrosPer1m,
+      inputCostMicros: billingBreakdown?.inputCostMicros,
+      outputCostMicros: billingBreakdown?.outputCostMicros,
+      cacheReadCostMicros: billingBreakdown?.cacheReadCostMicros,
+      originalUsdMicros: billingBreakdown?.originalUsdMicros,
+      billingMultiplier: billingBreakdown?.billingMultiplier,
+      serviceTier: billingBreakdown?.serviceTier,
       balanceSnapshotMicros: settlement?.remainingCreditMicros,
       balanceSource: settlement ? "seller_authoritative" : "estimated",
       prompt,
@@ -1928,6 +2373,7 @@ export class TokenbuddyDaemon {
       billedMicros: settledMicros ?? usage.billedMicros,
       promptTokens: usage.promptTokens,
       completionTokens: usage.completionTokens,
+      cacheReadTokens: usage.cacheReadTokens,
       balanceSnapshotMicros: settlement?.remainingCreditMicros,
       balanceSource: settlement ? "seller_authoritative" : "estimated",
       sellerRequestId,
@@ -2240,6 +2686,7 @@ export class TokenbuddyDaemon {
         const currency = completeData.currency || createData.currency || "USD";
         const expiresAt = new Date(Date.now() + 86400 * 1000).toISOString();
         const ledgerStatus = completeData.status || "funded";
+        const paymentSummary = purchasePaymentSummaryFromQuote(completeData.quote ?? createData.quote);
 
         this.tokenStore.saveToken(sellerKey, token, tokenClass, creditMicros, expiresAt);
         this.tokenStore.recordPurchaseLedger({
@@ -2250,6 +2697,7 @@ export class TokenbuddyDaemon {
           status: ledgerStatus,
           creditMicros,
           currency,
+          ...paymentSummary,
           paymentReference: completeData.paymentReference || completeData.payment_reference,
           completedAt: new Date().toISOString()
         });
@@ -2262,6 +2710,7 @@ export class TokenbuddyDaemon {
           status: ledgerStatus,
           creditMicros,
           currency,
+          ...paymentSummary,
           durationMs: Date.now() - startedAt
         });
         // v1.1: feed the credit tracker so the route-failover controller
@@ -2276,6 +2725,7 @@ export class TokenbuddyDaemon {
           tokenClass,
           creditMicros,
           currency,
+          ...paymentSummary,
           ledgerStatus,
           completeStatus: completeRes.status,
           durationMs: Date.now() - startedAt
@@ -2436,6 +2886,366 @@ export class TokenbuddyDaemon {
     });
   }
 
+  private manualProviderApiKey(provider: ManualProviderConfig): string {
+    if (provider.apiKeyEnv) {
+      const value = process.env[provider.apiKeyEnv];
+      if (!value) {
+        throw new Error(`manual provider key env is not configured: ${provider.apiKeyEnv}`);
+      }
+      return value;
+    }
+    if (provider.secretRef) {
+      const secret = this.currentManualProviderSecrets().secrets.find((entry) => entry.secretRef === provider.secretRef);
+      if (!secret) {
+        throw new Error(`manual provider secret is not configured: ${provider.secretRef}`);
+      }
+      return secret.apiKey;
+    }
+    throw new Error(`manual provider key reference is not configured: ${provider.id}`);
+  }
+
+  private manualProviderEndpointUrl(provider: ManualProviderConfig, endpoint: string): string {
+    const baseUrl = provider.baseUrl.replace(/\/+$/, "");
+    if (baseUrl.endsWith("/v1") && endpoint.startsWith("/v1/")) {
+      return `${baseUrl}${endpoint.slice(3)}`;
+    }
+    return `${baseUrl}${endpoint}`;
+  }
+
+  private manualProviderEndpointUrlFromBase(baseUrl: string, endpoint: string): string {
+    const normalized = baseUrl.replace(/\/+$/, "");
+    if (normalized.endsWith("/v1") && endpoint.startsWith("/v1/")) {
+      return `${normalized}${endpoint.slice(3)}`;
+    }
+    return `${normalized}${endpoint}`;
+  }
+
+  private async probeManualProviderModels(input: {
+    baseUrl: string;
+    apiKey: string;
+  }): Promise<{ modelIds: string[]; elapsedMs: number }> {
+    let parsed: URL;
+    try {
+      parsed = new URL(input.baseUrl);
+    } 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");
+    }
+    if (input.apiKey.trim().length < 6) {
+      throw new Error("manual provider api key is too short");
+    }
+
+    const startedAt = Date.now();
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(new Error("manual provider model probe timeout")), this.config.warmupProbeTimeoutMs ?? 3000);
+    try {
+      const response = await fetch(this.manualProviderEndpointUrlFromBase(parsed.toString(), "/v1/models"), {
+        method: "GET",
+        headers: {
+          "Authorization": `Bearer ${input.apiKey.trim()}`
+        },
+        signal: ac.signal
+      });
+      if (!response.ok) {
+        if (response.status === 401 || response.status === 403) {
+          throw new Error("manual provider authentication failed");
+        }
+        if (response.status === 404) {
+          throw new Error("manual provider /v1/models endpoint was not found");
+        }
+        throw new Error(`manual provider model probe returned HTTP ${response.status}`);
+      }
+      const body = await response.json().catch(() => undefined) as unknown;
+      const modelIds = parseOpenAiModelIds(body);
+      if (modelIds.length === 0) {
+        throw new Error("manual provider model list is empty");
+      }
+      return {
+        modelIds,
+        elapsedMs: Date.now() - startedAt
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private manualProviderErrorClass(status: number): string {
+    if (status === 401 || status === 403) {
+      return "auth_failed";
+    }
+    if (status === 429) {
+      return "rate_limited";
+    }
+    if (status >= 500) {
+      return "upstream_5xx";
+    }
+    if (status === 404) {
+      return "model_or_endpoint_not_found";
+    }
+    return `http_${status}`;
+  }
+
+  private shouldFailoverManualProvider(status: number): boolean {
+    return status === 408 || status === 429 || status >= 500;
+  }
+
+  private async fetchManualProviderRoute(
+    route: SellerRoute,
+    endpoint: string,
+    requestId: string,
+    idempotencyKey: string,
+    routeIndex: number,
+    attempt: number,
+    body: Record<string, unknown>
+  ): Promise<globalThis.Response> {
+    const provider = route.manualProvider;
+    if (!provider) {
+      throw new Error("manual provider route missing provider config");
+    }
+    const deadlineMs = this.requestDeadlineMs();
+    const requestAc = new AbortController();
+    const requestTimer = setTimeout(() => requestAc.abort(new Error("buyer deadline exceeded")), deadlineMs);
+    const attemptContext = sellerAttemptRequestContext(
+      requestId,
+      idempotencyKey,
+      routeIndex,
+      attempt,
+      0
+    );
+    try {
+      return await fetch(this.manualProviderEndpointUrl(provider, endpoint), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.manualProviderApiKey(provider)}`,
+          "X-Request-Id": attemptContext.requestId,
+          "Idempotency-Key": attemptContext.idempotencyKey,
+          "X-TokenBuddy-Deadline-Ms": String(deadlineMs)
+        },
+        body: JSON.stringify({
+          ...body,
+          requestId: attemptContext.requestId
+        }),
+        signal: requestAc.signal
+      });
+    } finally {
+      clearTimeout(requestTimer);
+    }
+  }
+
+  private async forwardManualProviderRoute(input: {
+    route: SellerRoute;
+    endpoint: string;
+    reqBody: Record<string, unknown>;
+    res: Response;
+    requestId: string;
+    idempotencyKey: string;
+    modelId: string;
+    requestedModelId?: string;
+    routeIndex: number;
+    routes: SellerRoute[];
+    plan: SellerRoutePlan;
+    paymentMethod: string;
+    startedAt: number;
+    markFirstByte: () => void;
+  }): Promise<boolean> {
+    const { route, endpoint, reqBody, res, requestId, idempotencyKey, modelId, requestedModelId, routeIndex, routes, plan, paymentMethod, startedAt, markFirstByte } = input;
+    const provider = route.manualProvider;
+    if (!provider) {
+      throw new Error("manual provider route missing provider config");
+    }
+    const sellerKey = route.seller.id;
+    const attemptStartedAt = Date.now();
+    const upstreamBody = this.applyResolvedModelToBody(endpoint, {
+      ...reqBody,
+      requestId
+    }, modelId);
+
+    logger.info("manual_provider.request.started", "manual provider request started", {
+      requestId,
+      providerId: provider.id,
+      sellerKey,
+      model: modelId,
+      requestedModel: requestedModelId,
+      endpoint,
+      stream: Boolean(reqBody.stream),
+      routeIndex,
+      backup: routeIndex > 0,
+      routePlanReason: route.planReason,
+      bodySummary: summarizeProxyBody(upstreamBody)
+    });
+
+    let response: globalThis.Response;
+    try {
+      response = await this.fetchManualProviderRoute(route, endpoint, requestId, idempotencyKey, routeIndex, 0, upstreamBody);
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.recordManualProviderObservation({
+        providerId: provider.id,
+        current: false,
+        status: "unhealthy",
+        errorClass: "deadline",
+        errorMessage
+      });
+      logger.warn("manual_provider.request.failed", "manual provider request failed before response", {
+        requestId,
+        providerId: provider.id,
+        model: modelId,
+        endpoint,
+        errorMessage,
+        durationMs: Date.now() - attemptStartedAt
+      });
+      if (routeIndex + 1 < routes.length) {
+        return false;
+      }
+      throw error;
+    }
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      const errorClass = this.manualProviderErrorClass(response.status);
+      const canFailover = this.shouldFailoverManualProvider(response.status) && routeIndex + 1 < routes.length;
+      this.recordManualProviderObservation({
+        providerId: provider.id,
+        current: false,
+        status: this.shouldFailoverManualProvider(response.status) ? "degraded" : "unhealthy",
+        errorClass,
+        errorMessage: errorBody.slice(0, 512)
+      });
+      logger.warn("manual_provider.upstream_fetch.failed", "manual provider upstream fetch returned non-ok status", {
+        requestId,
+        providerId: provider.id,
+        model: modelId,
+        endpoint,
+        status: response.status,
+        errorClass,
+        failover: canFailover,
+        durationMs: Date.now() - attemptStartedAt
+      });
+      if (canFailover) {
+        return false;
+      }
+      this.copyUpstreamHeaders(response, res);
+      res.status(response.status);
+      res.send(errorBody);
+      return true;
+    }
+
+    this.copyUpstreamHeaders(response, res);
+    res.status(response.status);
+    logger.info("manual_provider.upstream_fetch.succeeded", "manual provider upstream fetch succeeded", {
+      requestId,
+      providerId: provider.id,
+      model: modelId,
+      endpoint,
+      status: response.status,
+      stream: Boolean(reqBody.stream)
+    });
+
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("text/event-stream") || Boolean(reqBody.stream)) {
+      const reader = response.body?.getReader();
+      if (!reader) {
+        res.end();
+        return true;
+      }
+      let bytes = 0;
+      const decoder = new TextDecoder();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        bytes += value.byteLength;
+        const chunk = decoder.decode(value, { stream: true });
+        if (chunk.length > 0) {
+          markFirstByte();
+          res.write(chunk);
+        }
+      }
+      const decoderTail = decoder.decode();
+      if (decoderTail.length > 0) {
+        markFirstByte();
+        res.write(decoderTail);
+      }
+      res.end();
+      const durationMs = Date.now() - startedAt;
+      const ttftMs = durationMs > 0 ? Date.now() - attemptStartedAt : undefined;
+      this.recordManualProviderObservation({
+        providerId: provider.id,
+        current: true,
+        status: "healthy",
+        ttftMs,
+        avgTokensPerSecond: undefined
+      });
+      this.tokenStore.recordInferenceLedger({
+        requestId,
+        sellerKey,
+        modelId,
+        endpoint,
+        status: "ok",
+        promptTokens: 0,
+        completionTokens: 0,
+        cacheReadTokens: 0,
+        billedMicros: Math.max(1, bytes),
+        estimatedMicros: Math.max(1, bytes),
+        priceVersion: `local-provider:${provider.id}`,
+        balanceSource: "self_funded_provider",
+        prompt: this.inferPromptForHash(reqBody),
+        ttftMs,
+        fallbackCount: routeIndex,
+        routeReason: plan.reason,
+        falloverChain: routes.slice(0, routeIndex + 1).map((entry) => entry.seller.id),
+        upstreamStatus: "healthy",
+        durationMs,
+        paymentMethod
+      });
+      return true;
+    }
+
+    const responseBody = await response.text();
+    markFirstByte();
+    res.send(responseBody);
+    const usage = this.readUsage(responseBody);
+    const durationMs = Date.now() - startedAt;
+    const ttftMs = Date.now() - attemptStartedAt;
+    const completionTokens = usage.completionTokens;
+    const avgTokensPerSecond = durationMs > 0 && completionTokens > 0 ? completionTokens / (durationMs / 1000) : undefined;
+    this.recordManualProviderObservation({
+      providerId: provider.id,
+      current: true,
+      status: "healthy",
+      ttftMs,
+      avgTokensPerSecond
+    });
+    this.tokenStore.recordInferenceLedger({
+      requestId,
+      sellerKey,
+      modelId,
+      endpoint,
+      status: "ok",
+      promptTokens: usage.promptTokens,
+      completionTokens: usage.completionTokens,
+      cacheReadTokens: usage.cacheReadTokens,
+      billedMicros: usage.billedMicros,
+      estimatedMicros: usage.billedMicros,
+      priceVersion: `local-provider:${provider.id}`,
+      balanceSource: "self_funded_provider",
+      prompt: this.inferPromptForHash(reqBody),
+      response: responseBody,
+      ttftMs,
+      fallbackCount: routeIndex,
+      routeReason: plan.reason,
+      falloverChain: routes.slice(0, routeIndex + 1).map((entry) => entry.seller.id),
+      upstreamStatus: "healthy",
+      durationMs,
+      paymentMethod
+    });
+    return true;
+  }
+
   private async forwardProxyRequest(endpoint: string, req: Request, res: Response): Promise<void> {
     const startedAt = Date.now();
     let firstByteAt: number | null = null;
@@ -2454,7 +3264,10 @@ export class TokenbuddyDaemon {
     }
 
     try {
-      const { routes, plan, paymentMethod } = await this.selectSellerRoutes(endpoint, modelId, requestId);
+      const routeSelection = this.currentProviderMode().mode === "manual"
+        ? this.selectManualProviderRoutes(endpoint, modelId)
+        : await this.selectSellerRoutes(endpoint, modelId, requestId);
+      const { routes, plan, paymentMethod } = routeSelection;
       const upstreamStatusFromHeaders = (h: Headers): string | undefined => {
         const raw = h.get("x-tokenbuddy-upstream-status") || h.get("x-upstream-status");
         if (!raw) return undefined;
@@ -2465,6 +3278,39 @@ export class TokenbuddyDaemon {
       for (let routeIndex = 0; routeIndex < routes.length; routeIndex += 1) {
         const route = routes[routeIndex];
         const sellerKey = route.seller.id;
+        if (route.transport === "manual_provider") {
+          const completed = await this.forwardManualProviderRoute({
+            route,
+            endpoint,
+            reqBody: body as Record<string, unknown>,
+            res,
+            requestId,
+            idempotencyKey,
+            modelId,
+            requestedModelId,
+            routeIndex,
+            routes,
+            plan,
+            paymentMethod,
+            startedAt,
+            markFirstByte
+          });
+          if (completed) {
+            return;
+          }
+          lastError = new Error(`manual provider ${sellerKey} failed over`);
+          logger.warn("manual_provider.route.failover", "manual provider route failed over", {
+            requestId,
+            providerId: sellerKey,
+            model: modelId,
+            endpoint,
+            routeIndex,
+            nextRouteIndex: routeIndex + 1,
+            routesRemaining: routes.length - routeIndex,
+            routesRemainingAfterCurrent: Math.max(0, routes.length - routeIndex - 1)
+          });
+          continue;
+        }
         const lease = this.sellerConcurrencyLimiter.tryAcquire(sellerKey, { requestId, modelId, endpoint });
         if (!lease) {
           const routesRemaining = routes.length - routeIndex;
@@ -2777,7 +3623,7 @@ export class TokenbuddyDaemon {
                 route,
                 endpoint,
                 requestId,
-                { promptTokens: 0, completionTokens: 0, billedMicros: Math.max(1, bytes) },
+                { promptTokens: 0, completionTokens: 0, cacheReadTokens: 0, billedMicros: Math.max(1, bytes) },
                 this.parseSellerSettlementSummary(upstreamResponse.headers) ?? settlementTrailing.settlement ?? settlementExtractor.current(),
                 this.inferPromptForHash(body),
                 undefined,
@@ -2925,6 +3771,56 @@ export class TokenbuddyDaemon {
       });
     });
 
+    controlApp.put("/payments/default", (req, res) => {
+      try {
+        const method = typeof req.body?.method === "string" ? req.body.method.trim() : "";
+        const normalizedMethod = normalizePaymentMethodName(method);
+        const payments = this.livePayments();
+        const target = payments.find((payment) => normalizePaymentMethodName(payment.method) === normalizedMethod);
+        if (!normalizedMethod || normalizedMethod === "mock" || !target) {
+          res.status(400).json({
+            error: {
+              code: "payment_default_invalid",
+              message: "payment method is not configured"
+            }
+          });
+          return;
+        }
+        if (!target.enabled && !readConfigBoolean(target.config, "walletConfigPresent")) {
+          res.status(400).json({
+            error: {
+              code: "payment_default_not_ready",
+              message: "payment method must be bound before it can be selected"
+            }
+          });
+          return;
+        }
+        for (const payment of payments) {
+          this.tokenStore.savePayment({
+            method: payment.method,
+            enabled: payment.enabled,
+            isDefault: normalizePaymentMethodName(payment.method) === normalizedMethod,
+            config: payment.config
+          });
+        }
+        logger.info("control.payment.default_selected", "default payment selected", {
+          method: target.method
+        });
+        res.status(200).json({
+          payments: this.livePayments()
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("control.payment.default_select_failed", "default payment select failed", { errorMessage });
+        res.status(400).json({
+          error: {
+            code: "payment_default_select_failed",
+            message: errorMessage
+          }
+        });
+      }
+    });
+
     controlApp.get("/init/state", (req, res) => {
       try {
         const state = this.initStateSnapshot();
@@ -3315,6 +4211,453 @@ export class TokenbuddyDaemon {
     // 所有端点都热生效，不需重启 daemon。改完 store 即下次推理生效。
     // ─────────────────────────────────────────────────────────────────
 
+    controlApp.get("/routing/provider-mode", (req, res) => {
+      try {
+        res.status(200).json(this.providerModePayload());
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.provider_mode.read_failed", "provider mode read failed", { errorMessage });
+        res.status(500).json({ error: { code: "provider_mode_read_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.put("/routing/provider-mode", (req, res) => {
+      try {
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const requested = normalizeProviderModeConfig({
+          mode: body.mode,
+          updatedAt: new Date().toISOString()
+        });
+        const payment = this.providerPaymentState();
+        if (requested.mode === "auto" && !payment.paymentReady) {
+          res.status(409).json({
+            error: {
+              code: "payment_required",
+              message: "bind a payment method to enable auto provider"
+            },
+            paymentReady: false,
+            paymentRequired: true,
+            bindTarget: "/overview?bind=clawtip"
+          });
+          return;
+        }
+        const saved = this.saveProviderMode(requested.mode);
+        let strategy: BuyerSellerRoutingConfig | undefined;
+        if (saved.mode === "auto") {
+          const nextAuto = {
+            ...this.currentAutoProviderConfig(),
+            enabled: true
+          };
+          const shouldRoute = this.autoProviderCanRoute(nextAuto);
+          this.saveAutoProviderConfig(shouldRoute ? nextAuto : { ...nextAuto, enabled: false });
+          if (shouldRoute) {
+            strategy = this.applyAutoProviderRoutingConfig(nextAuto);
+          }
+        } else {
+          this.saveAutoProviderConfig({
+            ...this.currentAutoProviderConfig(),
+            enabled: false
+          });
+        }
+        logger.info("routing.provider_mode.applied", "provider mode applied", {
+          mode: saved.mode,
+          paymentReady: payment.paymentReady
+        });
+        res.status(200).json({
+          applied: true,
+          strategy,
+          ...this.providerModePayload()
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.provider_mode.apply_failed", "provider mode apply failed", { errorMessage });
+        res.status(400).json({ error: { code: "provider_mode_apply_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.get("/routing/manual-providers", (req, res) => {
+      try {
+        const config = this.currentManualProviders();
+        const observations = new Map(this.currentManualProviderObservations().observations.map((entry) => [entry.providerId, entry]));
+        res.status(200).json({
+          version: config.version,
+          updatedAt: config.updatedAt,
+          routing: config.routing,
+          providers: config.providers.map((provider) => publicManualProviderConfig(provider, observations.get(provider.id)))
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.manual_providers.read_failed", "manual providers read failed", { errorMessage });
+        res.status(500).json({ error: { code: "manual_providers_read_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.post("/routing/manual-providers/probe", async (req, res) => {
+      try {
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const baseUrl = typeof body.baseUrl === "string" ? body.baseUrl.trim() : "";
+        const apiKey = typeof body.apiKey === "string" ? body.apiKey.trim() : "";
+        const result = await this.probeManualProviderModels({ baseUrl, apiKey });
+        logger.info("routing.manual_provider.probed", "manual provider model probe succeeded", {
+          modelCount: result.modelIds.length,
+          elapsedMs: result.elapsedMs
+        });
+        res.status(200).json({
+          ok: true,
+          modelIds: result.modelIds,
+          elapsedMs: result.elapsedMs
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.manual_provider.probe_failed", "manual provider model probe failed", { errorMessage });
+        res.status(400).json({ error: { code: "manual_provider_probe_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.post("/routing/manual-providers/local", async (req, res) => {
+      try {
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const rawApiKey = typeof body.apiKey === "string" ? body.apiKey.trim() : "";
+        if (!rawApiKey) {
+          res.status(400).json({ error: { code: "manual_provider_local_create_failed", message: "manual provider apiKey is required" } });
+          return;
+        }
+        const baseUrl = typeof body.baseUrl === "string" ? body.baseUrl.trim() : "";
+        const probe = await this.probeManualProviderModels({ baseUrl, apiKey: rawApiKey });
+        const config = this.currentManualProviders();
+        const existingIds = new Set(config.providers.map((provider) => provider.id));
+        const rawId = typeof body.id === "string" && body.id.trim().length > 0 ? body.id : undefined;
+        const generatedId = `manual-${crypto.randomUUID().slice(0, 8)}`;
+        const providerId = rawId ?? generatedId;
+        const secretRef = `local:${providerId}`;
+        const providerInput = {
+          ...body,
+          apiKey: undefined,
+          apiKeyEnv: undefined,
+          secretRef,
+          models: probe.modelIds,
+          supportedProtocols: Array.isArray(body.supportedProtocols) ? body.supportedProtocols : ["chat_completions"],
+          enabled: body.enabled === undefined ? true : body.enabled
+        };
+        delete (providerInput as Record<string, unknown>).apiKey;
+        const provider = normalizeManualProviderConfig(providerInput, {
+          id: providerId,
+          existingIds
+        });
+        const nextConfig: ManualProvidersConfig = {
+          version: 1,
+          providers: [...config.providers, provider],
+          routing: config.routing,
+          updatedAt: new Date().toISOString()
+        };
+        this.saveManualProviderSecret(secretRef, rawApiKey);
+        this.saveManualProviders(nextConfig);
+        logger.info("routing.manual_provider.local_created", "local manual provider created", {
+          providerId: provider.id,
+          modelCount: provider.models.length,
+          enabled: provider.enabled,
+          keyRefKind: "secret"
+        });
+        res.status(201).json({
+          provider: publicManualProviderConfig(provider),
+          routing: nextConfig.routing,
+          providers: nextConfig.providers.map((entry) => publicManualProviderConfig(entry))
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.manual_provider.local_create_failed", "local manual provider create failed", { errorMessage });
+        res.status(400).json({ error: { code: "manual_provider_local_create_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.post("/routing/manual-providers", (req, res) => {
+      try {
+        const config = this.currentManualProviders();
+        const existingIds = new Set(config.providers.map((provider) => provider.id));
+        const rawId = (req.body as Record<string, unknown> | undefined)?.id;
+        const generatedId = `manual-${crypto.randomUUID().slice(0, 8)}`;
+        const provider = normalizeManualProviderConfig(req.body, {
+          id: typeof rawId === "string" && rawId.trim().length > 0 ? rawId : generatedId,
+          existingIds
+        });
+        const nextConfig: ManualProvidersConfig = {
+          version: 1,
+          providers: [...config.providers, provider],
+          routing: config.routing,
+          updatedAt: new Date().toISOString()
+        };
+        this.saveManualProviders(nextConfig);
+        logger.info("routing.manual_provider.created", "manual provider created", {
+          providerId: provider.id,
+          modelCount: provider.models.length,
+          enabled: provider.enabled,
+          keyRefKind: provider.apiKeyEnv ? "env" : "secret"
+        });
+        res.status(201).json({
+          provider: publicManualProviderConfig(provider),
+          routing: nextConfig.routing,
+          providers: nextConfig.providers.map((entry) => publicManualProviderConfig(entry))
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.manual_provider.create_failed", "manual provider create failed", { errorMessage });
+        res.status(400).json({ error: { code: "manual_provider_create_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.put("/routing/manual-providers/local/:id", async (req, res) => {
+      try {
+        const providerId = req.params.id;
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const config = this.currentManualProviders();
+        const provider = config.providers.find((entry) => entry.id === providerId);
+        if (!provider) {
+          res.status(404).json({ error: { code: "manual_provider_not_found", message: `manual provider not found: ${providerId}` } });
+          return;
+        }
+        const name = typeof body.name === "string" && body.name.trim().length > 0 ? body.name.trim() : provider.name;
+        const baseUrl = typeof body.baseUrl === "string" && body.baseUrl.trim().length > 0 ? body.baseUrl.trim() : provider.baseUrl;
+        const rawApiKey = typeof body.apiKey === "string" ? body.apiKey.trim() : "";
+        const apiKey = rawApiKey || this.manualProviderApiKey(provider);
+        const probe = await this.probeManualProviderModels({ baseUrl, apiKey });
+        const secretRef = provider.secretRef ?? `local:${provider.id}`;
+        const existingIds = new Set(config.providers.map((entry) => entry.id).filter((id) => id !== provider.id));
+        const updatedProvider = normalizeManualProviderConfig({
+          ...provider,
+          name,
+          baseUrl,
+          secretRef,
+          models: probe.modelIds,
+          supportedProtocols: provider.supportedProtocols.length > 0 ? provider.supportedProtocols : ["chat_completions"],
+          enabled: body.enabled === undefined ? provider.enabled : body.enabled,
+          updatedAt: new Date().toISOString()
+        }, {
+          id: provider.id,
+          existingIds
+        });
+        const nextConfig: ManualProvidersConfig = {
+          version: 1,
+          providers: config.providers.map((entry) => entry.id === provider.id ? updatedProvider : entry),
+          routing: config.routing,
+          updatedAt: new Date().toISOString()
+        };
+        if (rawApiKey || !provider.secretRef) {
+          this.saveManualProviderSecret(secretRef, apiKey);
+        }
+        this.saveManualProviders(nextConfig);
+        logger.info("routing.manual_provider.local_updated", "local manual provider updated", {
+          providerId: updatedProvider.id,
+          modelCount: updatedProvider.models.length,
+          enabled: updatedProvider.enabled,
+          keyRefKind: "secret"
+        });
+        res.status(200).json({
+          provider: publicManualProviderConfig(updatedProvider),
+          routing: nextConfig.routing,
+          providers: nextConfig.providers.map((entry) => publicManualProviderConfig(entry))
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.manual_provider.local_update_failed", "local manual provider update failed", { errorMessage });
+        res.status(400).json({ error: { code: "manual_provider_local_update_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.delete("/routing/manual-providers/:id", (req, res) => {
+      try {
+        const providerId = req.params.id;
+        const config = this.currentManualProviders();
+        const nextProviders = config.providers.filter((provider) => provider.id !== providerId);
+        if (nextProviders.length === config.providers.length) {
+          res.status(404).json({ error: { code: "manual_provider_not_found", message: `manual provider not found: ${providerId}` } });
+          return;
+        }
+        const nextConfig: ManualProvidersConfig = {
+          version: 1,
+          providers: nextProviders,
+          routing: config.routing.policy === "locked" && config.routing.lockedProviderId === providerId
+            ? { policy: "fallback" }
+            : config.routing,
+          updatedAt: new Date().toISOString()
+        };
+        const removed = config.providers.find((provider) => provider.id === providerId);
+        this.removeManualProviderSecret(removed?.secretRef);
+        this.saveManualProviders(nextConfig);
+        logger.info("routing.manual_provider.deleted", "manual provider deleted", { providerId });
+        res.status(200).json({
+          deleted: true,
+          providerId,
+          routing: nextConfig.routing,
+          providers: nextProviders.map((provider) => publicManualProviderConfig(provider))
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.manual_provider.delete_failed", "manual provider delete failed", { errorMessage });
+        res.status(400).json({ error: { code: "manual_provider_delete_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.put("/routing/manual-providers/order", (req, res) => {
+      try {
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const providerIds = Array.isArray(body.providerIds)
+          ? body.providerIds.map((entry) => typeof entry === "string" ? entry.trim() : "")
+          : [];
+        const config = this.currentManualProviders();
+        const currentIds = new Set(config.providers.map((provider) => provider.id));
+        const requestedIds = new Set(providerIds);
+        if (
+          providerIds.length !== config.providers.length ||
+          requestedIds.size !== providerIds.length ||
+          requestedIds.size !== currentIds.size ||
+          providerIds.some((providerId) => !currentIds.has(providerId))
+        ) {
+          res.status(400).json({
+            error: {
+              code: "manual_provider_order_invalid",
+              message: "manual provider order must include each configured provider exactly once"
+            }
+          });
+          return;
+        }
+        const providersById = new Map(config.providers.map((provider) => [provider.id, provider]));
+        const nextConfig: ManualProvidersConfig = {
+          version: 1,
+          providers: providerIds.map((providerId) => providersById.get(providerId)).filter((provider): provider is ManualProviderConfig => Boolean(provider)),
+          routing: config.routing,
+          updatedAt: new Date().toISOString()
+        };
+        this.saveManualProviders(nextConfig);
+        logger.info("routing.manual_provider.order_applied", "manual provider order applied", {
+          providerIds
+        });
+        const observations = new Map(this.currentManualProviderObservations().observations.map((entry) => [entry.providerId, entry]));
+        res.status(200).json({
+          version: nextConfig.version,
+          updatedAt: nextConfig.updatedAt,
+          routing: nextConfig.routing,
+          providers: nextConfig.providers.map((provider) => publicManualProviderConfig(provider, observations.get(provider.id)))
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.manual_provider.order_apply_failed", "manual provider order apply failed", { errorMessage });
+        res.status(400).json({ error: { code: "manual_provider_order_apply_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.put("/routing/manual-providers/routing", (req, res) => {
+      try {
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const policy = body.policy;
+        const lockedProviderId = typeof body.lockedProviderId === "string" ? body.lockedProviderId.trim() : undefined;
+        const config = this.currentManualProviders();
+        const routing = policy === "locked"
+          ? { policy: "locked" as const, lockedProviderId }
+          : { policy: "fallback" as const };
+        const normalized = normalizeManualProvidersConfig({
+          ...config,
+          routing
+        }).routing;
+        if (normalized.policy === "locked") {
+          const provider = config.providers.find((entry) => entry.id === normalized.lockedProviderId);
+          if (!provider) {
+            res.status(404).json({ error: { code: "manual_provider_not_found", message: `manual provider not found: ${normalized.lockedProviderId}` } });
+            return;
+          }
+          if (!provider.enabled) {
+            res.status(400).json({ error: { code: "manual_provider_locked_disabled", message: `manual provider is disabled: ${provider.id}` } });
+            return;
+          }
+        }
+        const nextConfig: ManualProvidersConfig = {
+          version: 1,
+          providers: config.providers,
+          routing: normalized,
+          updatedAt: new Date().toISOString()
+        };
+        this.saveManualProviders(nextConfig);
+        logger.info("routing.manual_provider.routing_applied", "manual provider routing applied", {
+          policy: normalized.policy,
+          lockedProviderId: normalized.lockedProviderId
+        });
+        const observations = new Map(this.currentManualProviderObservations().observations.map((entry) => [entry.providerId, entry]));
+        res.status(200).json({
+          version: nextConfig.version,
+          updatedAt: nextConfig.updatedAt,
+          routing: nextConfig.routing,
+          providers: nextConfig.providers.map((provider) => publicManualProviderConfig(provider, observations.get(provider.id)))
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.manual_provider.routing_apply_failed", "manual provider routing apply failed", { errorMessage });
+        res.status(400).json({ error: { code: "manual_provider_routing_apply_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.get("/routing/auto-provider", (req, res) => {
+      try {
+        const config = this.currentAutoProviderConfig();
+        const payment = this.providerPaymentState();
+        const mode = this.currentProviderMode();
+        res.status(200).json({
+          config,
+          active: mode.mode === "auto" && this.autoProviderCanRoute(config) && payment.paymentReady,
+          locked: !payment.paymentReady,
+          paymentReady: payment.paymentReady,
+          paymentRequired: !payment.paymentReady,
+          paymentLabel: payment.paymentLabel
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.auto_provider.read_failed", "auto provider read failed", { errorMessage });
+        res.status(500).json({ error: { code: "auto_provider_read_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.put("/routing/auto-provider", (req, res) => {
+      try {
+        const next = normalizeAutoProviderConfig(req.body);
+        const payment = this.providerPaymentState();
+        if (next.enabled && !payment.paymentReady) {
+          res.status(409).json({
+            error: {
+              code: "payment_required",
+              message: "bind a payment method to enable auto provider"
+            },
+            paymentReady: false,
+            paymentRequired: true,
+            bindTarget: "/overview?bind=clawtip"
+          });
+          return;
+        }
+        const shouldRoute = this.autoProviderCanRoute(next);
+        this.saveAutoProviderConfig(shouldRoute ? next : { ...next, enabled: false });
+        let strategy: BuyerSellerRoutingConfig | undefined;
+        if (shouldRoute) {
+          this.saveProviderMode("auto");
+          strategy = this.applyAutoProviderRoutingConfig(next);
+        }
+        logger.info("routing.auto_provider.applied", "auto provider applied", {
+          enabled: shouldRoute,
+          range: next.range,
+          scorer: next.scorer,
+          modelCount: next.modelIds.length,
+          sellerCount: next.sellerIds.length,
+          paymentReady: payment.paymentReady
+        });
+        res.status(200).json({
+          applied: true,
+          config: this.currentAutoProviderConfig(),
+          strategy,
+          ...this.providerModePayload()
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.auto_provider.apply_failed", "auto provider apply failed", { errorMessage });
+        res.status(400).json({ error: { code: "auto_provider_apply_failed", message: errorMessage } });
+      }
+    });
+
     // 1) GET /routing/strategy — 读当前路由策略 + 来源
     controlApp.get("/routing/strategy", (req, res) => {
       try {
@@ -3741,6 +5084,13 @@ function withLiveClawtipWalletState(payment: PaymentConfig, home?: string): Paym
   };
 }
 
+function paymentLabel(method: string): string {
+  if (method === "clawtip") {
+    return "ClawTip";
+  }
+  return method;
+}
+
 function normalizeClawtipActivationPayment(bootstrap: ClawtipBootstrapResponse): ClawtipBootstrapPayment {
   if (!bootstrap.payment?.orderNo || !bootstrap.payment.indicator || !bootstrap.payment.resourceUrl) {
     throw new Error("ClawTip bootstrap response missing orderNo, indicator, or resourceUrl.");
@@ -3779,6 +5129,10 @@ function readConfigBoolean(config: Record<string, unknown> | undefined, key: str
   return config?.[key] === true;
 }
 
+function normalizePaymentMethodName(method: string): string {
+  return method.trim().toLowerCase();
+}
+
 function selectedSellerIdForRouting(routing: BuyerSellerRoutingConfig): string | undefined {
   return routing.mode === "fixed" ? routing.sellerId : undefined;
 }
@@ -3848,6 +5202,25 @@ function catalogSnapshotFromRegistry(registry: SellerRegistryDocument): InitDoct
   };
 }
 
+function parseOpenAiModelIds(value: unknown): string[] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return [];
+  }
+  const data = (value as { data?: unknown }).data;
+  if (!Array.isArray(data)) {
+    return [];
+  }
+  return data
+    .flatMap((entry) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return [];
+      }
+      const id = (entry as { id?: unknown }).id;
+      return typeof id === "string" && id.trim().length > 0 ? [id.trim()] : [];
+    })
+    .filter((id, index, all) => all.indexOf(id) === index);
+}
+
 function normalizeTrustedRegistryCache(value: unknown): TrustedRegistryCacheRecord | undefined {
   if (!value || typeof value !== "object") {
     return undefined;