@tokenbuddy/tokenbuddy 1.0.9 → 1.0.11

package/dist/src/daemon.js

@@ -5,7 +5,13 @@ import * as fs from "fs";
 import { createModuleLogger } from "@tokenbuddy/logging";
 import { BuyerStore } from "./buyer-store.js";
 import { applyProviderInstall, detectProviders, previewProviderInstall, rollbackProviderInstall, } from "./provider-install.js";
-import { discoverSellerBackedModels, fetchSellerManifest, fetchSellerRegistry, manifestModelIds, manifestPaymentMethods, manifestProtocols, normalizeSellerUrl, } from "./seller-catalog.js";
+import { discoverSellerBackedModels, fetchSellerRegistry, normalizeSellerUrl, RegistryTooLargeError, } from "./seller-catalog.js";
+import { ModelIndex } from "./model-index.js";
+import { PrewarmCache } 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";
 const logger = createModuleLogger("tb-proxyd");
 const PROXY_JSON_BODY_LIMIT = "10mb";
 function numericHeaderField(value) {
@@ -18,197 +24,6 @@ function numericHeaderField(value) {
     }
     return undefined;
 }
-class ResponsesStreamNormalizer {
-    pending = "";
-    state = new Map();
-    push(chunk) {
-        this.pending += chunk;
-        const blocks = this.pending.split("\n\n");
-        this.pending = blocks.pop() || "";
-        return blocks
-            .map((block) => this.normalizeBlock(block))
-            .filter((block) => block.length > 0)
-            .join("\n\n");
-    }
-    finish() {
-        if (!this.pending.trim()) {
-            return "";
-        }
-        const block = this.normalizeBlock(this.pending);
-        this.pending = "";
-        return block;
-    }
-    normalizeBlock(block) {
-        if (!block.trim()) {
-            return "";
-        }
-        // Each \n\n separates an event in SSE format
-        const subBlocks = block.split("\n\n");
-        const output = [];
-        for (const sub of subBlocks) {
-            if (!sub.trim() || sub.trim() === "data: [DONE]") {
-                if (sub.trim())
-                    output.push(sub);
-                continue;
-            }
-            const lines = sub.split("\n");
-            const eventLine = lines.find((l) => l.startsWith("event:"));
-            const dataLine = lines.find((l) => l.startsWith("data:"));
-            if (!dataLine) {
-                output.push(sub);
-                continue;
-            }
-            const rawData = dataLine.replace(/^data:\s?/, "");
-            if (rawData === "[DONE]") {
-                output.push(sub);
-                continue;
-            }
-            let payload;
-            try {
-                payload = JSON.parse(rawData);
-            }
-            catch {
-                output.push(sub);
-                continue;
-            }
-            const eventName = (eventLine?.replace(/^event:\s?/, "") || payload?.type);
-            if (!eventName || !eventName.startsWith("response.")) {
-                output.push(sub);
-                continue;
-            }
-            // When upstream already sends content_part.added, record it in state
-            if (eventName === "response.content_part.added" &&
-                payload?.item_id) {
-                const current = this.state.get(payload.item_id);
-                if (current)
-                    current.contentPartStarted = true;
-                output.push(sub);
-                continue;
-            }
-            // response.output_item.added: inject content_part.added only if upstream hasn't
-            if (eventName === "response.output_item.added" &&
-                payload?.item?.type === "message" &&
-                payload?.item?.id) {
-                const itemId = payload.item.id;
-                const current = this.getState(itemId);
-                const item = { ...payload.item };
-                item.content = [{ type: "output_text", text: "", annotations: [] }];
-                output.push(this.serializeEvent(eventName, {
-                    ...payload,
-                    output_index: payload.output_index ?? 0,
-                    item
-                }));
-                if (!current.contentPartStarted) {
-                    current.contentPartStarted = true;
-                    output.push(this.serializeEvent("response.content_part.added", {
-                        type: "response.content_part.added",
-                        item_id: itemId,
-                        output_index: payload.output_index ?? 0,
-                        content_index: 0,
-                        part: { type: "output_text", text: "", annotations: [] }
-                    }));
-                }
-                continue;
-            }
-            // response.output_text.delta: inject content_part.added if missing
-            if (eventName === "response.output_text.delta" && payload?.item_id) {
-                const itemId = payload.item_id;
-                const current = this.getState(itemId);
-                if (!current.contentPartStarted) {
-                    current.contentPartStarted = true;
-                    output.push(this.serializeEvent("response.content_part.added", {
-                        type: "response.content_part.added",
-                        item_id: itemId,
-                        output_index: payload.output_index ?? 0,
-                        content_index: payload.content_index ?? 0,
-                        part: { type: "output_text", text: "", annotations: [] }
-                    }));
-                }
-                const deltaText = typeof payload.delta === "string"
-                    ? payload.delta
-                    : typeof payload.delta?.text === "string"
-                        ? payload.delta.text
-                        : "";
-                current.text += deltaText;
-                output.push(this.serializeEvent(eventName, {
-                    ...payload,
-                    output_index: payload.output_index ?? 0,
-                    content_index: payload.content_index ?? 0
-                }));
-                continue;
-            }
-            // response.output_text.done: also emit content_part.done
-            if (eventName === "response.output_text.done" && payload?.item_id) {
-                const itemId = payload.item_id;
-                const current = this.getState(itemId);
-                output.push(this.serializeEvent(eventName, {
-                    ...payload,
-                    output_index: payload.output_index ?? 0,
-                    content_index: payload.content_index ?? 0
-                }));
-                output.push(this.serializeEvent("response.content_part.done", {
-                    type: "response.content_part.done",
-                    item_id: itemId,
-                    output_index: payload.output_index ?? 0,
-                    content_index: payload.content_index ?? 0,
-                    part: { type: "output_text", text: current.text, annotations: [] }
-                }));
-                continue;
-            }
-            // response.output_item.done: normalize content to output_text type
-            if (eventName === "response.output_item.done" &&
-                payload?.item?.type === "message" &&
-                payload?.item?.id) {
-                const itemId = payload.item.id;
-                const current = this.getState(itemId);
-                const item = {
-                    ...payload.item,
-                    content: [{ type: "output_text", text: current.text, annotations: [] }]
-                };
-                output.push(this.serializeEvent(eventName, {
-                    ...payload,
-                    output_index: payload.output_index ?? 0,
-                    item
-                }));
-                continue;
-            }
-            // response.completed: patch output if empty
-            if (eventName === "response.completed" && payload?.response) {
-                const response = { ...payload.response };
-                if (!Array.isArray(response.output) || response.output.length === 0) {
-                    const first = this.state.values().next()
-                        .value;
-                    if (first) {
-                        response.output = [{
-                                id: first.itemId,
-                                type: "message",
-                                status: "completed",
-                                role: "assistant",
-                                content: [{ type: "output_text", text: first.text, annotations: [] }]
-                            }];
-                        response.output_text = first.text;
-                    }
-                }
-                output.push(this.serializeEvent(eventName, { ...payload, response }));
-                continue;
-            }
-            // All other events: pass through unchanged
-            output.push(sub);
-        }
-        return output.join("\n\n");
-    }
-    getState(itemId) {
-        const current = this.state.get(itemId);
-        if (current)
-            return current;
-        const created = { itemId, text: "", contentPartStarted: false };
-        this.state.set(itemId, created);
-        return created;
-    }
-    serializeEvent(name, data) {
-        return `event: ${name}\ndata: ${JSON.stringify(data)}`;
-    }
-}
 class SellerSettlementStreamExtractor {
     pending = "";
     settlement;
@@ -289,6 +104,25 @@ export class TokenbuddyDaemon {
     selectionMode;
     selectedSellerId;
     activePurchases = new Map();
+    // v1.2 fallback pipeline: model-index, prewarm-cache, credit-tracker,
+    // pool, and route-failover together replace the v1
+    // "fetchRegistry + manifest per request" path.
+    modelIndex = new ModelIndex();
+    prewarmCache = new PrewarmCache();
+    creditTracker = new CreditTracker();
+    sellerPool = new SellerPool({
+        modelIndex: this.modelIndex,
+        cache: this.prewarmCache,
+        creditTracker: this.creditTracker
+    });
+    routeFailover = new RouteFailover({
+        pool: this.sellerPool,
+        creditTracker: this.creditTracker
+    });
+    // v1.2 §18.5: assigned in the constructor because the scheduler needs
+    // config-derived knobs. The `!` opts out of strict-initialization so the
+    // rest of the class can treat it as non-nullable.
+    prewarmScheduler;
     constructor(config) {
         this.tokenStore = new BuyerStore({ dbPath: config.dbPath });
         const routingPreference = this.tokenStore.getDaemonRuntimeConfig("routing")
@@ -300,6 +134,43 @@ export class TokenbuddyDaemon {
                 "auto";
         this.selectedSellerId =
             config.selectedSellerId || routingPreference?.sellerId;
+        // 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, {
+            prewarmScheduler: new PrewarmScheduler({
+                modelIndex: this.modelIndex,
+                cache: this.prewarmCache,
+                prober: this.buildHealthProber(config.warmupProbeTimeoutMs ?? 3000),
+                idleIntervalMs: (config.warmupRefreshIntervalSecs ?? 60) * 1000
+            })
+        });
+    }
+    buildHealthProber(timeoutMs) {
+        return async (seller, signal) => {
+            try {
+                const ac = new AbortController();
+                const timer = setTimeout(() => ac.abort(new Error("healthz timeout")), timeoutMs);
+                if (signal) {
+                    if (signal.aborted) {
+                        ac.abort(signal.reason);
+                    }
+                    else {
+                        signal.addEventListener("abort", () => ac.abort(signal.reason), { once: true });
+                    }
+                }
+                const startedAt = Date.now();
+                const res = await fetch(`${seller.url.replace(/\/+$/, "")}/healthz`, { signal: ac.signal });
+                clearTimeout(timer);
+                if (!res.ok) {
+                    return { ok: false, latencyMs: Date.now() - startedAt, httpStatus: res.status, errorMessage: `healthz returned ${res.status}` };
+                }
+                return { ok: true, latencyMs: Date.now() - startedAt, httpStatus: res.status };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { ok: false, latencyMs: 0, errorMessage: message };
+            }
+        };
     }
     activeControlPort() {
         const address = this.controlServer?.address?.();
@@ -309,8 +180,43 @@ export class TokenbuddyDaemon {
         const address = this.proxyServer?.address?.();
         return typeof address === "object" && address ? address.port : this.config.proxyPort;
     }
+    // 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
+    // trades freshness for availability: requests still route, but the
+    // model set is whatever was cached before the registry outgrew 1MB.
+    lastRegistrySnapshot = null;
     async fetchRegistry() {
-        return await fetchSellerRegistry(this.config.sellerRegistryUrl);
+        try {
+            const registry = await fetchSellerRegistry(this.config.sellerRegistryUrl);
+            this.modelIndex.rebuild(registry.sellers, {
+                registryVersion: registry.version,
+                defaultSellerId: registry.defaultSeller
+            });
+            this.sellerPool.sync();
+            this.lastRegistrySnapshot = registry;
+            return registry;
+        }
+        catch (err) {
+            // v1.2 §18.9: if the bootstrap returns 413, fall back to the
+            // last-known registry document. This keeps the buyer routing even
+            // when the registry temporarily outgrows the 1MB cap.
+            if (err instanceof RegistryTooLargeError && this.lastRegistrySnapshot) {
+                logger.warn("registry.stale_fallback", "registry returned 413; using last-known snapshot for routing", {
+                    sellerRegistryUrl: this.config.sellerRegistryUrl,
+                    cachedVersion: this.lastRegistrySnapshot.version,
+                    cachedSellers: this.lastRegistrySnapshot.sellers.length
+                });
+                const stale = this.lastRegistrySnapshot;
+                this.modelIndex.rebuild(stale.sellers, {
+                    registryVersion: stale.version,
+                    defaultSellerId: stale.defaultSeller
+                });
+                this.sellerPool.sync();
+                return stale;
+            }
+            throw err;
+        }
     }
     runtimeSummary() {
         const sellerRoutingMode = this.selectedSellerId ? "fixed" : this.selectionMode;
@@ -413,45 +319,39 @@ export class TokenbuddyDaemon {
         if (!paymentMethod || !["mock", "clawtip"].includes(paymentMethod)) {
             throw new Error("mock or clawtip payment method is not configured as an enabled buyer payment method");
         }
+        // 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
+        // pulling `models` directly off the registry entries.
         const registry = await this.fetchRegistry();
-        const defaultSellers = registry.sellers.filter((seller) => seller.id === registry.defaultSeller);
-        const backupSellers = registry.sellers.filter((seller) => seller.id !== registry.defaultSeller);
-        const manualSellers = this.selectedSellerId
-            ? registry.sellers.filter((seller) => seller.id === this.selectedSellerId)
-            : defaultSellers;
-        const sellers = this.selectionMode === "manual" ? manualSellers : [...defaultSellers, ...backupSellers];
-        const routes = [];
-        for (const seller of sellers) {
-            let manifest;
-            try {
-                manifest = await fetchSellerManifest(seller);
-            }
-            catch (error) {
-                logger.warn("route.manifest.failed", "seller manifest unavailable during route selection", {
-                    sellerKey: seller.id,
-                    model: modelId,
-                    endpoint,
-                    errorMessage: error instanceof Error ? error.message : String(error)
-                });
-                continue;
-            }
-            const protocols = manifestProtocols(manifest, seller);
-            const paymentMethods = manifestPaymentMethods(manifest, seller);
-            const modelIds = manifestModelIds(manifest);
-            if (!protocols.includes(protocol) || !paymentMethods.includes(paymentMethod) || !modelIds.includes(modelId)) {
-                continue;
-            }
-            routes.push({
-                seller,
-                manifest,
-                protocol,
-                modelId,
-                paymentMethod
-            });
+        const indexCandidates = this.modelIndex.sellersFor(modelId, { protocol, paymentMethod });
+        let ordered = indexCandidates;
+        if (this.selectionMode === "manual" && this.selectedSellerId) {
+            ordered = indexCandidates.filter((seller) => seller.id === this.selectedSellerId);
+        }
+        else if (this.selectionMode === "manual" && registry.defaultSeller) {
+            ordered = indexCandidates.filter((seller) => seller.id === registry.defaultSeller);
+        }
+        else if (registry.defaultSeller) {
+            // auto mode: default first, then backups in registry order
+            ordered = [
+                ...indexCandidates.filter((seller) => seller.id === registry.defaultSeller),
+                ...indexCandidates.filter((seller) => seller.id !== registry.defaultSeller)
+            ];
         }
-        if (routes.length === 0) {
+        if (ordered.length === 0) {
             throw new Error(`no compatible seller for ${endpoint} model ${modelId}`);
         }
+        const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
+        const routes = ordered.map((seller) => ({
+            seller,
+            manifest: null,
+            protocol,
+            modelId,
+            paymentMethod,
+            poolEntry: poolById.get(seller.id)
+        }));
         logger.info("route.candidates.prewarmed", "seller route candidates prewarmed", {
             model: modelId,
             endpoint,
@@ -463,38 +363,51 @@ export class TokenbuddyDaemon {
         });
         return routes;
     }
-    logRouteSelected(route, endpoint, routeIndex) {
-        logger.info("route.selected", "seller route selected", {
-            sellerKey: route.seller.id,
-            model: route.modelId,
-            endpoint,
-            protocol: route.protocol,
-            paymentMethod: route.paymentMethod,
-            routeIndex,
-            backup: routeIndex > 0
-        });
-    }
-    shouldFailoverStatus(status) {
-        return status === 429 || status >= 500;
-    }
-    logFailover(route, endpoint, routeIndex, reason, status) {
-        logger.warn("route.failover.triggered", "seller route failed over to backup candidate", {
-            sellerKey: route.seller.id,
-            model: route.modelId,
-            endpoint,
-            routeIndex,
-            reason,
-            status
-        });
-    }
     failoverErrorMessage(error) {
         return error instanceof Error ? error.message : String(error);
     }
-    async selectSeller(endpoint, modelId) {
-        const routes = await this.selectSellerRoutes(endpoint, modelId);
-        const route = routes[0];
-        this.logRouteSelected(route, endpoint, 0);
-        return route;
+    /**
+     * Map an HTTP status from a failed seller call to a `FailureKind` that
+     * the route-failover controller understands. Hard 4xx (other than
+     * auth/insufficient) means the seller is wrong for the request; 5xx
+     * and 429 are treated as transient and eligible for the soft-failure
+     * retry budget. The v1.1 "insufficient funds" check stays on the
+     * caller side because it short-circuits the failure path with a
+     * re-purchase.
+     */
+    classifyFailureStatus(status) {
+        if (status === 401 || status === 403) {
+            return "auth_invalid";
+        }
+        if (status === 402) {
+            return "insufficient_funds";
+        }
+        if (status === 400 || status === 404 || status === 422) {
+            return "hard_4xx";
+        }
+        return "soft_5xx";
+    }
+    /**
+     * Emit the structured failover log line. The decision itself is
+     * produced by `RouteFailover.decide`; this helper exists only to keep
+     * the controller loop readable.
+     */
+    handleFailoverDecision(decision, context) {
+        if (decision.action === "retry_same_seller") {
+            return;
+        }
+        if (decision.action === "failover_next") {
+            logger.warn("route.failover.triggered", "seller route failed over to backup candidate", {
+                sellerKey: context.sellerKey,
+                endpoint: context.endpoint,
+                routeIndex: context.routeIndex,
+                reason: decision.reason,
+                status: context.status,
+                wastedCreditMicros: decision.wastedCreditMicros,
+                freshPurchase: decision.freshPurchase,
+                retryAttemptsBeforeFailover: decision.retryAttemptsBeforeFailover
+            });
+        }
     }
     async listSellerBackedModels() {
         const catalog = await discoverSellerBackedModels(this.config.sellerRegistryUrl);
@@ -668,13 +581,58 @@ export class TokenbuddyDaemon {
         }
         return parsed;
     }
+    /**
+     * v1.2 §8: hard per-request deadline. The buyer refuses to wait longer
+     * than this for a single seller; on expiry the request is aborted and
+     * the route-failover controller can either retry the same seller with
+     * a smaller body or fail over. Configurable via
+     * `TB_PROXYD_REQUEST_DEADLINE_MS` (default 30s).
+     */
+    requestDeadlineMs() {
+        const raw = process.env.TB_PROXYD_REQUEST_DEADLINE_MS;
+        if (!raw) {
+            return 30_000;
+        }
+        const parsed = Number(raw);
+        if (!Number.isInteger(parsed) || parsed < 1000) {
+            return 30_000;
+        }
+        return parsed;
+    }
+    /**
+     * Safety margin subtracted from the cached token's `expiresAt` before
+     * deciding to reuse it. Buying a new token 60s before expiry gives the
+     * upstream enough headroom to reject any in-flight calls under the old
+     * token before the buyer assumes the new one is valid.
+     */
+    tokenExpirySafetyMarginMs() {
+        const raw = process.env.TB_PROXYD_TOKEN_EXPIRY_SAFETY_MARGIN_MS;
+        if (!raw) {
+            return 60_000;
+        }
+        const parsed = Number(raw);
+        if (!Number.isInteger(parsed) || parsed < 0) {
+            return 60_000;
+        }
+        return parsed;
+    }
     async getOrPurchaseToken(route) {
         const sellerKey = route.seller.id;
         const sellerUrl = normalizeSellerUrl(route.seller);
         const { modelId, paymentMethod } = route;
         const cached = this.tokenStore.getToken(sellerKey);
         const rebuyMinBalanceMicros = this.tokenRebuyMinBalanceMicros();
-        if (cached && cached.balanceMicros > rebuyMinBalanceMicros) {
+        // v1.2 PR-fix (2026-06-02): reject cached tokens that are inside the
+        // safety margin of their seller-assigned expiry. The previous
+        // implementation only checked `balanceMicros`, which let the buyer
+        // keep serving 24h-expired access tokens to the upstream and
+        // produced 401 "Bearer token is invalid or expired" errors. The
+        // `expiresAt` field is sourced from the seller's
+        // `/purchase/complete` response and is part of the `saveToken`
+        // contract.
+        const expiresAtMs = cached?.expiresAt ? Date.parse(cached.expiresAt) : NaN;
+        const tokenStillFresh = Number.isFinite(expiresAtMs) && Date.now() + this.tokenExpirySafetyMarginMs() < expiresAtMs;
+        if (cached && tokenStillFresh && cached.balanceMicros > rebuyMinBalanceMicros) {
             logger.info("token.cache.hit", "seller token cache hit", {
                 sellerKey,
                 model: modelId,
@@ -687,7 +645,8 @@ export class TokenbuddyDaemon {
             sellerKey,
             model: modelId,
             balanceMicros: cached?.balanceMicros || 0,
-            rebuyMinBalanceMicros
+            rebuyMinBalanceMicros,
+            expired: Boolean(cached) && !tokenStillFresh
         });
         const purchaseKey = `${sellerKey}:${modelId}:${paymentMethod}`;
         const purchasePromise = this.activePurchases.get(purchaseKey);
@@ -794,6 +753,9 @@ export class TokenbuddyDaemon {
                     paymentReference: completeData.paymentReference || completeData.payment_reference,
                     completedAt: new Date().toISOString()
                 });
+                // v1.1: feed the credit tracker so the route-failover controller
+                // knows the seller is inside the fresh-purchase window.
+                this.creditTracker.recordPurchase(sellerKey, creditMicros, creditMicros);
                 logger.info("purchase.token.succeeded", "seller token purchased", {
                     sellerKey,
                     model: modelId,
@@ -949,57 +911,139 @@ export class TokenbuddyDaemon {
             for (let routeIndex = 0; routeIndex < routes.length; routeIndex += 1) {
                 const route = routes[routeIndex];
                 const sellerKey = route.seller.id;
-                this.logRouteSelected(route, endpoint, routeIndex);
-                try {
-                    logger.info("proxy.request.started", "proxy request started", {
-                        requestId,
-                        sellerKey,
-                        model: modelId,
-                        requestedModel: requestedModelId,
-                        endpoint,
-                        stream: Boolean(body.stream)
-                    });
-                    const sellerUrl = normalizeSellerUrl(route.seller);
-                    const upstreamBody = this.applyResolvedModelToBody(endpoint, {
-                        ...body,
-                        requestId
-                    }, modelId);
-                    const sendSellerRequest = async (token) => fetch(`${sellerUrl}${endpoint}`, {
-                        method: "POST",
-                        headers: {
-                            "Content-Type": "application/json",
-                            "Authorization": `Bearer ${token}`,
-                            "X-Request-Id": requestId,
-                            "Idempotency-Key": idempotencyKey
-                        },
-                        body: JSON.stringify(upstreamBody)
-                    });
-                    logger.info("proxy.upstream_fetch.started", "proxy upstream fetch started", {
-                        requestId,
-                        sellerKey,
-                        model: modelId,
-                        endpoint,
-                        stream: Boolean(body.stream)
-                    });
-                    let token = await this.getOrPurchaseToken(route);
-                    let upstreamResponse = await sendSellerRequest(token);
-                    if (!upstreamResponse.ok) {
-                        const errorBody = await upstreamResponse.text();
-                        if (this.isInsufficientFundsResponse(upstreamResponse.status, errorBody)) {
-                            token = await this.recoverFromInsufficientFunds(route, token);
-                            upstreamResponse = await sendSellerRequest(token);
-                            if (upstreamResponse.ok) {
-                                logger.info("proxy.retry_after_402.succeeded", "seller request succeeded after one-shot auto purchase retry", {
-                                    requestId,
-                                    sellerKey,
-                                    model: modelId,
-                                    endpoint,
-                                    durationMs: Date.now() - startedAt
-                                });
+                logger.info("route.selected", "seller route selected", {
+                    sellerKey,
+                    model: modelId,
+                    endpoint,
+                    protocol: route.protocol,
+                    paymentMethod: route.paymentMethod,
+                    routeIndex,
+                    backup: routeIndex > 0
+                });
+                let attempt = 0;
+                // Soft-failure retry budget; the route-failover controller decides
+                // whether the same seller should be retried or we move on. The
+                // v1 "1 retry for 4xx fallback" loop is replaced with a
+                // stateful decision per attempt.
+                // eslint-disable-next-line no-constant-condition
+                while (true) {
+                    try {
+                        logger.info("proxy.request.started", "proxy request started", {
+                            requestId,
+                            sellerKey,
+                            model: modelId,
+                            requestedModel: requestedModelId,
+                            endpoint,
+                            stream: Boolean(body.stream),
+                            attempt
+                        });
+                        const sellerUrl = normalizeSellerUrl(route.seller);
+                        const upstreamBody = this.applyResolvedModelToBody(endpoint, {
+                            ...body,
+                            requestId
+                        }, modelId);
+                        logger.info("proxy.upstream_fetch.started", "proxy upstream fetch started", {
+                            requestId,
+                            sellerKey,
+                            model: modelId,
+                            endpoint,
+                            stream: Boolean(body.stream),
+                            upstreamBody
+                        });
+                        // v1.1 §17.5: refuse to auto-purchase once the session budget is
+                        // exhausted. The seller is treated as "no auto-purchase available"
+                        // and the request fails over to the next candidate.
+                        if (!this.routeFailover.canAutoPurchase()) {
+                            logger.warn("purchase.budget.exceeded", "session auto-purchase budget exhausted; failing over without buying", {
+                                requestId,
+                                sellerKey,
+                                model: modelId,
+                                endpoint,
+                                routeIndex
+                            });
+                            lastError = new Error("auto-purchase budget exceeded for this session");
+                            break;
+                        }
+                        // v1.1: a purchase failure means the seller is unreachable for
+                        // payment, not "transiently flapping". Do not retry the same
+                        // seller; transfer leftover to wasted and fail over immediately.
+                        let token;
+                        try {
+                            token = await this.getOrPurchaseToken(route);
+                        }
+                        catch (purchaseError) {
+                            logger.warn("purchase.failed", "seller auto-purchase failed; failing over without retry", {
+                                requestId,
+                                sellerKey,
+                                model: modelId,
+                                endpoint,
+                                errorMessage: this.failoverErrorMessage(purchaseError)
+                            });
+                            this.routeFailover.decide({
+                                sellerId: sellerKey,
+                                errorKind: "deadline",
+                                errorMessage: this.failoverErrorMessage(purchaseError),
+                                attempt
+                            }, routes.length - routeIndex);
+                            lastError = purchaseError;
+                            break;
+                        }
+                        // v1.2 §8: enforce a hard per-request deadline so a slow
+                        // upstream cannot hang the buyer. The deadline is honored by
+                        // the AbortController passed to `fetch`; sellers that observe
+                        // the `X-TokenBuddy-Deadline-Ms` header (PR-6) can propagate
+                        // it to their own upstream fetch via the same signal.
+                        const deadlineMs = this.requestDeadlineMs();
+                        const requestAc = new AbortController();
+                        const requestTimer = setTimeout(() => requestAc.abort(new Error("buyer deadline exceeded")), deadlineMs);
+                        const sendSellerRequest = async (token) => {
+                            const headers = {
+                                "Content-Type": "application/json",
+                                "Authorization": `Bearer ${token}`,
+                                "X-Request-Id": requestId,
+                                "Idempotency-Key": idempotencyKey
+                            };
+                            headers["X-TokenBuddy-Deadline-Ms"] = String(deadlineMs);
+                            return fetch(`${sellerUrl}${endpoint}`, {
+                                method: "POST",
+                                headers,
+                                body: JSON.stringify(upstreamBody),
+                                signal: requestAc.signal
+                            });
+                        };
+                        let upstreamResponse = await sendSellerRequest(token);
+                        if (!upstreamResponse.ok) {
+                            const errorBody = await upstreamResponse.text();
+                            if (this.isInsufficientFundsResponse(upstreamResponse.status, errorBody)) {
+                                token = await this.recoverFromInsufficientFunds(route, token);
+                                upstreamResponse = await sendSellerRequest(token);
+                                if (upstreamResponse.ok) {
+                                    logger.info("proxy.retry_after_402.succeeded", "seller request succeeded after one-shot auto purchase retry", {
+                                        requestId,
+                                        sellerKey,
+                                        model: modelId,
+                                        endpoint,
+                                        durationMs: Date.now() - startedAt
+                                    });
+                                }
+                                else {
+                                    const retryErrorBody = await upstreamResponse.text();
+                                    logger.warn("proxy.retry_after_402.failed", "seller request still failed after one-shot auto purchase retry", {
+                                        requestId,
+                                        sellerKey,
+                                        model: modelId,
+                                        endpoint,
+                                        status: upstreamResponse.status,
+                                        durationMs: Date.now() - startedAt
+                                    });
+                                    this.copyUpstreamHeaders(upstreamResponse, res);
+                                    res.status(upstreamResponse.status);
+                                    res.send(retryErrorBody);
+                                    return;
+                                }
                             }
                             else {
-                                const retryErrorBody = await upstreamResponse.text();
-                                logger.warn("proxy.retry_after_402.failed", "seller request still failed after one-shot auto purchase retry", {
+                                logger.warn("proxy.upstream_fetch.failed", "proxy upstream fetch returned non-ok status", {
                                     requestId,
                                     sellerKey,
                                     model: modelId,
@@ -1007,117 +1051,126 @@ export class TokenbuddyDaemon {
                                     status: upstreamResponse.status,
                                     durationMs: Date.now() - startedAt
                                 });
-                                this.copyUpstreamHeaders(upstreamResponse, res);
-                                res.status(upstreamResponse.status);
-                                res.send(retryErrorBody);
-                                return;
-                            }
-                        }
-                        else {
-                            logger.warn("proxy.upstream_fetch.failed", "proxy upstream fetch returned non-ok status", {
-                                requestId,
-                                sellerKey,
-                                model: modelId,
-                                endpoint,
-                                status: upstreamResponse.status,
-                                durationMs: Date.now() - startedAt
-                            });
-                            if (this.shouldFailoverStatus(upstreamResponse.status) && routeIndex < routes.length - 1) {
+                                const kind = this.classifyFailureStatus(upstreamResponse.status);
+                                const decision = this.routeFailover.decide({
+                                    sellerId: sellerKey,
+                                    status: upstreamResponse.status,
+                                    errorKind: kind,
+                                    errorMessage: errorBody,
+                                    attempt
+                                }, routes.length - routeIndex);
+                                this.handleFailoverDecision(decision, { sellerKey, endpoint, routeIndex });
+                                if (decision.action === "fail_fast" || decision.action === "abort") {
+                                    this.copyUpstreamHeaders(upstreamResponse, res);
+                                    res.status(upstreamResponse.status);
+                                    res.send(errorBody);
+                                    return;
+                                }
+                                if (decision.action === "retry_same_seller") {
+                                    attempt += 1;
+                                    if (decision.retryDelayMs) {
+                                        await new Promise((resolve) => setTimeout(resolve, decision.retryDelayMs));
+                                    }
+                                    continue;
+                                }
+                                // failover_next
                                 lastError = new Error(`seller ${sellerKey} returned ${upstreamResponse.status}`);
-                                this.logFailover(route, endpoint, routeIndex, "upstream_status", upstreamResponse.status);
-                                continue;
-                            }
-                            this.copyUpstreamHeaders(upstreamResponse, res);
-                            res.status(upstreamResponse.status);
-                            res.send(errorBody);
-                            return;
-                        }
-                    }
-                    this.copyUpstreamHeaders(upstreamResponse, res);
-                    res.status(upstreamResponse.status);
-                    logger.info("proxy.upstream_fetch.succeeded", "proxy upstream fetch succeeded", {
-                        requestId,
-                        sellerKey,
-                        model: modelId,
-                        endpoint,
-                        status: upstreamResponse.status,
-                        stream: Boolean(body.stream)
-                    });
-                    const contentType = upstreamResponse.headers.get("content-type") || "";
-                    if (contentType.includes("text/event-stream") || Boolean(body.stream)) {
-                        const reader = upstreamResponse.body?.getReader();
-                        if (!reader) {
-                            res.end();
-                            return;
-                        }
-                        let bytes = 0;
-                        const decoder = new TextDecoder();
-                        const responsesStreamNormalizer = new ResponsesStreamNormalizer();
-                        const settlementExtractor = new SellerSettlementStreamExtractor();
-                        while (true) {
-                            const { done, value } = await reader.read();
-                            if (done) {
                                 break;
                             }
-                            bytes += value.byteLength;
-                            const chunk = decoder.decode(value, { stream: true });
-                            const sellerChunk = settlementExtractor.push(chunk);
-                            if (sellerChunk.length === 0) {
-                                continue;
+                        }
+                        // Successful response: stream or buffer.
+                        this.copyUpstreamHeaders(upstreamResponse, res);
+                        res.status(upstreamResponse.status);
+                        logger.info("proxy.upstream_fetch.succeeded", "proxy upstream fetch succeeded", {
+                            requestId,
+                            sellerKey,
+                            model: modelId,
+                            endpoint,
+                            status: upstreamResponse.status,
+                            stream: Boolean(body.stream)
+                        });
+                        const contentType = upstreamResponse.headers.get("content-type") || "";
+                        if (contentType.includes("text/event-stream") || Boolean(body.stream)) {
+                            const reader = upstreamResponse.body?.getReader();
+                            if (!reader) {
+                                res.end();
+                                return;
                             }
-                            if (endpoint === "/v1/responses") {
-                                const normalized = responsesStreamNormalizer.push(sellerChunk);
-                                if (normalized.length > 0) {
-                                    res.write(`${normalized}\n\n`);
+                            let bytes = 0;
+                            const decoder = new TextDecoder();
+                            const settlementExtractor = new SellerSettlementStreamExtractor();
+                            while (true) {
+                                const { done, value } = await reader.read();
+                                if (done) {
+                                    break;
+                                }
+                                bytes += value.byteLength;
+                                const chunk = decoder.decode(value, { stream: true });
+                                // 透明代理：把 seller 的 SSE 字节原样转给客户端，只剥离我们注入的
+                                // tokenbuddy.settlement 事件（不让客户端看到内部记账字段）。除此之外
+                                // 不做任何协议转换——卖方格式 bug（如 chat.completion.chunk prefix、
+                                // 缺 event: 行）由卖方修，buyer 不兜底。
+                                const sellerChunk = settlementExtractor.push(chunk);
+                                if (sellerChunk.length > 0) {
+                                    res.write(sellerChunk);
                                 }
                             }
-                            else {
-                                res.write(sellerChunk);
-                            }
-                        }
-                        const settlementTrailing = settlementExtractor.finish();
-                        if (settlementTrailing.downstream.length > 0) {
-                            if (endpoint === "/v1/responses") {
-                                const normalized = responsesStreamNormalizer.push(settlementTrailing.downstream);
-                                if (normalized.length > 0) {
-                                    res.write(`${normalized}\n\n`);
+                            // flush TextDecoder 内部 buffer：stream:true 模式下最后可能留有几个字节的
+                            // 不完整 UTF-8 序列（多字节字符被切到下一 chunk 的场景），不调 stream:false
+                            // flush 就 break 会丢这批字节。上面的 stream 末尾事件（done / completed）
+                            // 之前被吞掉就是这个原因。
+                            const decoderTail = decoder.decode();
+                            if (decoderTail.length > 0) {
+                                const sellerTail = settlementExtractor.push(decoderTail);
+                                if (sellerTail.length > 0) {
+                                    res.write(sellerTail);
                                 }
                             }
-                            else {
+                            const settlementTrailing = settlementExtractor.finish();
+                            if (settlementTrailing.downstream.length > 0) {
                                 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));
+                            return;
                         }
-                        if (endpoint === "/v1/responses") {
-                            const trailing = responsesStreamNormalizer.finish();
-                            if (trailing.length > 0) {
-                                res.write(`${trailing}\n\n`);
-                            }
-                        }
-                        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));
+                        const responseBody = await upstreamResponse.text();
+                        res.send(responseBody);
+                        const usage = this.readUsage(responseBody);
+                        this.recordReconciledInference(route, endpoint, requestId, usage, this.parseSellerSettlementSummary(upstreamResponse.headers), this.inferPromptForHash(body), responseBody);
                         return;
                     }
-                    const responseBody = await upstreamResponse.text();
-                    res.send(responseBody);
-                    const usage = this.readUsage(responseBody);
-                    this.recordReconciledInference(route, endpoint, requestId, usage, this.parseSellerSettlementSummary(upstreamResponse.headers), this.inferPromptForHash(body), responseBody);
-                    return;
-                }
-                catch (routeError) {
-                    lastError = routeError;
-                    logger.warn("proxy.route.failed", "seller route failed before response", {
-                        requestId,
-                        sellerKey,
-                        model: modelId,
-                        endpoint,
-                        errorMessage: this.failoverErrorMessage(routeError),
-                        durationMs: Date.now() - startedAt
-                    });
-                    if (!res.headersSent && routeIndex < routes.length - 1) {
-                        this.logFailover(route, endpoint, routeIndex, "exception");
-                        continue;
+                    catch (routeError) {
+                        lastError = routeError;
+                        const kind = "deadline";
+                        const decision = this.routeFailover.decide({
+                            sellerId: sellerKey,
+                            errorKind: kind,
+                            errorMessage: this.failoverErrorMessage(routeError),
+                            attempt
+                        }, routes.length - routeIndex);
+                        this.handleFailoverDecision(decision, { sellerKey, endpoint, routeIndex, reason: "exception" });
+                        logger.warn("proxy.route.failed", "seller route failed before response", {
+                            requestId,
+                            sellerKey,
+                            model: modelId,
+                            endpoint,
+                            errorMessage: this.failoverErrorMessage(routeError),
+                            durationMs: Date.now() - startedAt
+                        });
+                        if (decision.action === "retry_same_seller") {
+                            attempt += 1;
+                            if (decision.retryDelayMs) {
+                                await new Promise((resolve) => setTimeout(resolve, decision.retryDelayMs));
+                            }
+                            continue;
+                        }
+                        if (decision.action === "fail_fast" || decision.action === "abort") {
+                            throw routeError;
+                        }
+                        // failover_next
+                        break;
                     }
-                    throw routeError;
                 }
             }
             throw lastError instanceof Error ? lastError : new Error("all seller routes failed");
@@ -1189,6 +1242,46 @@ export class TokenbuddyDaemon {
                 inferences: this.tokenStore.listInferenceLedger()
             });
         });
+        // v1.2 §18.11: control plane snapshot of the prewarm cache + seller
+        // pool + credit tracker. `tb doctor` reads this to render the
+        // recovery / prewarm / credit summary block.
+        controlApp.get("/v1.2/prewarm", (req, res) => {
+            const prewarmEntries = this.prewarmCache.snapshot().map((entry) => ({
+                modelId: entry.modelId,
+                protocol: entry.protocol,
+                paymentMethod: entry.paymentMethod,
+                state: entry.state,
+                candidateCount: entry.candidates.length,
+                warmedAt: entry.warmedAt,
+                ttlMs: entry.ttlMs,
+                consecutiveWarmingFailures: entry.consecutiveWarmingFailures
+            }));
+            const poolSnapshot = this.sellerPool.snapshot().map((entry) => ({
+                sellerId: entry.sellerId,
+                url: entry.url,
+                circuit: entry.circuit,
+                consecutiveFailures: entry.consecutiveFailures,
+                lastSuccessAt: entry.lastSuccessAt,
+                lastFailAt: entry.lastFailAt,
+                healthScore: entry.healthScore
+            }));
+            const creditSummary = this.creditTracker.summary();
+            const focusSet = this.resolveFocusSet();
+            const schedulerStats = this.prewarmScheduler.stats();
+            res.status(200).json({
+                prewarm: {
+                    entries: prewarmEntries,
+                    size: prewarmEntries.length
+                },
+                pool: {
+                    size: poolSnapshot.length,
+                    entries: poolSnapshot
+                },
+                credit: creditSummary,
+                focusSet,
+                scheduler: schedulerStats
+            });
+        });
         controlApp.get("/sellers", async (req, res) => {
             try {
                 const registry = await this.fetchRegistry();
@@ -1399,12 +1492,55 @@ export class TokenbuddyDaemon {
             sellerRegistryUrl: this.config.sellerRegistryUrl,
             selectionMode: this.selectionMode
         });
+        // v1.2 §18.5: kick off the on-demand prewarm pipeline. The startup
+        // sweep runs after the configured jitter window (5-10s by default);
+        // subsequent refreshes run on the `idleIntervalMs` cadence and the
+        // `forwardProxyRequest` hot path can dispatch lazy prewarms on miss.
+        this.prewarmScheduler.start();
+        void this.runStartupPrewarmSweep();
+    }
+    /**
+     * 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.
+     */
+    resolveFocusSet() {
+        const explicit = this.config.warmupModels ?? [];
+        if (explicit.length > 0) {
+            return explicit;
+        }
+        const envRaw = process.env.TB_BUYER_WARMUP_MODELS || "";
+        const envModels = envRaw.split(",").map((s) => s.trim()).filter(Boolean);
+        if (envModels.length > 0) {
+            return envModels;
+        }
+        return this.tokenStore.recentModels(7, 5);
+    }
+    async runStartupPrewarmSweep() {
+        const focusSet = this.resolveFocusSet();
+        if (focusSet.length === 0) {
+            logger.info("prewarm.startup.skipped", "no focus set configured; relying on lazy prewarms", {});
+            return;
+        }
+        logger.info("prewarm.startup.scheduled", "startup prewarm sweep scheduled", {
+            focusSetSize: focusSet.length,
+            focusSet: focusSet.slice(0, 20)
+        });
+        try {
+            await this.prewarmScheduler.runStartupPrewarm(focusSet);
+        }
+        catch (err) {
+            logger.warn("prewarm.startup.failed", "startup prewarm sweep failed", {
+                errorMessage: err instanceof Error ? err.message : String(err)
+            });
+        }
     }
     stop() {
         if (this.controlServer)
             this.controlServer.close();
         if (this.proxyServer)
             this.proxyServer.close();
+        void this.prewarmScheduler.stop();
         this.tokenStore.close();
     }
 }