@tokenbuddy/tokenbuddy 1.0.14 → 1.0.15

package/dist/src/daemon.js

@@ -2,20 +2,78 @@ import express from "express";
 import * as crypto from "crypto";
 import { spawn } from "child_process";
 import * as fs from "fs";
+import * as path from "path";
+import { ErrorCode } from "@tokenbuddy/contracts";
 import { createModuleLogger } from "@tokenbuddy/logging";
 import { BuyerStore } from "./buyer-store.js";
+import { fetchClawtipBootstrap } from "./clawtip-bootstrap.js";
+import { inspectOpenClawWalletConfig, } from "./init-payment-options.js";
+import { startClawtipWalletBootstrap, waitForClawtipActivationConfirmation, } from "./init-clawtip-activation.js";
 import { applyProviderInstall, detectProviders, previewProviderInstall, rollbackProviderInstall, } from "./provider-install.js";
 import { discoverSellerBackedModels, fetchSellerRegistry, normalizeSellerUrl, RegistryTooLargeError, } from "./seller-catalog.js";
 import { ModelIndex } from "./model-index.js";
-import { PrewarmCache } from "./prewarm-cache.js";
+import { PrewarmCache, prewarmKey } from "./prewarm-cache.js";
 import { CreditTracker } from "./credit-tracker.js";
 import { SellerPool } from "./seller-pool.js";
 import { RouteFailover } from "./route-failover.js";
 import { PrewarmScheduler } from "./prewarm-scheduler.js";
 import { planSellerRouteSet } from "./seller-route-planner.js";
-import { mergeSellerRoutingConfig, ROUTING_CONFIG_KEY } from "./seller-routing-config.js";
+import { assertSellerRoutingConfig, mergeSellerRoutingConfig, normalizeSellerRoutingConfig, parseSellerIdList, ROUTING_CONFIG_KEY } from "./seller-routing-config.js";
 const logger = createModuleLogger("tb-proxyd");
+const FOCUS_SET_CONFIG_KEY = "focus-set";
 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";
+function clientToolStatusFromProvider(provider) {
+    return {
+        id: provider.id,
+        name: provider.name,
+        status: provider.status,
+        detected: provider.detected,
+        configured: provider.configured,
+        configPath: provider.configPath,
+        commandName: provider.commandName,
+        reason: provider.reason,
+    };
+}
+function buildCustomClientToolStatus(proxyPort) {
+    const openaiBaseUrl = `http://127.0.0.1:${proxyPort}/v1`;
+    const anthropicBaseUrl = `http://127.0.0.1:${proxyPort}`;
+    return {
+        id: "custom",
+        name: "Custom client",
+        status: "manual",
+        detected: true,
+        configured: false,
+        reason: `OpenAI-compatible: ${openaiBaseUrl} · Anthropic-compatible: ${anthropicBaseUrl}`,
+        manualConfig: {
+            openaiBaseUrl,
+            anthropicBaseUrl,
+            apiKey: "TOKENBUDDY_PROXY",
+        },
+    };
+}
+/**
+ * 解析 `tb-ui` 构建产物目录(daemon 静态托管 SPA 用)。
+ * 优先级:env TB_UI_DIR > require.resolve("tb-ui") > 相对路径猜
+ * 找不到时记录 warning 仍允许 daemon 启动(纯 API 模式);静态请求会 404。
+ */
+function resolveUiDir() {
+    if (process.env.TB_UI_DIR)
+        return process.env.TB_UI_DIR;
+    try {
+        // require.resolve 在 npm workspaces 装好时能找到 tb-ui/package.json
+        const pkgPath = require.resolve("tb-ui/package.json");
+        return path.join(path.dirname(pkgPath), "dist");
+    }
+    catch {
+        // fallback: monorepo 假设 daemon dist 跟 tb-ui/dist 在同 root
+        // 用 __filename (jest cjs 编译下可用,生产 ESM 也兼容) 推回 src 再到 root
+        const here = typeof __filename !== "undefined" ? path.dirname(__filename) : process.cwd();
+        return path.resolve(here, "../../tb-ui/dist");
+    }
+}
 function numericHeaderField(value) {
     if (typeof value === "number" && Number.isFinite(value)) {
         return value;
@@ -123,6 +181,55 @@ function summarizeProxyBody(body) {
         temperaturePresent: data.temperature !== undefined
     };
 }
+function finiteNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function readErrorCode(bodyText) {
+    try {
+        const parsed = JSON.parse(bodyText);
+        const code = parsed.error?.code ?? parsed.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isBusyCapacityErrorBody(bodyText) {
+    if (!bodyText) {
+        return false;
+    }
+    return readErrorCode(bodyText) === ErrorCode.BusyCapacity;
+}
+function capacityBlockedUntilFromHealth(body, now) {
+    const capacity = body.capacity;
+    if (!capacity) {
+        return undefined;
+    }
+    const activeConnections = finiteNumber(capacity.activeConnections ?? capacity.active_connections);
+    const maxConnections = finiteNumber(capacity.maxConnections ?? capacity.max_connections);
+    const queueDepth = finiteNumber(capacity.queueDepth ?? capacity.queue_depth);
+    const maxQueueDepth = finiteNumber(capacity.maxQueueDepth ?? capacity.max_queue_depth);
+    if (activeConnections === undefined ||
+        maxConnections === undefined ||
+        queueDepth === undefined ||
+        maxQueueDepth === undefined) {
+        return undefined;
+    }
+    if (maxConnections <= 0) {
+        return undefined;
+    }
+    const connectionsFull = activeConnections >= maxConnections;
+    const queueUnavailable = maxQueueDepth <= 0;
+    const queueFull = queueUnavailable || queueDepth >= maxQueueDepth;
+    return connectionsFull && queueFull ? now + SELLER_CAPACITY_BLOCK_MS : undefined;
+}
 function reorderDefaultSellerFirst(sellers, defaultSellerId) {
     if (!defaultSellerId) {
         return sellers;
@@ -146,6 +253,15 @@ export class TokenbuddyDaemon {
     selectionMode;
     selectedSellerId;
     sellerRouting;
+    lastRoutingPrewarmKey;
+    lazyPrewarmKeys = new Set();
+    clawtipActivationWait;
+    clawtipActivationWaitCancelToken;
+    /**
+     * tb-ui v1 控制平面 `PUT /prewarm/focus-set` 写入的 explicit focus set。
+     * 优先级最高；`null` 表示回退到 env / historical（与 `resolveFocusSet()` 原行为一致）。
+     */
+    currentFocusSet = null;
     activePurchases = new Map();
     // v1.2 fallback pipeline: model-index, prewarm-cache, credit-tracker,
     // pool, and route-failover together replace the v1
@@ -170,10 +286,17 @@ export class TokenbuddyDaemon {
         this.tokenStore = new BuyerStore({ dbPath: config.dbPath });
         const storedRouting = this.tokenStore.getDaemonRuntimeConfig(ROUTING_CONFIG_KEY)
             ?.config;
+        const storedFocusSet = this.tokenStore.getDaemonRuntimeConfig(FOCUS_SET_CONFIG_KEY)
+            ?.config;
         this.config = config;
         this.sellerRouting = mergeSellerRoutingConfig(storedRouting, config.sellerRouting);
-        this.selectionMode = this.sellerRouting.mode === "fullAuto" ? "auto" : "manual";
-        this.selectedSellerId = this.sellerRouting.mode === "fixed" ? this.sellerRouting.sellerId : undefined;
+        this.selectionMode = selectionModeForRouting(this.sellerRouting);
+        this.selectedSellerId = selectedSellerIdForRouting(this.sellerRouting);
+        // tb-ui v1: explicit focus set 优先于 env / historical
+        if (storedFocusSet && Array.isArray(storedFocusSet.models)) {
+            const deduped = Array.from(new Set(storedFocusSet.models.map((m) => m.trim()).filter(Boolean)));
+            this.currentFocusSet = deduped.length > 0 ? deduped : null;
+        }
         // v1.2 §18.5: scheduler is created here (not in the field initializer)
         // because it needs the config-derived prober + idle interval.
         Object.assign(this, {
@@ -204,7 +327,22 @@ export class TokenbuddyDaemon {
                 if (!res.ok) {
                     return { ok: false, latencyMs: Date.now() - startedAt, httpStatus: res.status, errorMessage: `health returned ${res.status}` };
                 }
-                return { ok: true, latencyMs: Date.now() - startedAt, httpStatus: res.status };
+                const now = Date.now();
+                const body = await res.json();
+                const upstream = body.upstream;
+                const upstreamErrorClass = upstream?.lastErrorClass ?? upstream?.last_error_class;
+                return {
+                    ok: true,
+                    latencyMs: now - startedAt,
+                    httpStatus: res.status,
+                    upstreamStatus: typeof upstream?.status === "string"
+                        ? upstream.status
+                        : undefined,
+                    upstreamErrorClass: typeof upstreamErrorClass === "string"
+                        ? upstreamErrorClass
+                        : undefined,
+                    capacityBlockedUntil: capacityBlockedUntilFromHealth(body, now)
+                };
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -220,6 +358,193 @@ export class TokenbuddyDaemon {
         const address = this.proxyServer?.address?.();
         return typeof address === "object" && address ? address.port : this.config.proxyPort;
     }
+    clawtipStaticDir() {
+        return path.join(path.dirname(this.config.dbPath), "static", "clawtip");
+    }
+    bundledClawtipStaticDir() {
+        if (this.config.clawtipBundledStaticDir === false) {
+            return undefined;
+        }
+        if (typeof this.config.clawtipBundledStaticDir === "string") {
+            return fs.existsSync(this.config.clawtipBundledStaticDir) ? this.config.clawtipBundledStaticDir : undefined;
+        }
+        const here = typeof __filename !== "undefined" ? path.dirname(__filename) : process.cwd();
+        const candidates = [
+            path.resolve(here, "../static/clawtip"),
+            path.resolve(here, "../../static/clawtip"),
+            path.resolve(process.cwd(), "packages/tokenbuddy-cli/static/clawtip")
+        ];
+        return candidates.find((candidate) => fs.existsSync(candidate));
+    }
+    clawtipPublicUrl(fileName) {
+        return `${CLAWTIP_STATIC_ROUTE}/${encodeURIComponent(fileName)}`;
+    }
+    ensureClawtipStaticAssets() {
+        const outputDir = this.clawtipStaticDir();
+        fs.mkdirSync(outputDir, { recursive: true });
+        const rechargeOutputPath = path.join(outputDir, CLAWTIP_RECHARGE_QR_FILE);
+        if (fs.existsSync(rechargeOutputPath)) {
+            return;
+        }
+        const bundledDir = this.bundledClawtipStaticDir();
+        const rechargeSourcePath = bundledDir ? path.join(bundledDir, CLAWTIP_RECHARGE_QR_FILE) : undefined;
+        if (rechargeSourcePath && fs.existsSync(rechargeSourcePath)) {
+            fs.copyFileSync(rechargeSourcePath, rechargeOutputPath);
+        }
+    }
+    copyClawtipQrToStatic(mediaPath, orderNo) {
+        if (!fs.existsSync(mediaPath)) {
+            throw new Error(`ClawTip QR image does not exist: ${mediaPath}`);
+        }
+        const extension = safeQrExtension(mediaPath);
+        const fileName = `${safeStaticFileSegment(orderNo)}-${Date.now()}${extension}`;
+        const outputDir = this.clawtipStaticDir();
+        fs.mkdirSync(outputDir, { recursive: true });
+        const outputPath = path.join(outputDir, fileName);
+        fs.copyFileSync(mediaPath, outputPath);
+        return {
+            fileName,
+            path: outputPath,
+            url: this.clawtipPublicUrl(fileName)
+        };
+    }
+    async startClawtipActivationQr() {
+        const bootstrapUrl = process.env.TOKENBUDDY_BOOTSTRAP_URL || "https://tb-wallet-bootstrap.fly.dev";
+        const fetchBootstrap = this.config.clawtipBootstrapFetcher || fetchClawtipBootstrap;
+        const bootstrap = await fetchBootstrap(bootstrapUrl);
+        const payment = normalizeClawtipActivationPayment(bootstrap);
+        const startBootstrap = this.config.clawtipWalletBootstrapStarter || startClawtipWalletBootstrap;
+        const activation = await startBootstrap(payment, { home: this.config.clawtipHomeDir });
+        if (!activation.parsedOutput.mediaPath) {
+            throw new Error("ClawTip activation did not return a QR image.");
+        }
+        const staticQr = this.copyClawtipQrToStatic(activation.parsedOutput.mediaPath, payment.orderNo);
+        const walletConfig = inspectOpenClawWalletConfig(this.config.clawtipHomeDir);
+        const existingPayment = this.tokenStore.getPayment("clawtip");
+        this.tokenStore.savePayment({
+            method: "clawtip",
+            enabled: walletConfig.exists,
+            isDefault: existingPayment?.isDefault ?? true,
+            config: {
+                ...(existingPayment?.config ?? {}),
+                bootstrapUrl,
+                orderNo: payment.orderNo,
+                amountFen: payment.amountFen,
+                indicator: payment.indicator,
+                slug: payment.slug,
+                skillId: payment.skillId,
+                description: payment.description,
+                resourceUrl: payment.resourceUrl,
+                activationOrderFile: activation.orderFile,
+                walletConfigPath: walletConfig.expectedPath,
+                walletConfigPresent: walletConfig.exists,
+                activationQrImagePath: activation.parsedOutput.mediaPath,
+                activationQrImageUrl: staticQr.url,
+                authUrl: activation.parsedOutput.authUrl,
+                clawtipId: activation.parsedOutput.clawtipId,
+                payCredentialWritten: Boolean(activation.payCredential),
+                activationCompletedBy: activation.payCredential
+                    ? (walletConfig.exists ? "payCredential+wallet-config" : "payCredential")
+                    : walletConfig.exists ? "wallet-config" : "pending-wallet-scan"
+            }
+        });
+        this.scheduleClawtipActivationWait(activation.parsedOutput.clawtipId);
+        return {
+            ok: true,
+            kind: "activate",
+            method: "clawtip",
+            orderNo: payment.orderNo,
+            amountFen: payment.amountFen,
+            qrImageUrl: staticQr.url,
+            sourceImagePath: activation.parsedOutput.mediaPath,
+            staticImagePath: staticQr.path,
+            authUrl: activation.parsedOutput.authUrl,
+            clawtipId: activation.parsedOutput.clawtipId,
+            orderFile: activation.orderFile,
+            walletConfigPath: walletConfig.expectedPath,
+            walletConfigPresent: walletConfig.exists,
+            requiresWalletAuth: activation.parsedOutput.requiresWalletAuth,
+            payCredentialWritten: Boolean(activation.payCredential)
+        };
+    }
+    scheduleClawtipActivationWait(clawtipId) {
+        if (this.clawtipActivationWait) {
+            return;
+        }
+        const cancelToken = { cancelled: false };
+        this.clawtipActivationWaitCancelToken = cancelToken;
+        const waitForActivation = this.config.clawtipActivationWaiter || waitForClawtipActivationConfirmation;
+        this.clawtipActivationWait = waitForActivation({
+            clawtipId,
+            inspectWalletConfig: () => inspectOpenClawWalletConfig(this.config.clawtipHomeDir),
+            isCancelled: () => cancelToken.cancelled,
+            cancel: () => undefined
+        })
+            .then((walletRegistered) => {
+            if (cancelToken.cancelled) {
+                return;
+            }
+            if (!walletRegistered) {
+                logger.info("control.payment.clawtip.activation_wait.pending", "ClawTip activation wait ended before wallet registration");
+                return;
+            }
+            const walletConfig = inspectOpenClawWalletConfig(this.config.clawtipHomeDir);
+            const payment = this.tokenStore.getPayment("clawtip");
+            if (!payment || payment.method !== "clawtip") {
+                return;
+            }
+            this.tokenStore.savePayment({
+                ...payment,
+                enabled: walletConfig.exists,
+                config: {
+                    ...(payment.config ?? {}),
+                    walletConfigPath: walletConfig.expectedPath,
+                    walletConfigPresent: walletConfig.exists,
+                    activationCompletedBy: walletConfig.exists
+                        ? "wallet-config"
+                        : readConfigString(payment.config, "activationCompletedBy") ?? "pending-wallet-scan"
+                }
+            });
+            logger.info("control.payment.clawtip.activation_wait.completed", "ClawTip activation wait completed", {
+                walletRegistered,
+                walletConfigPresent: walletConfig.exists
+            });
+        })
+            .catch((error) => {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.warn("control.payment.clawtip.activation_wait.failed", "ClawTip activation wait failed", { errorMessage });
+        })
+            .finally(() => {
+            if (this.clawtipActivationWaitCancelToken === cancelToken) {
+                this.clawtipActivationWaitCancelToken = undefined;
+                this.clawtipActivationWait = undefined;
+            }
+        });
+    }
+    clawtipRechargeQr() {
+        const payment = this.tokenStore.getPayment("clawtip");
+        const resourceUrl = readConfigString(payment?.config, "resourceUrl");
+        const orderNo = readConfigString(payment?.config, "orderNo") || "clawtip-recharge";
+        const mediaPath = path.join(this.clawtipStaticDir(), CLAWTIP_RECHARGE_QR_FILE);
+        if (!fs.existsSync(mediaPath)) {
+            throw new Error(`ClawTip fixed recharge QR image is missing: ${mediaPath}`);
+        }
+        const walletConfig = inspectOpenClawWalletConfig(this.config.clawtipHomeDir);
+        return {
+            ok: true,
+            kind: "recharge",
+            method: "clawtip",
+            orderNo,
+            qrImageUrl: this.clawtipPublicUrl(CLAWTIP_RECHARGE_QR_FILE),
+            sourceImagePath: mediaPath,
+            staticImagePath: mediaPath,
+            resourceUrl,
+            walletConfigPath: walletConfig.expectedPath,
+            walletConfigPresent: walletConfig.exists,
+            requiresWalletAuth: false,
+            payCredentialWritten: readConfigBoolean(payment?.config, "payCredentialWritten")
+        };
+    }
     // v1.2 §18.9: stale-cache fallback. The buyer remembers the last
     // successfully fetched registry document and reuses it when the
     // bootstrap returns 413 (`X-TokenBuddy-Registry-Too-Large: 1`). This
@@ -259,6 +584,7 @@ export class TokenbuddyDaemon {
         }
     }
     runtimeSummary() {
+        this.refreshSellerRoutingConfig();
         return {
             status: "running",
             pid: process.pid,
@@ -363,11 +689,13 @@ export class TokenbuddyDaemon {
         // v1.2: registry is the source of truth for routing. We rebuild the
         // model-index once per request (cheap; index lookup is in-memory) so
         // the response always reflects the latest seller list. The previous
-        // "fetchSellerManifest per candidate" path is removed in favor of
+        // "fetchSellerManifest per request" path is removed in favor of
         // pulling `models` directly off the registry entries.
         const registry = await this.fetchRegistry();
-        const routing = this.sellerRouting;
+        const routing = resolveSellerRoutingForModel(this.refreshSellerRoutingConfig(), modelId);
         const registrySellers = reorderDefaultSellerFirst(registry.sellers, registry.defaultSeller);
+        this.sellerPool.ensureRegistrySellers(registrySellers);
+        this.scheduleLazyPrewarmIfNeeded(modelId, protocol, paymentMethod);
         const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
         const planned = planSellerRouteSet({
             modelId,
@@ -380,8 +708,12 @@ export class TokenbuddyDaemon {
                 sellerId: entry.sellerId,
                 healthScore: entry.healthScore,
                 avgLatencyMs: entry.avgLatencyMs,
-                circuit: entry.circuit
-            }))
+                ttftMs: entry.ttftMs,
+                avgInferenceMs: entry.avgInferenceMs,
+                circuit: entry.circuit,
+                capacityBlockedUntil: entry.capacityBlockedUntil
+            })),
+            now: Date.now()
         });
         if (planned.routes.length === 0) {
             throw new Error(`no compatible seller for ${endpoint} model ${modelId}`);
@@ -408,7 +740,109 @@ export class TokenbuddyDaemon {
             sellerCount: routes.length,
             sellers: routes.map((route) => route.seller.id)
         });
-        return routes;
+        return { routes, plan: planned, paymentMethod };
+    }
+    refreshSellerRoutingConfig() {
+        const storedRouting = this.tokenStore.getDaemonRuntimeConfig(ROUTING_CONFIG_KEY)
+            ?.config;
+        const nextRouting = mergeSellerRoutingConfig(storedRouting, this.config.sellerRouting);
+        if (!sameSellerRouting(this.sellerRouting, nextRouting)) {
+            const previous = this.sellerRouting;
+            this.sellerRouting = nextRouting;
+            this.selectionMode = selectionModeForRouting(nextRouting);
+            this.selectedSellerId = selectedSellerIdForRouting(nextRouting);
+            logger.info("routing.config.reloaded", "seller routing config reloaded", {
+                previousMode: previous.mode,
+                previousScorer: previous.scorer,
+                sellerRoutingMode: nextRouting.mode,
+                sellerRoutingScorer: nextRouting.scorer,
+                selectedSellerId: this.selectedSellerId
+            });
+            void this.runRoutingPrewarmSweep(nextRouting);
+        }
+        return this.sellerRouting;
+    }
+    async runRoutingPrewarmSweep(routing) {
+        const focusSet = this.resolveFocusSet();
+        const routingPrewarmKey = `${routingKey(routing)}\u0001${focusSet.join("\u0001")}`;
+        if (focusSet.length === 0) {
+            logger.info("prewarm.routing.skipped", "no focus set configured after routing reload; relying on lazy prewarms", {
+                sellerRoutingMode: routing.mode,
+                sellerRoutingScorer: routing.scorer
+            });
+            return;
+        }
+        if (this.lastRoutingPrewarmKey === routingPrewarmKey) {
+            return;
+        }
+        this.lastRoutingPrewarmKey = routingPrewarmKey;
+        logger.info("prewarm.routing.scheduled", "routing reload prewarm sweep scheduled", {
+            sellerRoutingMode: routing.mode,
+            sellerRoutingScorer: routing.scorer,
+            focusSetSize: focusSet.length,
+            focusSet: focusSet.slice(0, 20)
+        });
+        try {
+            await this.fetchRegistry();
+            const paymentMethod = this.defaultPaymentMethod();
+            for (const modelId of focusSet) {
+                this.schedulePrewarmForModel({
+                    modelId,
+                    reason: "explicit",
+                    protocol: this.resolvePrewarmProtocol(modelId, paymentMethod),
+                    paymentMethod
+                });
+            }
+        }
+        catch (err) {
+            logger.warn("prewarm.routing.failed", "routing reload prewarm sweep failed", {
+                sellerRoutingMode: routing.mode,
+                sellerRoutingScorer: routing.scorer,
+                errorMessage: err instanceof Error ? err.message : String(err)
+            });
+        }
+    }
+    scheduleLazyPrewarmIfNeeded(modelId, protocol, paymentMethod) {
+        const freshness = this.prewarmCache.freshness(modelId, protocol, paymentMethod);
+        if (freshness.present && !freshness.expired) {
+            return;
+        }
+        const key = prewarmKey(modelId, protocol, paymentMethod);
+        if (this.lazyPrewarmKeys.has(key)) {
+            return;
+        }
+        this.lazyPrewarmKeys.add(key);
+        logger.info("prewarm.lazy.scheduled", "lazy prewarm scheduled for requested model", {
+            modelId,
+            protocol,
+            paymentMethod,
+            freshnessState: freshness.state
+        });
+        this.schedulePrewarmForModel({
+            modelId,
+            reason: "lazy",
+            protocol,
+            paymentMethod
+        }).finally(() => {
+            this.lazyPrewarmKeys.delete(key);
+        });
+    }
+    schedulePrewarmForModel(input) {
+        if (!input.protocol || !input.paymentMethod) {
+            logger.warn("prewarm.schedule.skipped", "prewarm schedule skipped because protocol or payment method is missing", {
+                modelId: input.modelId,
+                reason: input.reason,
+                protocol: input.protocol,
+                paymentMethod: input.paymentMethod
+            });
+            return Promise.resolve();
+        }
+        return this.prewarmScheduler.schedulePrewarm({
+            modelId: input.modelId,
+            reason: input.reason,
+            protocol: input.protocol,
+            paymentMethod: input.paymentMethod
+        });
     }
     failoverErrorMessage(error) {
         return error instanceof Error ? error.message : String(error);
@@ -422,13 +856,16 @@ export class TokenbuddyDaemon {
      * caller side because it short-circuits the failure path with a
      * re-purchase.
      */
-    classifyFailureStatus(status) {
+    classifyFailureStatus(status, bodyText) {
         if (status === 401 || status === 403) {
             return "auth_invalid";
         }
         if (status === 402) {
             return "insufficient_funds";
         }
+        if (status === 429 && isBusyCapacityErrorBody(bodyText)) {
+            return "busy_capacity";
+        }
         if (status === 400 || status === 404 || status === 422) {
             return "hard_4xx";
         }
@@ -561,7 +998,7 @@ export class TokenbuddyDaemon {
         }
         return parseSellerSettlementObject(raw);
     }
-    recordReconciledInference(route, endpoint, requestId, usage, settlement, prompt, response) {
+    recordReconciledInference(route, endpoint, requestId, usage, settlement, prompt, response, extras) {
         if (settlement) {
             this.tokenStore.reconcileTokenBalance({
                 sellerKey: route.seller.id,
@@ -589,7 +1026,14 @@ export class TokenbuddyDaemon {
             balanceSnapshotMicros: settlement?.remainingCreditMicros,
             balanceSource: settlement ? "seller_authoritative" : "estimated",
             prompt,
-            response
+            response,
+            ttftMs: extras?.ttftMs,
+            fallbackCount: extras?.fallbackCount,
+            routeReason: extras?.routeReason,
+            falloverChain: extras?.falloverChain,
+            upstreamStatus: extras?.upstreamStatus,
+            durationMs: extras?.durationMs,
+            paymentMethod: extras?.paymentMethod
         });
         logger.info("inference.ledger.recorded", "safe inference ledger recorded", {
             requestId: settlement?.requestId || requestId,
@@ -604,7 +1048,14 @@ export class TokenbuddyDaemon {
             promptTokens: usage.promptTokens,
             completionTokens: usage.completionTokens,
             balanceSnapshotMicros: settlement?.remainingCreditMicros,
-            balanceSource: settlement ? "seller_authoritative" : "estimated"
+            balanceSource: settlement ? "seller_authoritative" : "estimated",
+            ttftMs: extras?.ttftMs,
+            fallbackCount: extras?.fallbackCount,
+            routeReason: extras?.routeReason,
+            falloverChain: extras?.falloverChain,
+            upstreamStatus: extras?.upstreamStatus,
+            durationMs: extras?.durationMs,
+            paymentMethod: extras?.paymentMethod
         });
     }
     async refreshSellerBalance(route, token, balanceSource) {
@@ -1074,6 +1525,11 @@ export class TokenbuddyDaemon {
     }
     async forwardProxyRequest(endpoint, req, res) {
         const startedAt = Date.now();
+        let firstByteAt = null;
+        const markFirstByte = () => {
+            if (firstByteAt === null)
+                firstByteAt = Date.now();
+        };
         const body = req.body || {};
         const { requestedModelId, resolvedModelId } = this.resolveRouteModelId(endpoint, body);
         const modelId = resolvedModelId;
@@ -1084,13 +1540,20 @@ export class TokenbuddyDaemon {
             return;
         }
         try {
-            const routes = await this.selectSellerRoutes(endpoint, modelId);
+            const { routes, plan, paymentMethod } = await this.selectSellerRoutes(endpoint, modelId);
+            const upstreamStatusFromHeaders = (h) => {
+                const raw = h.get("x-tokenbuddy-upstream-status") || h.get("x-upstream-status");
+                if (!raw)
+                    return undefined;
+                return raw === "healthy" || raw === "degraded" || raw === "unhealthy" || raw === "unknown" ? raw : "unknown";
+            };
             let lastError;
             for (let routeIndex = 0; routeIndex < routes.length; routeIndex += 1) {
                 const route = routes[routeIndex];
                 const sellerKey = route.seller.id;
                 logger.info("route.selected", "seller route selected", {
                     sellerKey,
+                    sellerId: sellerKey,
                     model: modelId,
                     endpoint,
                     protocol: route.protocol,
@@ -1247,7 +1710,7 @@ export class TokenbuddyDaemon {
                                     status: upstreamResponse.status,
                                     durationMs: Date.now() - startedAt
                                 });
-                                const kind = this.classifyFailureStatus(upstreamResponse.status);
+                                const kind = this.classifyFailureStatus(upstreamResponse.status, errorBody);
                                 const decision = this.routeFailover.decide({
                                     sellerId: sellerKey,
                                     status: upstreamResponse.status,
@@ -1317,6 +1780,7 @@ export class TokenbuddyDaemon {
                                 // 缺 event: 行）由卖方修，buyer 不兜底。
                                 const sellerChunk = settlementExtractor.push(chunk);
                                 if (sellerChunk.length > 0) {
+                                    markFirstByte();
                                     res.write(sellerChunk);
                                 }
                             }
@@ -1328,21 +1792,40 @@ export class TokenbuddyDaemon {
                             if (decoderTail.length > 0) {
                                 const sellerTail = settlementExtractor.push(decoderTail);
                                 if (sellerTail.length > 0) {
+                                    markFirstByte();
                                     res.write(sellerTail);
                                 }
                             }
                             const settlementTrailing = settlementExtractor.finish();
                             if (settlementTrailing.downstream.length > 0) {
+                                markFirstByte();
                                 res.write(settlementTrailing.downstream);
                             }
                             res.end();
-                            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));
+                            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, {
+                                ttftMs: firstByteAt ? firstByteAt - startedAt : undefined,
+                                fallbackCount: routeIndex,
+                                routeReason: plan.reason,
+                                falloverChain: routes.slice(0, routeIndex + 1).map((r) => r.seller.id),
+                                upstreamStatus: upstreamStatusFromHeaders(upstreamResponse.headers),
+                                durationMs: Date.now() - startedAt,
+                                paymentMethod
+                            });
                             return;
                         }
                         const responseBody = await upstreamResponse.text();
+                        markFirstByte();
                         res.send(responseBody);
                         const usage = this.readUsage(responseBody);
-                        this.recordReconciledInference(route, endpoint, requestId, usage, this.parseSellerSettlementSummary(upstreamResponse.headers), this.inferPromptForHash(body), responseBody);
+                        this.recordReconciledInference(route, endpoint, requestId, usage, this.parseSellerSettlementSummary(upstreamResponse.headers), this.inferPromptForHash(body), responseBody, {
+                            ttftMs: firstByteAt ? firstByteAt - startedAt : undefined,
+                            fallbackCount: routeIndex,
+                            routeReason: plan.reason,
+                            falloverChain: routes.slice(0, routeIndex + 1).map((r) => r.seller.id),
+                            upstreamStatus: upstreamStatusFromHeaders(upstreamResponse.headers),
+                            durationMs: Date.now() - startedAt,
+                            paymentMethod
+                        });
                         return;
                     }
                     catch (routeError) {
@@ -1437,9 +1920,41 @@ export class TokenbuddyDaemon {
         controlApp.get("/payments", (req, res) => {
             logger.info("control.payments.requested", "control payments requested", {});
             res.status(200).json({
-                payments: this.tokenStore.listPayments()
+                payments: this.tokenStore.listPayments().map((payment) => withLiveClawtipWalletState(payment, this.config.clawtipHomeDir))
             });
         });
+        controlApp.post("/payments/clawtip/activate", async (req, res) => {
+            try {
+                const qr = await this.startClawtipActivationQr();
+                logger.info("control.payment.clawtip.activate_qr.created", "ClawTip activation QR copied for tb-ui", {
+                    orderNo: qr.orderNo,
+                    qrImageUrl: qr.qrImageUrl,
+                    walletConfigPresent: qr.walletConfigPresent
+                });
+                res.status(200).json(qr);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("control.payment.clawtip.activate_qr.failed", "ClawTip activation QR failed", { errorMessage });
+                res.status(500).json({ error: { code: "clawtip_activate_qr_failed", message: errorMessage } });
+            }
+        });
+        controlApp.post("/payments/clawtip/recharge", (req, res) => {
+            try {
+                const qr = this.clawtipRechargeQr();
+                logger.info("control.payment.clawtip.recharge_qr.created", "ClawTip fixed recharge QR served for tb-ui", {
+                    orderNo: qr.orderNo,
+                    qrImageUrl: qr.qrImageUrl,
+                    walletConfigPresent: qr.walletConfigPresent
+                });
+                res.status(200).json(qr);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("control.payment.clawtip.recharge_qr.failed", "ClawTip recharge QR failed", { errorMessage });
+                res.status(500).json({ error: { code: "clawtip_recharge_qr_failed", message: errorMessage } });
+            }
+        });
         controlApp.get("/ledger/purchases", (req, res) => {
             logger.info("control.ledger.requested", "control purchase ledger requested", {
                 ledger: "purchases"
@@ -1578,6 +2093,41 @@ export class TokenbuddyDaemon {
                 });
             }
         });
+        controlApp.get("/providers/status", (_req, res) => {
+            try {
+                const providerStatuses = detectProviders({ home: this.config.providerHomeDir }).map(clientToolStatusFromProvider);
+                const clients = [
+                    ...providerStatuses,
+                    buildCustomClientToolStatus(this.activeProxyPort()),
+                ];
+                const configuredCount = clients.filter((client) => client.configured).length;
+                const detectedCount = clients.filter((client) => client.detected && client.status !== "manual").length;
+                logger.info("provider.status.requested", "provider status requested", {
+                    clientCount: clients.length,
+                    configuredCount,
+                    detectedCount
+                });
+                res.status(200).json({
+                    clients,
+                    summary: {
+                        configuredCount,
+                        detectedCount,
+                        totalCount: clients.length,
+                        installCommand: "tb init"
+                    }
+                });
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("provider.status.failed", "provider status failed", { errorMessage });
+                res.status(400).json({
+                    error: {
+                        code: "provider_status_failed",
+                        message: errorMessage
+                    }
+                });
+            }
+        });
         controlApp.post("/providers/install/preview", (req, res) => {
             try {
                 const changes = previewProviderInstall({
@@ -1655,6 +2205,169 @@ export class TokenbuddyDaemon {
                 });
             }
         });
+        // ─────────────────────────────────────────────────────────────────
+        // tb-ui v1: 控制平面写端点（PR-0）
+        // 所有端点都热生效，不需重启 daemon。改完 store 即下次推理生效。
+        // ─────────────────────────────────────────────────────────────────
+        // 1) GET /routing/strategy — 读当前路由策略 + 来源
+        controlApp.get("/routing/strategy", (req, res) => {
+            try {
+                const stored = this.tokenStore.getDaemonRuntimeConfig(ROUTING_CONFIG_KEY)?.config;
+                const current = this.refreshSellerRoutingConfig();
+                const source = stored !== undefined ? "store" : this.config.sellerRouting ? "config" : "default";
+                logger.info("routing.strategy.read", "routing strategy read", {
+                    source,
+                    mode: current.mode,
+                    scorer: current.scorer
+                });
+                res.status(200).json({ strategy: current, source });
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("routing.strategy.read_failed", "routing strategy read failed", { errorMessage });
+                res.status(500).json({ error: { code: "routing_strategy_read_failed", message: errorMessage } });
+            }
+        });
+        // 2) GET /routing/preview — 算「假如改完会怎样」，不改 state
+        //   query: modelId? protocol? paymentMethod? mode? scorer? sellerId? sellerIds?(逗号分隔)
+        controlApp.get("/routing/preview", (req, res) => {
+            try {
+                const override = buildRoutingConfigFromQuery(req.query);
+                const result = this.buildRoutingPreview({
+                    modelId: typeof req.query.modelId === "string" ? req.query.modelId : undefined,
+                    protocol: typeof req.query.protocol === "string" ? req.query.protocol : undefined,
+                    paymentMethod: typeof req.query.paymentMethod === "string" ? req.query.paymentMethod : undefined,
+                    routing: override ?? undefined
+                });
+                if ("error" in result.plan) {
+                    res.status(409).json({
+                        error: { code: result.plan.error, message: `cannot preview routing: ${result.plan.error}` },
+                        modelId: result.modelId,
+                        protocol: result.protocol,
+                        paymentMethod: result.paymentMethod
+                    });
+                    return;
+                }
+                res.status(200).json({
+                    modelId: result.modelId,
+                    protocol: result.protocol,
+                    paymentMethod: result.paymentMethod,
+                    plan: result.plan
+                });
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("routing.preview.failed", "routing preview failed", { errorMessage });
+                res.status(400).json({ error: { code: "routing_preview_failed", message: errorMessage } });
+            }
+        });
+        // 3) PUT /routing/strategy — 写策略 + 热更新 + 返回 preview
+        controlApp.put("/routing/strategy", (req, res) => {
+            try {
+                const body = (req.body ?? {});
+                const normalized = normalizeSellerRoutingConfig(body);
+                // 必填字段再次校验（normalize 会回退 default，但 PUT 必须显式）
+                assertSellerRoutingConfig(normalized);
+                this.tokenStore.saveDaemonRuntimeConfig(ROUTING_CONFIG_KEY, normalized);
+                const current = this.refreshSellerRoutingConfig();
+                logger.info("routing.strategy.applied", "routing strategy applied", {
+                    mode: current.mode,
+                    scorer: current.scorer,
+                    sellerId: current.sellerId,
+                    sellerIds: current.sellerIds
+                });
+                const preview = this.buildRoutingPreview({ routing: current });
+                const previewPayload = "error" in preview.plan
+                    ? { error: preview.plan.error }
+                    : {
+                        modelId: preview.modelId,
+                        protocol: preview.protocol,
+                        paymentMethod: preview.paymentMethod,
+                        ...preview.plan
+                    };
+                res.status(200).json({ applied: true, strategy: current, preview: previewPayload });
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("routing.strategy.apply_failed", "routing strategy apply failed", { errorMessage });
+                res.status(400).json({ error: { code: "routing_strategy_apply_failed", message: errorMessage } });
+            }
+        });
+        // 4) PUT /prewarm/focus-set — 设置 explicit focus set（覆盖 config.warmupModels / env）
+        //   body: { models: ["claude-3-5-sonnet", "gpt-4o"], clear?: false }
+        //   clear=true 时 models 数组可省略；表示回退 env / historical
+        controlApp.put("/prewarm/focus-set", (req, res) => {
+            try {
+                const body = (req.body ?? {});
+                const clear = body.clear === true;
+                if (clear) {
+                    const result = this.applyFocusSet(null);
+                    res.status(200).json({ ok: true, ...result });
+                    return;
+                }
+                if (!Array.isArray(body.models)) {
+                    res.status(400).json({
+                        error: { code: "invalid_focus_set", message: "focus-set body must have a string[] `models` field, or `clear: true`" }
+                    });
+                    return;
+                }
+                const models = body.models
+                    .filter((m) => typeof m === "string")
+                    .map((m) => m.trim())
+                    .filter(Boolean);
+                const result = this.applyFocusSet(models);
+                res.status(200).json({ ok: true, ...result });
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("focus_set.apply_failed", "focus set apply failed", { errorMessage });
+                res.status(400).json({ error: { code: "focus_set_apply_failed", message: errorMessage } });
+            }
+        });
+        // 5) POST /daemon/restart — 优雅重启 tb-proxyd（调子进程 `tb daemon restart`）
+        //   现有 CLI 子命令（cli.ts:1129）。detached 模式让子进程独立于 daemon 生命周期。
+        controlApp.post("/daemon/restart", (req, res) => {
+            try {
+                const child = spawn("tb", ["daemon", "restart"], {
+                    detached: true,
+                    stdio: "ignore"
+                });
+                child.unref();
+                logger.info("daemon.restart.scheduled", "daemon restart scheduled via tb CLI");
+                res.status(202).json({ ok: true, message: "restart scheduled" });
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("daemon.restart.failed", "daemon restart failed", { errorMessage });
+                res.status(500).json({ error: { code: "daemon_restart_failed", message: errorMessage } });
+            }
+        });
+        this.ensureClawtipStaticAssets();
+        controlApp.use(CLAWTIP_STATIC_ROUTE, express.static(this.clawtipStaticDir(), { index: false, fallthrough: false }));
+        // ────────────────────────────────────────────────────────────
+        // tb-ui v1: 静态托管 SPA(dist 由 `npm run build --workspace tb-ui` 生成)
+        // 必须在所有 API 路由**之后**才挂载,这样:
+        // - `/health` `/ledger/purchases` 等 API 路径仍由上面 17+ 个端点处理
+        // - 真实静态文件(`/index.html` `/assets/index-abc.js` 等)由 express.static 服务
+        // - 未匹配路径(`/overview` `/routing` 等 React Router 路径)走 SPA fallback 回 index.html
+        // ────────────────────────────────────────────────────────────
+        const uiDir = resolveUiDir();
+        if (uiDir && fs.existsSync(uiDir) && fs.existsSync(path.join(uiDir, "index.html"))) {
+            controlApp.use(express.static(uiDir, { index: "index.html", fallthrough: true }));
+            // SPA fallback: React Router 用 BrowserRouter(history mode),客户端路径如
+            // /overview /routing /ledger 不对应任何文件,必须回 index.html 让 React Router 接管。
+            // Express 已经按注册顺序匹配了所有 17+ 个 API 路由,这里只接住"什么都没匹配"的 GET。
+            controlApp.get(/^(?!\/(?:health|status|payments|sellers|models|ledger|routing|prewarm|v1\.2|daemon|providers|static)\/).*/, (_req, res) => {
+                res.sendFile(path.join(uiDir, "index.html"));
+            });
+            logger.info("ui.static.attached", "tb-ui dist attached to control plane SPA fallback", { uiDir });
+        }
+        else {
+            logger.warn("ui.static.missing", "tb-ui dist not found; only control plane API will be served", {
+                uiDir,
+                hint: "run `npm run build --workspace tb-ui` then restart"
+            });
+        }
         this.controlServer = controlApp.listen(this.config.controlPort);
         // 2. Proxy Plane Server (17821)
         const proxyApp = express();
@@ -1717,9 +2430,13 @@ export class TokenbuddyDaemon {
     /**
      * v1.2 §18.4: build the focus set from the explicit config, the env
      * override, and the historical usage in the buyer store. The order of
-     * precedence: explicit config > env > historical > empty.
+     * precedence: explicit `currentFocusSet` (set via `PUT /prewarm/focus-set`)
+     * > explicit config > env > historical > empty.
      */
     resolveFocusSet() {
+        if (this.currentFocusSet !== null) {
+            return this.currentFocusSet;
+        }
         const explicit = this.config.warmupModels ?? [];
         if (explicit.length > 0) {
             return explicit;
@@ -1731,6 +2448,86 @@ export class TokenbuddyDaemon {
         }
         return this.tokenStore.recentModels(7, 5);
     }
+    /**
+     * tb-ui v1 `PUT /prewarm/focus-set` 调用的统一入口。`models === null`
+     * 表示「清除 explicit focus set，回退 env/historical」。
+     * 写 store + 触发 `runRoutingPrewarmSweep`，**热生效**（不需重启 daemon）。
+     */
+    applyFocusSet(models) {
+        if (models === null) {
+            this.tokenStore.removeDaemonRuntimeConfig(FOCUS_SET_CONFIG_KEY);
+            this.currentFocusSet = null;
+        }
+        else {
+            const deduped = Array.from(new Set(models.map((m) => m.trim()).filter(Boolean)));
+            this.tokenStore.saveDaemonRuntimeConfig(FOCUS_SET_CONFIG_KEY, { models: deduped });
+            this.currentFocusSet = deduped;
+        }
+        // 触发路由重读 + 预热 sweep（如果当前 routing 已是焦点集合的依赖）。
+        this.refreshSellerRoutingConfig();
+        const focusSet = this.resolveFocusSet();
+        const source = this.currentFocusSet !== null
+            ? "explicit"
+            : (this.config.warmupModels?.length ?? 0) > 0
+                ? "explicit"
+                : (process.env.TB_BUYER_WARMUP_MODELS?.trim() ?? "").length > 0
+                    ? "env"
+                    : focusSet.length > 0
+                        ? "historical"
+                        : "empty";
+        logger.info("focus_set.applied", "explicit focus set applied", {
+            source,
+            focusSetSize: focusSet.length,
+            focusSet: focusSet.slice(0, 20)
+        });
+        return { focusSet, source };
+    }
+    /**
+     * tb-ui v1 `GET /routing/preview` 和 `PUT /routing/strategy` 复用的 preview 计算。
+     * 接受任意 routing 覆盖（来自 request body）算「假如改成这个，路由会是啥」。
+     * 不修改任何内部 state，**纯函数式**。
+     */
+    buildRoutingPreview(input) {
+        const registry = this.lastRegistrySnapshot;
+        const focusFirst = this.resolveFocusSet()[0];
+        const registryFirst = registry?.sellers[0]?.models?.[0];
+        const modelId = input.modelId?.trim() || focusFirst || registryFirst || "";
+        const protocol = input.protocol?.trim() || "chat_completions";
+        const paymentMethod = input.paymentMethod?.trim() || this.defaultPaymentMethod() || "clawtip";
+        if (!modelId) {
+            return { modelId, protocol, paymentMethod, plan: { error: "no_focus_model_available" } };
+        }
+        if (!registry) {
+            return { modelId, protocol, paymentMethod, plan: { error: "registry_not_loaded" } };
+        }
+        const current = this.refreshSellerRoutingConfig();
+        const routing = input.routing
+            ? mergeSellerRoutingConfig(current, input.routing)
+            : current;
+        const resolvedRouting = resolveSellerRoutingForModel(routing, modelId);
+        const registrySellers = reorderDefaultSellerFirst(registry.sellers, registry.defaultSeller);
+        this.sellerPool.ensureRegistrySellers(registrySellers);
+        const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
+        const plan = planSellerRouteSet({
+            modelId,
+            protocol,
+            paymentMethod,
+            registrySellers,
+            routing: resolvedRouting,
+            prewarmCandidates: this.prewarmCache.get(modelId, protocol, paymentMethod)?.candidates,
+            sellerMetrics: Array.from(poolById.values()).map((entry) => ({
+                sellerId: entry.sellerId,
+                healthScore: entry.healthScore,
+                avgLatencyMs: entry.avgLatencyMs,
+                ttftMs: entry.ttftMs,
+                avgInferenceMs: entry.avgInferenceMs,
+                circuit: entry.circuit,
+                capacityBlockedUntil: entry.capacityBlockedUntil
+            })),
+            now: Date.now()
+        });
+        return { modelId, protocol, paymentMethod, plan };
+    }
     async runStartupPrewarmSweep() {
         const focusSet = this.resolveFocusSet();
         if (focusSet.length === 0) {
@@ -1745,7 +2542,7 @@ export class TokenbuddyDaemon {
             await this.fetchRegistry();
             await this.prewarmScheduler.runStartupPrewarm(focusSet.map((modelId) => ({
                 modelId,
-                protocol: this.resolvePrewarmProtocol(modelId)
+                protocol: this.resolvePrewarmProtocol(modelId, this.defaultPaymentMethod())
             })));
         }
         catch (err) {
@@ -1754,15 +2551,18 @@ export class TokenbuddyDaemon {
             });
         }
     }
-    resolvePrewarmProtocol(modelId) {
+    resolvePrewarmProtocol(modelId, paymentMethod = "clawtip") {
         for (const protocol of ["chat_completions", "messages", "responses"]) {
-            if (this.modelIndex.sellersFor(modelId, { protocol, paymentMethod: "clawtip" }).length > 0) {
+            if (this.modelIndex.sellersFor(modelId, { protocol, paymentMethod }).length > 0) {
                 return protocol;
             }
         }
         return undefined;
     }
     stop() {
+        if (this.clawtipActivationWaitCancelToken) {
+            this.clawtipActivationWaitCancelToken.cancelled = true;
+        }
         if (this.controlServer)
             this.controlServer.close();
         if (this.proxyServer)
@@ -1770,5 +2570,166 @@ export class TokenbuddyDaemon {
         void this.prewarmScheduler.stop();
         this.tokenStore.close();
     }
+    /**
+     * @internal — test-only seam to inject a registry snapshot without
+     * hitting the network. Used by `tests/control-plane-ui-endpoints.test.ts`
+     * to drive `buildRoutingPreview` deterministically. Production code
+     * must NOT call this; the real `fetchRegistry()` populates the snapshot.
+     */
+    setLastRegistrySnapshotForTest(snapshot) {
+        this.lastRegistrySnapshot = snapshot;
+    }
+}
+function selectionModeForRouting(routing) {
+    return routing.mode === "fullAuto" ? "auto" : "manual";
+}
+function withLiveClawtipWalletState(payment, home) {
+    if (payment.method !== "clawtip") {
+        return payment;
+    }
+    const walletConfig = inspectOpenClawWalletConfig(home);
+    return {
+        ...payment,
+        enabled: payment.enabled && walletConfig.exists,
+        config: {
+            ...(payment.config ?? {}),
+            walletConfigPath: walletConfig.expectedPath,
+            walletConfigPresent: walletConfig.exists,
+            nearbyWalletConfigPaths: walletConfig.alternatePaths
+        }
+    };
+}
+function normalizeClawtipActivationPayment(bootstrap) {
+    if (!bootstrap.payment?.orderNo || !bootstrap.payment.indicator || !bootstrap.payment.resourceUrl) {
+        throw new Error("ClawTip bootstrap response missing orderNo, indicator, or resourceUrl.");
+    }
+    return {
+        orderNo: bootstrap.payment.orderNo,
+        amountFen: bootstrap.payment.amountFen ?? bootstrap.activationFeeFen ?? 1,
+        payTo: bootstrap.payment.payTo,
+        encryptedData: bootstrap.payment.encryptedData,
+        indicator: bootstrap.payment.indicator,
+        slug: bootstrap.payment.slug,
+        skillId: bootstrap.payment.skillId,
+        description: bootstrap.payment.description,
+        resourceUrl: bootstrap.payment.resourceUrl,
+    };
+}
+function safeQrExtension(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    if (extension === ".jpg" || extension === ".jpeg" || extension === ".webp") {
+        return extension;
+    }
+    return ".png";
+}
+function safeStaticFileSegment(value) {
+    return value.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "clawtip";
+}
+function readConfigString(config, key) {
+    const value = config?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function readConfigBoolean(config, key) {
+    return config?.[key] === true;
+}
+function selectedSellerIdForRouting(routing) {
+    return routing.mode === "fixed" ? routing.sellerId : undefined;
+}
+function routingKey(routing) {
+    const fixedByModel = Object.entries(routing.fixedByModel ?? {})
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([modelId, sellerId]) => `${modelId}:${sellerId}`);
+    return [
+        routing.mode,
+        routing.scorer,
+        routing.sellerId ?? "",
+        ...(routing.sellerIds ?? []),
+        ...fixedByModel
+    ].join("\u0001");
+}
+/**
+ * 从 query string 构造 `BuyerSellerRoutingConfig` override（用于 GET /routing/preview）。
+ * 接受 `mode` / `scorer` / `sellerId` / `sellerIds`（逗号分隔）。
+ * 任一字段缺失返回 `undefined`，调用方走「用当前 routing」分支。
+ * mode / scorer 非法抛 400，由端点 handler 捕获。
+ */
+function buildRoutingConfigFromQuery(query) {
+    const mode = typeof query.mode === "string" ? query.mode.trim() : "";
+    const scorer = typeof query.scorer === "string" ? query.scorer.trim() : "";
+    const sellerId = typeof query.sellerId === "string" ? query.sellerId.trim() : "";
+    const sellerIdsRaw = typeof query.sellerIds === "string" ? query.sellerIds.trim() : "";
+    const fixedByModelRaw = typeof query.fixedByModel === "string" ? query.fixedByModel.trim() : "";
+    if (!mode && !scorer && !sellerId && !sellerIdsRaw && !fixedByModelRaw) {
+        return undefined;
+    }
+    const override = {};
+    if (mode) {
+        if (mode !== "fixed" && mode !== "fixedSet" && mode !== "fullAuto") {
+            throw new Error("mode must be fixed, fixedSet, or fullAuto");
+        }
+        override.mode = mode;
+    }
+    if (scorer) {
+        if (scorer !== "speed" && scorer !== "discount" && scorer !== "balanced") {
+            throw new Error("scorer must be speed, discount, or balanced");
+        }
+        override.scorer = scorer;
+    }
+    if (sellerId) {
+        override.sellerId = sellerId;
+    }
+    if (sellerIdsRaw) {
+        override.sellerIds = parseSellerIdList(sellerIdsRaw);
+    }
+    if (fixedByModelRaw) {
+        override.fixedByModel = parseFixedByModel(fixedByModelRaw);
+    }
+    return override;
+}
+function sameSellerRouting(a, b) {
+    return a.mode === b.mode
+        && a.scorer === b.scorer
+        && optionalStringEqual(a.sellerId, b.sellerId)
+        && stringArraysEqual(a.sellerIds ?? [], b.sellerIds ?? [])
+        && fixedByModelEqual(a.fixedByModel ?? {}, b.fixedByModel ?? {});
+}
+function optionalStringEqual(a, b) {
+    return (a ?? "") === (b ?? "");
+}
+function stringArraysEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    return a.every((entry, index) => entry === b[index]);
+}
+function resolveSellerRoutingForModel(routing, modelId) {
+    if (routing.mode !== "fixed") {
+        return routing;
+    }
+    const fixedSellerId = routing.fixedByModel?.[modelId]?.trim() || routing.sellerId;
+    return {
+        mode: "fixed",
+        scorer: routing.scorer,
+        sellerId: fixedSellerId,
+        fixedByModel: routing.fixedByModel
+    };
+}
+function parseFixedByModel(value) {
+    const entries = value
+        .split(",")
+        .map((entry) => entry.split(":"))
+        .filter((parts) => parts.length === 2)
+        .map(([modelId, sellerId]) => [modelId.trim(), sellerId.trim()])
+        .filter(([modelId, sellerId]) => modelId.length > 0 && sellerId.length > 0);
+    return Object.fromEntries(entries);
+}
+function fixedByModelEqual(a, b) {
+    const aEntries = Object.entries(a).sort(([left], [right]) => left.localeCompare(right));
+    const bEntries = Object.entries(b).sort(([left], [right]) => left.localeCompare(right));
+    return aEntries.length === bEntries.length
+        && aEntries.every(([modelId, sellerId], index) => {
+            const [otherModelId, otherSellerId] = bEntries[index] ?? [];
+            return modelId === otherModelId && sellerId === otherSellerId;
+        });
 }
 //# sourceMappingURL=daemon.js.map