@tokenbuddy/tokenbuddy 1.0.39 → 1.0.41

package/dist/src/daemon.js

@@ -21,6 +21,7 @@ import { PrewarmScheduler } from "./prewarm-scheduler.js";
 import { SellerConcurrencyLimiter } from "./seller-concurrency-limiter.js";
 import { SellerMetadataCache } from "./seller-metadata-cache.js";
 import { planSellerRouteSet } from "./seller-route-planner.js";
+import { buildSellerRouteRecommendations } from "./seller-route-recommendations.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";
@@ -193,6 +194,13 @@ function safeBillingServiceTier(value) {
 function safeBillingUnit(value) {
     return value === "tokens" || value === "images" ? value : undefined;
 }
+function safeBillingSource(value) {
+    if (typeof value !== "string")
+        return undefined;
+    return ["provider_reported", "seller_computed", "reservation_fallback", "buyer_estimated"].includes(value)
+        ? value
+        : undefined;
+}
 function safeShortDisplayString(value) {
     if (typeof value !== "string")
         return undefined;
@@ -208,9 +216,11 @@ function billingBreakdownSummary(value) {
     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 cacheWritePriceMicrosPer1m = nonNegativeIntegerField(data.cacheWritePriceMicrosPer1m ?? data.cache_write_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 cacheWriteCostMicros = nonNegativeIntegerField(data.cacheWriteCostMicros ?? data.cache_write_cost_micros);
     const originalUsdMicros = nonNegativeIntegerField(data.originalUsdMicros ?? data.original_usd_micros);
     const billingMultiplier = nonNegativeFiniteField(data.billingMultiplier ?? data.billing_multiplier);
     if (inputPriceMicrosPer1m === undefined ||
@@ -224,13 +234,17 @@ function billingBreakdownSummary(value) {
         return undefined;
     }
     return {
+        billingSource: safeBillingSource(data.billingSource ?? data.billing_source),
+        reportedCostUsdMicros: nonNegativeIntegerField(data.reportedCostUsdMicros ?? data.reported_cost_usd_micros),
         billingUnit: safeBillingUnit(data.billingUnit ?? data.billing_unit),
         inputPriceMicrosPer1m,
         outputPriceMicrosPer1m,
         cacheReadPriceMicrosPer1m,
+        cacheWritePriceMicrosPer1m,
         inputCostMicros,
         outputCostMicros,
         cacheReadCostMicros,
+        cacheWriteCostMicros,
         originalUsdMicros,
         billingMultiplier,
         serviceTier: safeBillingServiceTier(data.serviceTier ?? data.service_tier),
@@ -243,6 +257,20 @@ function billingBreakdownSummary(value) {
         imageCostMicrosPerImage: nonNegativeIntegerField(data.imageCostMicrosPerImage ?? data.image_cost_micros_per_image)
     };
 }
+function billableUsageSummary(value) {
+    const data = usageRecord(value);
+    if (!data)
+        return undefined;
+    return {
+        inputTokens: nonNegativeIntegerField(data.inputTokens ?? data.input_tokens),
+        outputTokens: nonNegativeIntegerField(data.outputTokens ?? data.output_tokens),
+        cacheReadTokens: nonNegativeIntegerField(data.cacheReadTokens ?? data.cache_read_tokens),
+        cacheWriteTokens: nonNegativeIntegerField(data.cacheWriteTokens ?? data.cache_write_tokens),
+        reasoningTokens: nonNegativeIntegerField(data.reasoningTokens ?? data.reasoning_tokens),
+        audioInputTokens: nonNegativeIntegerField(data.audioInputTokens ?? data.audio_input_tokens),
+        webSearchCalls: nonNegativeIntegerField(data.webSearchCalls ?? data.web_search_calls)
+    };
+}
 function imageUsageMetadata(responseBody, requestBody) {
     const responseImages = Array.isArray(responseBody?.data) ? responseBody.data : undefined;
     const firstImage = responseImages?.find((item) => item && typeof item === "object");
@@ -353,11 +381,25 @@ function parseSellerSettlementObject(raw) {
             remainingCreditMicros,
             reservedBalanceMicros: numericHeaderField(parsed.reservedBalanceMicros ?? parsed.reserved_balance_micros),
             spentMicros: numericHeaderField(parsed.spentMicros ?? parsed.spent_micros),
+            pricingCurrency: typeof parsed.pricingCurrency === "string"
+                ? parsed.pricingCurrency
+                : typeof parsed.pricing_currency === "string"
+                    ? parsed.pricing_currency
+                    : undefined,
+            settlementUnit: typeof parsed.settlementUnit === "string"
+                ? parsed.settlementUnit
+                : typeof parsed.settlement_unit === "string"
+                    ? parsed.settlement_unit
+                    : undefined,
+            usdToMicrosRate: numericHeaderField(parsed.usdToMicrosRate ?? parsed.usd_to_micros_rate),
             priceVersion: typeof parsed.priceVersion === "string"
                 ? parsed.priceVersion
                 : typeof parsed.price_version === "string"
                     ? parsed.price_version
                     : undefined,
+            billingSource: safeBillingSource(parsed.billingSource ?? parsed.billing_source),
+            reportedCostUsdMicros: numericHeaderField(parsed.reportedCostUsdMicros ?? parsed.reported_cost_usd_micros),
+            billableUsage: billableUsageSummary(parsed.billableUsage ?? parsed.billable_usage),
             billingBreakdown: billingBreakdownSummary(parsed.billingBreakdown ?? parsed.billing_breakdown)
         };
     }
@@ -1951,7 +1993,7 @@ export class TokenbuddyDaemon {
         const registrySellers = reorderDefaultSellerFirst(registry.sellers, registry.defaultSeller);
         await this.refreshSellerRouteMetadata(registrySellers);
         this.sellerPool.ensureRegistrySellers(registrySellers);
-        this.scheduleLazyPrewarmIfNeeded(modelId, protocol, paymentMethod);
+        const lazyPrewarmDecision = this.scheduleLazyPrewarmIfNeeded(modelId, protocol, paymentMethod);
         this.sellerPool.recycleOpenCircuits();
         const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
         const concurrencySnapshot = this.sellerConcurrencyLimiter.snapshot();
@@ -1986,6 +2028,26 @@ export class TokenbuddyDaemon {
             routeSourceReason: planned.sourceReason,
             routeReason: planned.reason,
             candidateDiagnostics: planned.diagnostics,
+            prewarmCachePresent: lazyPrewarmDecision.freshness.present,
+            prewarmCacheState: lazyPrewarmDecision.freshness.state,
+            prewarmCacheExpired: lazyPrewarmDecision.freshness.expired,
+            prewarmCacheExpiringSoon: lazyPrewarmDecision.freshness.expiringSoon,
+            prewarmCacheRemainingMs: lazyPrewarmDecision.freshness.remainingMs,
+            prewarmCacheCandidateCount: lazyPrewarmDecision.freshness.entry?.candidates.length ?? 0,
+            prewarmLazyScheduled: lazyPrewarmDecision.scheduled,
+            prewarmLazyReason: lazyPrewarmDecision.reason,
+            poolSnapshotCount: poolById.size,
+            localConcurrencyEnabled: concurrencySnapshot.enabled,
+            plannedRoutes: planned.routes.map((route, index) => ({
+                rank: index + 1,
+                sellerId: route.seller.id,
+                routeState: route.metrics.routeState,
+                healthScore: route.metrics.healthScore,
+                ttftMs: route.metrics.ttftMs,
+                avgTokensPerSecond: route.metrics.avgTokensPerSecond,
+                discountRatio: route.metrics.discountRatio,
+                registryOrder: route.metrics.registryOrder
+            })),
             sellerCount: planned.routes.length,
             selectedSellerId: planned.routes[0]?.seller.id,
             selectedSellerName: planned.routes[0]?.seller.name,
@@ -2071,11 +2133,11 @@ export class TokenbuddyDaemon {
     scheduleLazyPrewarmIfNeeded(modelId, protocol, paymentMethod) {
         const freshness = this.prewarmCache.freshness(modelId, protocol, paymentMethod);
         if (freshness.present && !freshness.expired) {
-            return;
+            return { scheduled: false, reason: "fresh", freshness };
         }
         const key = prewarmKey(modelId, protocol, paymentMethod);
         if (this.lazyPrewarmKeys.has(key)) {
-            return;
+            return { scheduled: false, reason: "already_scheduled", freshness };
         }
         this.lazyPrewarmKeys.add(key);
         logger.info("prewarm.lazy.scheduled", "lazy prewarm scheduled for requested model", {
@@ -2092,6 +2154,7 @@ export class TokenbuddyDaemon {
         }).finally(() => {
             this.lazyPrewarmKeys.delete(key);
         });
+        return { scheduled: true, reason: "scheduled", freshness };
     }
     schedulePrewarmForModel(input) {
         if (!input.protocol || !input.paymentMethod) {
@@ -2137,6 +2200,22 @@ export class TokenbuddyDaemon {
         }
         return "soft_5xx";
     }
+    classifyRouteException(error, responseStarted) {
+        if (responseStarted) {
+            return "stream_aborted";
+        }
+        if (this.isBuyerDeadlineError(error)) {
+            return "deadline";
+        }
+        return "soft_5xx";
+    }
+    isBuyerDeadlineError(error) {
+        const message = this.failoverErrorMessage(error).toLowerCase();
+        if (message.includes("buyer deadline exceeded")) {
+            return true;
+        }
+        return error instanceof Error && error.name === "AbortError";
+    }
     /**
      * Emit the structured failover log line. The decision itself is
      * produced by `RouteFailover.decide`; this helper exists only to keep
@@ -2160,7 +2239,14 @@ export class TokenbuddyDaemon {
                 nextAttempt: context.attempt + 1,
                 nextAttemptNumber: context.attempt + 2,
                 reason: decision.reason,
+                controllerAction: decision.action,
+                failureKind: context.failureKind,
                 status: context.status,
+                protocol: context.protocol,
+                paymentMethod: context.paymentMethod,
+                routePlanSource: context.routePlanSource,
+                routePlanReason: context.routePlanReason,
+                routePlanSellerCount: context.routePlanSellerCount,
                 retryDelayMs: decision.retryDelayMs
             });
             return;
@@ -2179,7 +2265,14 @@ export class TokenbuddyDaemon {
                 attempt: context.attempt,
                 attemptNumber: context.attempt + 1,
                 reason: decision.reason,
+                controllerAction: decision.action,
+                failureKind: context.failureKind,
                 status: context.status,
+                protocol: context.protocol,
+                paymentMethod: context.paymentMethod,
+                routePlanSource: context.routePlanSource,
+                routePlanReason: context.routePlanReason,
+                routePlanSellerCount: context.routePlanSellerCount,
                 wastedCreditMicros: decision.wastedCreditMicros,
                 freshPurchase: decision.freshPurchase,
                 retryAttemptsBeforeFailover: decision.retryAttemptsBeforeFailover
@@ -2199,7 +2292,13 @@ export class TokenbuddyDaemon {
             attemptNumber: context.attempt + 1,
             action: decision.action,
             reason: decision.reason,
-            status: context.status
+            failureKind: context.failureKind,
+            status: context.status,
+            protocol: context.protocol,
+            paymentMethod: context.paymentMethod,
+            routePlanSource: context.routePlanSource,
+            routePlanReason: context.routePlanReason,
+            routePlanSellerCount: context.routePlanSellerCount
         });
     }
     logPaymentProofResolved(route, proofSource, requestId) {
@@ -2365,11 +2464,12 @@ export class TokenbuddyDaemon {
         if (entry.upstreamStatus === "degraded") {
             return "degraded";
         }
-        if (Number.isFinite(entry.healthScore)) {
-            if (entry.healthScore < 40) {
+        const healthScore = entry.healthScore;
+        if (Number.isFinite(healthScore)) {
+            if (healthScore < 40) {
                 return "error";
             }
-            if (entry.healthScore < 70) {
+            if (healthScore < 70) {
                 return "degraded";
             }
         }
@@ -2408,6 +2508,10 @@ export class TokenbuddyDaemon {
             promptTokens: 0,
             completionTokens: 0,
             cacheReadTokens: 0,
+            cacheWriteTokens: 0,
+            reasoningTokens: 0,
+            audioInputTokens: 0,
+            webSearchCalls: 0,
             billedMicros: 0
         };
         if (!bodyText.trim()) {
@@ -2425,6 +2529,10 @@ export class TokenbuddyDaemon {
         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 completionDetails = usageRecord(usage?.completion_tokens_details);
+        const outputDetails = usageRecord(usage?.output_tokens_details);
+        const cacheCreation = usageRecord(usage?.cache_creation);
+        const serverToolUse = usageRecord(usage?.server_tool_use);
         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)
@@ -2432,18 +2540,36 @@ export class TokenbuddyDaemon {
             ?? nonNegativeIntegerField(usage?.cache_read_input_tokens)
             ?? nonNegativeIntegerField(usage?.cache_read_tokens)
             ?? 0;
+        const cacheCreationOneHour = nonNegativeIntegerField(cacheCreation?.ephemeral_1h_input_tokens);
+        const cacheCreationFiveMinute = nonNegativeIntegerField(cacheCreation?.ephemeral_5m_input_tokens);
+        const cacheCreationBucketTokens = cacheCreationOneHour !== undefined || cacheCreationFiveMinute !== undefined
+            ? (cacheCreationOneHour ?? 0) + (cacheCreationFiveMinute ?? 0)
+            : undefined;
+        const cacheWriteTokens = nonNegativeIntegerField(promptDetails?.cache_write_tokens)
+            ?? nonNegativeIntegerField(usage?.cache_creation_input_tokens)
+            ?? cacheCreationBucketTokens
+            ?? 0;
+        const reasoningTokens = nonNegativeIntegerField(completionDetails?.reasoning_tokens)
+            ?? nonNegativeIntegerField(outputDetails?.reasoning_tokens)
+            ?? 0;
+        const audioInputTokens = nonNegativeIntegerField(promptDetails?.audio_tokens) ?? 0;
+        const webSearchCalls = nonNegativeIntegerField(serverToolUse?.web_search_requests) ?? 0;
         const upstreamCostMicros = extractUpstreamCostMicros(data, usage);
         const billablePromptTokens = Math.max(0, promptTokens - cacheReadTokens);
         const imageMetadata = endpoint === "/v1/images/generations"
             ? imageUsageMetadata(data, usageRecord(requestBody))
             : {};
         return {
+            ...imageMetadata,
             promptTokens,
             completionTokens,
             cacheReadTokens,
+            cacheWriteTokens,
+            reasoningTokens,
+            audioInputTokens,
+            webSearchCalls,
             billedMicros: upstreamCostMicros ?? (billablePromptTokens + completionTokens) * 4,
-            ...(upstreamCostMicros === undefined ? {} : { upstreamCostMicros }),
-            ...imageMetadata
+            ...(upstreamCostMicros === undefined ? {} : { upstreamCostMicros })
         };
     }
     readUsageFromSse(bodyText, endpoint, requestBody) {
@@ -2499,18 +2625,29 @@ export class TokenbuddyDaemon {
             status: settlement ? "settled" : "estimated",
             promptTokens: usage.promptTokens,
             completionTokens: usage.completionTokens,
-            cacheReadTokens: usage.cacheReadTokens,
+            cacheReadTokens: settlement?.billableUsage?.cacheReadTokens ?? usage.cacheReadTokens,
+            cacheWriteTokens: settlement?.billableUsage?.cacheWriteTokens ?? usage.cacheWriteTokens,
+            reasoningTokens: settlement?.billableUsage?.reasoningTokens ?? usage.reasoningTokens,
+            audioInputTokens: settlement?.billableUsage?.audioInputTokens ?? usage.audioInputTokens,
+            webSearchCalls: settlement?.billableUsage?.webSearchCalls ?? usage.webSearchCalls,
             billedMicros: settledMicros ?? usage.billedMicros,
             estimatedMicros: usage.billedMicros,
             settledMicros,
             settledUsdMicros: settlement?.settledUsdMicros,
+            pricingCurrency: settlement?.pricingCurrency,
+            settlementUnit: settlement?.settlementUnit,
+            usdToMicrosRate: settlement?.usdToMicrosRate,
+            billingSource: settlement?.billingSource ?? billingBreakdown?.billingSource ?? (settlement ? "seller_computed" : "buyer_estimated"),
+            reportedCostUsdMicros: settlement?.reportedCostUsdMicros ?? billingBreakdown?.reportedCostUsdMicros,
             priceVersion: settlement?.priceVersion,
             inputPriceMicrosPer1m: billingBreakdown?.inputPriceMicrosPer1m,
             outputPriceMicrosPer1m: billingBreakdown?.outputPriceMicrosPer1m,
             cacheReadPriceMicrosPer1m: billingBreakdown?.cacheReadPriceMicrosPer1m,
+            cacheWritePriceMicrosPer1m: billingBreakdown?.cacheWritePriceMicrosPer1m,
             inputCostMicros: billingBreakdown?.inputCostMicros,
             outputCostMicros: billingBreakdown?.outputCostMicros,
             cacheReadCostMicros: billingBreakdown?.cacheReadCostMicros,
+            cacheWriteCostMicros: billingBreakdown?.cacheWriteCostMicros,
             originalUsdMicros: billingBreakdown?.originalUsdMicros,
             billingMultiplier: billingBreakdown?.billingMultiplier,
             serviceTier: billingBreakdown?.serviceTier,
@@ -3528,7 +3665,11 @@ export class TokenbuddyDaemon {
             const usage = this.readUsage(responseBody, endpoint, upstreamBody);
             const durationMs = Date.now() - startedAt;
             const ttftMs = firstByteAt !== undefined ? firstByteAt - startedAt : undefined;
-            const billedMicros = usage.billedMicros > 0 ? usage.billedMicros : Math.max(1, bytes);
+            const billedMicros = usage.upstreamCostMicros !== undefined
+                ? usage.upstreamCostMicros
+                : usage.billedMicros > 0
+                    ? usage.billedMicros
+                    : Math.max(1, bytes);
             const completionTokens = usage.completionTokens;
             const avgTokensPerSecond = completionTokens > 0
                 ? averageOutputTokensPerSecond(completionTokens, durationMs, ttftMs)
@@ -3549,8 +3690,15 @@ export class TokenbuddyDaemon {
                 promptTokens: usage.promptTokens,
                 completionTokens: usage.completionTokens,
                 cacheReadTokens: usage.cacheReadTokens,
+                cacheWriteTokens: usage.cacheWriteTokens,
+                reasoningTokens: usage.reasoningTokens,
+                audioInputTokens: usage.audioInputTokens,
+                webSearchCalls: usage.webSearchCalls,
                 billedMicros,
                 estimatedMicros: billedMicros,
+                pricingCurrency: usage.upstreamCostMicros === undefined ? undefined : "USD",
+                billingSource: usage.upstreamCostMicros === undefined ? "buyer_estimated" : "provider_reported",
+                reportedCostUsdMicros: usage.upstreamCostMicros,
                 priceVersion: `local-provider:${provider.id}`,
                 billingUnit: endpoint === "/v1/images/generations" ? "images" : "tokens",
                 balanceSource: "self_funded_provider",
@@ -3587,8 +3735,15 @@ export class TokenbuddyDaemon {
             promptTokens: usage.promptTokens,
             completionTokens: usage.completionTokens,
             cacheReadTokens: usage.cacheReadTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            reasoningTokens: usage.reasoningTokens,
+            audioInputTokens: usage.audioInputTokens,
+            webSearchCalls: usage.webSearchCalls,
             billedMicros: usage.billedMicros,
             estimatedMicros: usage.billedMicros,
+            pricingCurrency: usage.upstreamCostMicros === undefined ? undefined : "USD",
+            billingSource: usage.upstreamCostMicros === undefined ? "buyer_estimated" : "provider_reported",
+            reportedCostUsdMicros: usage.upstreamCostMicros,
             priceVersion: `local-provider:${provider.id}`,
             billingUnit: endpoint === "/v1/images/generations" ? "images" : "tokens",
             imageCount: usage.imageCount,
@@ -3622,12 +3777,32 @@ export class TokenbuddyDaemon {
         const modelId = resolvedModelId;
         const requestId = req.header("x-request-id") || (body && typeof body === "object" ? body.requestId : undefined) || `proxy_req_${crypto.randomBytes(8).toString("hex")}`;
         const idempotencyKey = req.header("idempotency-key") || `idem_${crypto.randomBytes(12).toString("hex")}`;
+        const protocol = this.endpointProtocol(endpoint);
+        const providerMode = this.currentProviderMode().mode;
+        logger.info("proxy.request.received", "proxy request received", {
+            requestId,
+            requestedModel: requestedModelId,
+            resolvedModel: modelId,
+            model: modelId,
+            endpoint,
+            protocol,
+            providerMode,
+            stream: Boolean(body.stream)
+        });
         if (!modelId) {
+            logger.warn("proxy.request.rejected", "proxy request rejected before route selection", {
+                requestId,
+                endpoint,
+                protocol,
+                providerMode,
+                errorCode: "model_required",
+                durationMs: Date.now() - startedAt
+            });
             res.status(400).json({ error: { code: "model_required", message: "request body must include model" } });
             return;
         }
         try {
-            const routeSelection = this.currentProviderMode().mode === "manual"
+            const routeSelection = providerMode === "manual"
                 ? this.selectManualProviderRoutes(endpoint, modelId)
                 : await this.selectSellerRoutes(endpoint, modelId, requestId);
             const { routes, plan, paymentMethod } = routeSelection;
@@ -3684,6 +3859,7 @@ export class TokenbuddyDaemon {
                         sellerKey,
                         sellerId: sellerKey,
                         model: modelId,
+                        requestedModel: requestedModelId,
                         endpoint,
                         protocol: route.protocol,
                         paymentMethod: route.paymentMethod,
@@ -3704,6 +3880,7 @@ export class TokenbuddyDaemon {
                         sellerKey,
                         sellerId: sellerKey,
                         model: modelId,
+                        requestedModel: requestedModelId,
                         endpoint,
                         protocol: route.protocol,
                         paymentMethod: route.paymentMethod,
@@ -3811,8 +3988,14 @@ export class TokenbuddyDaemon {
                                     attempt,
                                     attemptNumber: attempt + 1,
                                     reason: "purchase_failed",
+                                    failureKind: "purchase_failed",
                                     controllerReason: decision.reason,
-                                    controllerAction: decision.action
+                                    controllerAction: decision.action,
+                                    protocol: route.protocol,
+                                    paymentMethod: route.paymentMethod,
+                                    routePlanSource: route.planSource,
+                                    routePlanReason: route.planReason,
+                                    routePlanSellerCount: route.planSellerCount
                                 });
                                 lastError = purchaseError;
                                 break;
@@ -3908,7 +4091,13 @@ export class TokenbuddyDaemon {
                                         routeIndex,
                                         routesRemaining: routes.length - routeIndex,
                                         attempt,
-                                        status: upstreamResponse.status
+                                        status: upstreamResponse.status,
+                                        failureKind: kind,
+                                        protocol: route.protocol,
+                                        paymentMethod: route.paymentMethod,
+                                        routePlanSource: route.planSource,
+                                        routePlanReason: route.planReason,
+                                        routePlanSellerCount: route.planSellerCount
                                     });
                                     if (decision.action === "fail_fast" || decision.action === "abort") {
                                         this.copyUpstreamHeaders(upstreamResponse, res);
@@ -4034,7 +4223,7 @@ export class TokenbuddyDaemon {
                         }
                         catch (routeError) {
                             lastError = routeError;
-                            const kind = "deadline";
+                            const kind = this.classifyRouteException(routeError, res.headersSent);
                             const decision = this.routeFailover.decide({
                                 sellerId: sellerKey,
                                 errorKind: kind,
@@ -4049,16 +4238,35 @@ export class TokenbuddyDaemon {
                                 routeIndex,
                                 routesRemaining: routes.length - routeIndex,
                                 attempt,
-                                reason: "exception"
+                                reason: "exception",
+                                failureKind: kind,
+                                protocol: route.protocol,
+                                paymentMethod: route.paymentMethod,
+                                routePlanSource: route.planSource,
+                                routePlanReason: route.planReason,
+                                routePlanSellerCount: route.planSellerCount
                             });
                             logger.warn("proxy.route.failed", "seller route failed before response", {
                                 requestId,
                                 sellerKey,
                                 model: modelId,
                                 endpoint,
+                                failureKind: kind,
+                                protocol: route.protocol,
+                                paymentMethod: route.paymentMethod,
+                                routePlanSource: route.planSource,
+                                routePlanReason: route.planReason,
+                                routePlanSellerCount: route.planSellerCount,
+                                responseStarted: res.headersSent,
                                 errorMessage: this.failoverErrorMessage(routeError),
                                 durationMs: Date.now() - startedAt
                             });
+                            if (kind === "stream_aborted") {
+                                if (!res.writableEnded) {
+                                    res.end();
+                                }
+                                return;
+                            }
                             if (decision.action === "retry_same_seller") {
                                 attempt += 1;
                                 if (decision.retryDelayMs) {
@@ -4078,6 +4286,19 @@ export class TokenbuddyDaemon {
                     lease.release();
                 }
             }
+            logger.warn("route.failover.exhausted", "all seller routes exhausted", {
+                requestId,
+                model: modelId,
+                requestedModel: requestedModelId,
+                endpoint,
+                protocol,
+                providerMode,
+                routePlanReason: plan.reason,
+                routePlanSellerCount: routes.length,
+                attemptedSellerIds: routes.map((route) => route.seller.id),
+                lastErrorMessage: lastError instanceof Error ? lastError.message : lastError === undefined ? undefined : String(lastError),
+                durationMs: Date.now() - startedAt
+            });
             throw lastError instanceof Error ? lastError : new Error("all seller routes failed");
         }
         catch (error) {
@@ -5303,6 +5524,40 @@ export class TokenbuddyDaemon {
         });
         // 2) GET /routing/preview — 算「假如改完会怎样」，不改 state
         //   query: modelId? protocol? paymentMethod? mode? scorer? sellerId? sellerIds?(逗号分隔)
+        controlApp.get("/routing/recommendations", async (req, res) => {
+            try {
+                const scope = buildRecommendationScopeFromQuery(req.query);
+                const result = await this.buildRoutingRecommendations({
+                    modelIds: parseCommaSeparatedList(typeof req.query.modelIds === "string" ? req.query.modelIds : ""),
+                    protocol: typeof req.query.protocol === "string" ? req.query.protocol : undefined,
+                    paymentMethod: typeof req.query.paymentMethod === "string" ? req.query.paymentMethod : undefined,
+                    scorer: parseRoutingScorerQuery(typeof req.query.scorer === "string" ? req.query.scorer : ""),
+                    scope,
+                    topK: parsePositiveIntegerQuery(typeof req.query.topK === "string" ? req.query.topK : "")
+                });
+                if ("error" in result) {
+                    res.status(409).json({
+                        error: { code: result.error, message: `cannot build recommendations: ${result.error}` }
+                    });
+                    return;
+                }
+                logger.info("routing.recommendations.built", "routing recommendations built", {
+                    scope: result.scope.type,
+                    focusModelCount: result.focusModelSet.length,
+                    protocol: result.protocol,
+                    protocolByModelId: result.protocolByModelId,
+                    sellerCount: result.sellers.length,
+                    excludedSellerCount: result.excludedSellers.length,
+                    scorer: result.scorer
+                });
+                res.status(200).json(result);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("routing.recommendations.failed", "routing recommendations failed", { errorMessage });
+                res.status(400).json({ error: { code: "routing_recommendations_failed", message: errorMessage } });
+            }
+        });
         controlApp.get("/routing/preview", async (req, res) => {
             try {
                 const override = buildRoutingConfigFromQuery(req.query);
@@ -5602,6 +5857,71 @@ export class TokenbuddyDaemon {
         });
         return { modelId, protocol, paymentMethod, plan };
     }
+    async buildRoutingRecommendations(input) {
+        const registry = this.lastRegistrySnapshot ?? (this.forceRegistrySnapshotForTest ? null : await this.fetchRegistry());
+        if (!registry) {
+            return { error: "registry_not_loaded" };
+        }
+        const registrySellers = reorderDefaultSellerFirst(registry.sellers, registry.defaultSeller);
+        const focusModelSet = this.resolveRecommendationFocusSet(input.modelIds, registrySellers);
+        if (focusModelSet.length === 0) {
+            return { error: "no_focus_model_available" };
+        }
+        const paymentMethod = input.paymentMethod?.trim() || this.defaultPaymentMethod() || "clawtip";
+        const explicitProtocol = input.protocol?.trim();
+        const protocolByModelId = this.resolveRecommendationProtocols(focusModelSet, registrySellers, paymentMethod, explicitProtocol);
+        const protocol = explicitProtocol || recommendationProtocolLabel(protocolByModelId);
+        const scorer = input.scorer ?? this.currentAutoProviderConfig().scorer;
+        const scope = input.scope ?? { type: "recommended" };
+        await this.refreshSellerRouteMetadata(registrySellers);
+        this.sellerPool.ensureRegistrySellers(registrySellers);
+        const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
+        const concurrencySnapshot = this.sellerConcurrencyLimiter.snapshot();
+        const localConcurrencyBySellerId = new Map(concurrencySnapshot.active.map((entry) => [entry.sellerId, entry.activeCount]));
+        return buildSellerRouteRecommendations({
+            focusModelSet,
+            protocol,
+            protocolByModelId,
+            paymentMethod,
+            scorer,
+            scope,
+            topK: input.topK,
+            registrySellers,
+            prewarmCandidatesForModel: (modelId, protocolForModel) => this.prewarmCache.get(modelId, protocolForModel, paymentMethod)?.candidates,
+            sellerMetrics: Array.from(poolById.values()).map((entry) => this.routeMetricFromPoolEntry(entry, concurrencySnapshot.enabled
+                ? {
+                    localConcurrencyActive: localConcurrencyBySellerId.get(entry.sellerId) ?? 0,
+                    localConcurrencyLimit: concurrencySnapshot.maxInFlightPerSeller
+                }
+                : undefined)),
+            now: Date.now()
+        });
+    }
+    resolveRecommendationProtocols(modelIds, registrySellers, paymentMethod, explicitProtocol) {
+        return Object.fromEntries(modelIds.map((modelId) => [
+            modelId,
+            explicitProtocol || this.resolveRecommendationProtocol(modelId, paymentMethod, registrySellers)
+        ]));
+    }
+    resolveRecommendationProtocol(modelId, paymentMethod, registrySellers) {
+        for (const protocol of recommendationProtocolPriority(modelId)) {
+            if (registrySellers.some((seller) => recommendationSellerSupports(seller, modelId, protocol, paymentMethod))) {
+                return protocol;
+            }
+        }
+        return this.resolvePrewarmProtocol(modelId, paymentMethod) ?? recommendationProtocolPriority(modelId)[0] ?? "chat_completions";
+    }
+    resolveRecommendationFocusSet(modelIds, registrySellers) {
+        const explicit = this.uniqueModelIds(modelIds ?? []);
+        if (explicit.length > 0) {
+            return explicit;
+        }
+        const focusSet = this.resolveFocusSet();
+        if (focusSet.length > 0) {
+            return focusSet;
+        }
+        return this.uniqueModelIds(registrySellers.flatMap((seller) => seller.models ?? [])).slice(0, 20);
+    }
     async runStartupPrewarmSweep() {
         const focusSet = this.resolveFocusSet();
         if (focusSet.length === 0) {
@@ -5626,7 +5946,7 @@ export class TokenbuddyDaemon {
         }
     }
     resolvePrewarmProtocol(modelId, paymentMethod = "clawtip") {
-        for (const protocol of ["chat_completions", "messages", "responses", "images_generations"]) {
+        for (const protocol of recommendationProtocolPriority(modelId)) {
             if (this.modelIndex.sellersFor(modelId, { protocol, paymentMethod }).length > 0) {
                 return protocol;
             }
@@ -6031,6 +6351,90 @@ function normalizeTrustedRegistryCache(value) {
         trust: data.trust
     };
 }
+function recommendationProtocolLabel(protocolByModelId) {
+    const protocols = Array.from(new Set(Object.values(protocolByModelId).filter(Boolean)));
+    if (protocols.length === 1) {
+        return protocols[0] ?? "chat_completions";
+    }
+    return protocols.length > 1 ? "mixed" : "chat_completions";
+}
+function recommendationProtocolPriority(modelId) {
+    const normalized = normalizeRecommendationLookup(modelId);
+    if (normalized.includes("gpt-image") || normalized.includes("dall-e")) {
+        return ["images_generations", "chat_completions", "responses", "messages"];
+    }
+    if (normalized.includes("claude") || normalized.includes("anthropic")) {
+        return ["messages", "chat_completions", "responses", "images_generations"];
+    }
+    return ["chat_completions", "responses", "messages", "images_generations"];
+}
+function recommendationSellerSupports(seller, modelId, protocol, paymentMethod) {
+    return recommendationSellerSupportsModel(seller, modelId) &&
+        recommendationSellerSupportsProtocol(seller, protocol) &&
+        recommendationSellerSupportsPayment(seller, paymentMethod);
+}
+function recommendationSellerSupportsModel(seller, modelId) {
+    const normalized = normalizeRecommendationLookup(modelId);
+    return (seller.models ?? []).some((model) => normalizeRecommendationLookup(model) === normalized);
+}
+function recommendationSellerSupportsProtocol(seller, protocol) {
+    const normalized = normalizeRecommendationLookup(protocol);
+    return recommendationProtocolAliases(seller.supportedProtocols ?? [])
+        .some((entry) => normalizeRecommendationLookup(entry) === normalized);
+}
+function recommendationSellerSupportsPayment(seller, paymentMethod) {
+    const normalized = normalizeRecommendationLookup(paymentMethod);
+    return (seller.paymentMethods ?? []).some((entry) => normalizeRecommendationLookup(entry) === normalized);
+}
+function recommendationProtocolAliases(protocols) {
+    return protocols.includes("anthropic_messages") && !protocols.includes("messages")
+        ? [...protocols, "messages"]
+        : protocols;
+}
+function normalizeRecommendationLookup(value) {
+    return value.trim().toLowerCase();
+}
+function buildRecommendationScopeFromQuery(query) {
+    const scope = typeof query.scope === "string" ? query.scope.trim() : "";
+    const sellerIdsRaw = typeof query.sellerIds === "string" ? query.sellerIds.trim() : "";
+    if (!scope || scope === "recommended") {
+        return { type: "recommended" };
+    }
+    if (scope !== "custom") {
+        throw new Error("scope must be recommended or custom");
+    }
+    return {
+        type: "custom",
+        sellerIds: parseSellerIdList(sellerIdsRaw)
+    };
+}
+function parseRoutingScorerQuery(value) {
+    const scorer = value.trim();
+    if (!scorer) {
+        return undefined;
+    }
+    if (scorer !== "speed" && scorer !== "discount" && scorer !== "balanced") {
+        throw new Error("scorer must be speed, discount, or balanced");
+    }
+    return scorer;
+}
+function parsePositiveIntegerQuery(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error("topK must be a positive integer");
+    }
+    return parsed;
+}
+function parseCommaSeparatedList(value) {
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
 /**
  * 从 query string 构造 `BuyerSellerRoutingConfig` override（用于 GET /routing/preview）。
  * 接受 `mode` / `scorer` / `sellerId` / `sellerIds`（逗号分隔）。