@tokenbuddy/tokenbuddy 1.0.30 → 1.0.33

package/dist/src/daemon.js

@@ -22,6 +22,7 @@ import { SellerConcurrencyLimiter } from "./seller-concurrency-limiter.js";
 import { SellerMetadataCache } from "./seller-metadata-cache.js";
 import { planSellerRouteSet } from "./seller-route-planner.js";
 import { assertSellerRoutingConfig, mergeSellerRoutingConfig, normalizeSellerRoutingConfig, parseSellerIdList, ROUTING_CONFIG_KEY } from "./seller-routing-config.js";
+import { AUTO_PROVIDER_CONFIG_KEY, MANUAL_PROVIDER_CONFIG_KEY, MANUAL_PROVIDER_OBSERVATIONS_CONFIG_KEY, PROVIDER_MODE_CONFIG_KEY, defaultProviderModeConfig, normalizeAutoProviderConfig, normalizeManualProviderObservationsConfig, normalizeManualProviderConfig, normalizeManualProvidersConfig, normalizeProviderModeConfig, publicManualProviderConfig } from "./provider-routing-config.js";
 import { assertInitSetupSteps, buildCompletedInitSetupMarker, INIT_SETUP_CONFIG_KEY, INIT_SETUP_STEPS, isFreshInitMachine, normalizeInitSetupMarker, resolveInitRecommendedModels, } from "./init-setup.js";
 import { checkPackageUpdate, runPackageUpdate, scheduleLaunchAgentRestart, } from "./package-update.js";
 const logger = createModuleLogger("tb-proxyd");
@@ -31,6 +32,7 @@ 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";
 function currentModuleDir() {
     if (typeof __dirname !== "undefined") {
         return __dirname;
@@ -113,6 +115,73 @@ function numericHeaderField(value) {
     }
     return undefined;
 }
+function nonNegativeIntegerField(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function nonNegativeFiniteField(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function usageRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function safeBillingServiceTier(value) {
+    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) {
+    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) {
+    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 {
     pending = "";
     settlement;
@@ -180,7 +249,8 @@ function parseSellerSettlementObject(raw) {
                 ? parsed.priceVersion
                 : typeof parsed.price_version === "string"
                     ? parsed.price_version
-                    : undefined
+                    : undefined,
+            billingBreakdown: billingBreakdownSummary(parsed.billingBreakdown ?? parsed.billing_breakdown)
         };
     }
     catch {
@@ -230,6 +300,10 @@ function finiteNumber(value) {
     }
     return undefined;
 }
+function finitePositiveNumber(value) {
+    const number = finiteNumber(value);
+    return number !== undefined && number > 0 ? number : undefined;
+}
 function readErrorCode(bodyText) {
     try {
         const parsed = JSON.parse(bodyText);
@@ -380,7 +454,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
                         : undefined,
@@ -747,6 +821,167 @@ export class TokenbuddyDaemon {
     livePayments() {
         return this.tokenStore.listPayments().map((payment) => withLiveClawtipWalletState(payment, this.config.clawtipHomeDir));
     }
+    providerPaymentState() {
+        const payment = this.livePayments().find((entry) => entry.enabled && entry.method !== "mock");
+        return {
+            paymentReady: Boolean(payment),
+            paymentLabel: payment ? paymentLabel(payment.method) : undefined
+        };
+    }
+    currentProviderMode() {
+        return normalizeProviderModeConfig(this.tokenStore.getDaemonRuntimeConfig(PROVIDER_MODE_CONFIG_KEY)?.config);
+    }
+    saveProviderMode(mode) {
+        const config = {
+            ...defaultProviderModeConfig(),
+            mode
+        };
+        this.tokenStore.saveDaemonRuntimeConfig(PROVIDER_MODE_CONFIG_KEY, config);
+        return config;
+    }
+    currentManualProviders() {
+        return normalizeManualProvidersConfig(this.tokenStore.getDaemonRuntimeConfig(MANUAL_PROVIDER_CONFIG_KEY)?.config);
+    }
+    saveManualProviders(config) {
+        this.tokenStore.saveDaemonRuntimeConfig(MANUAL_PROVIDER_CONFIG_KEY, {
+            ...config,
+            updatedAt: new Date().toISOString()
+        });
+    }
+    currentManualProviderSecrets() {
+        const value = this.tokenStore.getDaemonRuntimeConfig(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;
+        const secrets = (Array.isArray(record.secrets) ? record.secrets : [])
+            .filter((entry) => 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()
+        };
+    }
+    saveManualProviderSecret(secretRef, apiKey) {
+        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
+        });
+    }
+    removeManualProviderSecret(secretRef) {
+        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()
+        });
+    }
+    currentManualProviderObservations() {
+        return normalizeManualProviderObservationsConfig(this.tokenStore.getDaemonRuntimeConfig(MANUAL_PROVIDER_OBSERVATIONS_CONFIG_KEY)?.config);
+    }
+    recordManualProviderObservation(input) {
+        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
+        });
+    }
+    currentAutoProviderConfig() {
+        return normalizeAutoProviderConfig(this.tokenStore.getDaemonRuntimeConfig(AUTO_PROVIDER_CONFIG_KEY)?.config);
+    }
+    saveAutoProviderConfig(config) {
+        this.tokenStore.saveDaemonRuntimeConfig(AUTO_PROVIDER_CONFIG_KEY, {
+            ...config,
+            updatedAt: new Date().toISOString()
+        });
+    }
+    applyAutoProviderRoutingConfig(config) {
+        const routing = 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;
+    }
+    autoProviderCanRoute(config) {
+        return config.enabled && (config.range !== "custom" || config.sellerIds.length > 0);
+    }
+    providerModePayload() {
+        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
+            }
+        };
+    }
     clientToolsSummary() {
         const providerStatuses = detectProviders({ home: this.config.providerHomeDir }).map(clientToolStatusFromProvider);
         const clients = [
@@ -977,7 +1212,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) {
@@ -1070,6 +1305,89 @@ export class TokenbuddyDaemon {
         const payments = this.tokenStore.listPayments().filter((payment) => payment.enabled);
         return payments.find((payment) => payment.isDefault)?.method || payments.find((payment) => payment.method === "mock")?.method;
     }
+    selectManualProviderRoutes(endpoint, modelId) {
+        const protocol = this.endpointProtocol(endpoint);
+        if (!protocol) {
+            throw new Error(`unsupported proxy endpoint: ${endpoint}`);
+        }
+        const config = this.currentManualProviders();
+        let providers;
+        let reason;
+        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)) {
+                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)));
+            reason = `manual:fallback:routes_${providers.length}`;
+        }
+        if (providers.length === 0) {
+            throw new Error(`no compatible manual provider for ${endpoint} model ${modelId}`);
+        }
+        const routes = 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: []
+                }
+            }
+        };
+    }
     async selectSellerRoutes(endpoint, modelId, requestId) {
         const protocol = this.endpointProtocol(endpoint);
         if (!protocol) {
@@ -1130,6 +1448,7 @@ export class TokenbuddyDaemon {
         }
         const routes = planned.routes.map((route) => ({
             seller: route.seller,
+            transport: "tokenbuddy_seller",
             manifest: null,
             protocol,
             modelId,
@@ -1355,6 +1674,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
         });
     }
@@ -1374,6 +1696,32 @@ export class TokenbuddyDaemon {
         });
     }
     async listSellerBackedModels() {
+        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);
@@ -1408,7 +1756,7 @@ export class TokenbuddyDaemon {
             return {
                 ...seller,
                 ttftMs: runtime?.ttftMs ?? seller.ttftMs,
-                avgTokensPerSecond: runtime?.avgTokensPerSecond ?? seller.avgTokensPerSecond ?? 0
+                avgTokensPerSecond: runtime?.avgTokensPerSecond ?? seller.avgTokensPerSecond
             };
         });
     }
@@ -1441,18 +1789,28 @@ export class TokenbuddyDaemon {
         const fallback = {
             promptTokens: 0,
             completionTokens: 0,
+            cacheReadTokens: 0,
             billedMicros: 0
         };
         if (!bodyText.trim()) {
             return fallback;
         }
         try {
-            const data = JSON.parse(bodyText);
-            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
             };
         }
@@ -1482,6 +1840,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,
@@ -1490,11 +1849,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,
@@ -1519,6 +1888,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,
@@ -1819,6 +2189,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({
                     purchaseId,
@@ -1828,6 +2199,7 @@ export class TokenbuddyDaemon {
                     status: ledgerStatus,
                     creditMicros,
                     currency,
+                    ...paymentSummary,
                     paymentReference: completeData.paymentReference || completeData.payment_reference,
                     completedAt: new Date().toISOString()
                 });
@@ -1840,6 +2212,7 @@ export class TokenbuddyDaemon {
                     status: ledgerStatus,
                     creditMicros,
                     currency,
+                    ...paymentSummary,
                     durationMs: Date.now() - startedAt
                 });
                 // v1.1: feed the credit tracker so the route-failover controller
@@ -1854,6 +2227,7 @@ export class TokenbuddyDaemon {
                     tokenClass,
                     creditMicros,
                     currency,
+                    ...paymentSummary,
                     ledgerStatus,
                     completeStatus: completeRes.status,
                     durationMs: Date.now() - startedAt
@@ -1996,6 +2370,323 @@ export class TokenbuddyDaemon {
             res.setHeader(key, value);
         });
     }
+    manualProviderApiKey(provider) {
+        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}`);
+    }
+    manualProviderEndpointUrl(provider, endpoint) {
+        const baseUrl = provider.baseUrl.replace(/\/+$/, "");
+        if (baseUrl.endsWith("/v1") && endpoint.startsWith("/v1/")) {
+            return `${baseUrl}${endpoint.slice(3)}`;
+        }
+        return `${baseUrl}${endpoint}`;
+    }
+    manualProviderEndpointUrlFromBase(baseUrl, endpoint) {
+        const normalized = baseUrl.replace(/\/+$/, "");
+        if (normalized.endsWith("/v1") && endpoint.startsWith("/v1/")) {
+            return `${normalized}${endpoint.slice(3)}`;
+        }
+        return `${normalized}${endpoint}`;
+    }
+    async probeManualProviderModels(input) {
+        let parsed;
+        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);
+            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);
+        }
+    }
+    manualProviderErrorClass(status) {
+        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}`;
+    }
+    shouldFailoverManualProvider(status) {
+        return status === 408 || status === 429 || status >= 500;
+    }
+    async fetchManualProviderRoute(route, endpoint, requestId, idempotencyKey, routeIndex, attempt, body) {
+        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);
+        }
+    }
+    async forwardManualProviderRoute(input) {
+        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;
+        try {
+            response = await this.fetchManualProviderRoute(route, endpoint, requestId, idempotencyKey, routeIndex, 0, upstreamBody);
+        }
+        catch (error) {
+            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;
+    }
     async forwardProxyRequest(endpoint, req, res) {
         const startedAt = Date.now();
         let firstByteAt = null;
@@ -2013,7 +2704,10 @@ export class TokenbuddyDaemon {
             return;
         }
         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) => {
                 const raw = h.get("x-tokenbuddy-upstream-status") || h.get("x-upstream-status");
                 if (!raw)
@@ -2024,6 +2718,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,
+                        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;
@@ -2319,7 +3046,7 @@ export class TokenbuddyDaemon {
                                 }
                                 res.end();
                                 void this.refreshSellerRuntimeMetrics(route, requestId);
-                                this.recordReconciledInference(route, endpoint, requestId, { promptTokens: 0, completionTokens: 0, billedMicros: Math.max(1, bytes) }, this.parseSellerSettlementSummary(upstreamResponse.headers) ?? settlementTrailing.settlement ?? settlementExtractor.current(), this.inferPromptForHash(body), undefined, {
+                                this.recordReconciledInference(route, endpoint, requestId, { promptTokens: 0, completionTokens: 0, cacheReadTokens: 0, billedMicros: Math.max(1, bytes) }, this.parseSellerSettlementSummary(upstreamResponse.headers) ?? settlementTrailing.settlement ?? settlementExtractor.current(), this.inferPromptForHash(body), undefined, {
                                     ttftMs: firstByteAt ? firstByteAt - startedAt : undefined,
                                     fallbackCount: routeIndex,
                                     routeReason: plan.reason,
@@ -2446,6 +3173,56 @@ export class TokenbuddyDaemon {
                 payments: this.livePayments()
             });
         });
+        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) {
+                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();
@@ -2829,6 +3606,452 @@ export class TokenbuddyDaemon {
         // tb-ui v1: 控制平面写端点（PR-0）
         // 所有端点都热生效，不需重启 daemon。改完 store 即下次推理生效。
         // ─────────────────────────────────────────────────────────────────
+        controlApp.get("/routing/provider-mode", (req, res) => {
+            try {
+                res.status(200).json(this.providerModePayload());
+            }
+            catch (error) {
+                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 ?? {});
+                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;
+                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) {
+                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) {
+                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 ?? {});
+                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) {
+                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 ?? {});
+                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.apiKey;
+                const provider = normalizeManualProviderConfig(providerInput, {
+                    id: providerId,
+                    existingIds
+                });
+                const nextConfig = {
+                    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) {
+                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?.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 = {
+                    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) {
+                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 ?? {});
+                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 = {
+                    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) {
+                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 = {
+                    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) {
+                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 ?? {});
+                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 = {
+                    version: 1,
+                    providers: providerIds.map((providerId) => providersById.get(providerId)).filter((provider) => 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) {
+                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 ?? {});
+                const policy = body.policy;
+                const lockedProviderId = typeof body.lockedProviderId === "string" ? body.lockedProviderId.trim() : undefined;
+                const config = this.currentManualProviders();
+                const routing = policy === "locked"
+                    ? { policy: "locked", lockedProviderId }
+                    : { policy: "fallback" };
+                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 = {
+                    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) {
+                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) {
+                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;
+                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) {
+                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 {
@@ -3214,6 +4437,12 @@ function withLiveClawtipWalletState(payment, home) {
         }
     };
 }
+function paymentLabel(method) {
+    if (method === "clawtip") {
+        return "ClawTip";
+    }
+    return method;
+}
 function normalizeClawtipActivationPayment(bootstrap) {
     if (!bootstrap.payment?.orderNo || !bootstrap.payment.indicator || !bootstrap.payment.resourceUrl) {
         throw new Error("ClawTip bootstrap response missing orderNo, indicator, or resourceUrl.");
@@ -3247,6 +4476,9 @@ function readConfigString(config, key) {
 function readConfigBoolean(config, key) {
     return config?.[key] === true;
 }
+function normalizePaymentMethodName(method) {
+    return method.trim().toLowerCase();
+}
 function selectedSellerIdForRouting(routing) {
     return routing.mode === "fixed" ? routing.sellerId : undefined;
 }
@@ -3311,6 +4543,24 @@ function catalogSnapshotFromRegistry(registry) {
         }))
     };
 }
+function parseOpenAiModelIds(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [];
+    }
+    const data = value.data;
+    if (!Array.isArray(data)) {
+        return [];
+    }
+    return data
+        .flatMap((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            return [];
+        }
+        const id = entry.id;
+        return typeof id === "string" && id.trim().length > 0 ? [id.trim()] : [];
+    })
+        .filter((id, index, all) => all.indexOf(id) === index);
+}
 function normalizeTrustedRegistryCache(value) {
     if (!value || typeof value !== "object") {
         return undefined;