@tokenbuddy/tokenbuddy 1.0.9 → 1.0.11

package/src/daemon.ts

@@ -14,17 +14,24 @@ import {
 } from "./provider-install.js";
 import {
   discoverSellerBackedModels,
-  fetchSellerManifest,
   fetchSellerRegistry,
   manifestModelIds,
   manifestPaymentMethods,
   manifestProtocols,
   normalizeSellerUrl,
+  RegistryTooLargeError,
   type RegistrySeller,
   type SellerManifest,
   type SellerRegistryDocument,
   type SellerRoutingPreference,
 } from "./seller-catalog.js";
+import { ModelIndex } from "./model-index.js";
+import { PrewarmCache } from "./prewarm-cache.js";
+import { CreditTracker } from "./credit-tracker.js";
+import { SellerPool, type FailureKind } from "./seller-pool.js";
+import { RouteFailover, type FailoverDecision, type RouteCandidate } from "./route-failover.js";
+import { PrewarmScheduler, type SellerProber } from "./prewarm-scheduler.js";
+import type { PoolEntry } from "./seller-pool.js";
 
 const logger = createModuleLogger("tb-proxyd");
 const PROXY_JSON_BODY_LIMIT = "10mb";
@@ -36,14 +43,21 @@ export interface DaemonConfig {
   sellerRegistryUrl: string;
   selectionMode?: "auto" | "manual";
   selectedSellerId?: string;
+  // v1.2 §18.4: focus-set override. When omitted, the daemon derives the
+  // focus set from the BuyerStore's historical model usage and the
+  // `TB_BUYER_WARMUP_MODELS` env var (comma-separated).
+  warmupModels?: string[];
+  warmupRefreshIntervalSecs?: number;
+  warmupProbeTimeoutMs?: number;
 }
 
 interface SellerRoute {
   seller: RegistrySeller;
-  manifest: SellerManifest;
+  manifest: SellerManifest | null;
   protocol: string;
   modelId: string;
   paymentMethod: string;
+  poolEntry?: PoolEntry;
 }
 
 interface UsageSummary {
@@ -80,225 +94,6 @@ function numericHeaderField(value: unknown): number | undefined {
   return undefined;
 }
 
-interface ResponsesStreamState {
-  itemId: string;
-  text: string;
-  contentPartStarted: boolean;
-}
-
-class ResponsesStreamNormalizer {
-  private pending = "";
-  private readonly state = new Map<string, ResponsesStreamState>();
-
-  public push(chunk: string): string {
-    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");
-  }
-
-  public finish(): string {
-    if (!this.pending.trim()) {
-      return "";
-    }
-    const block = this.normalizeBlock(this.pending);
-    this.pending = "";
-    return block;
-  }
-
-  private normalizeBlock(block: string): string {
-    if (!block.trim()) {
-      return "";
-    }
-    // Each \n\n separates an event in SSE format
-    const subBlocks = block.split("\n\n");
-    const output: string[] = [];
-
-    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: any;
-      try {
-        payload = JSON.parse(rawData);
-      } catch {
-        output.push(sub);
-        continue;
-      }
-
-      const eventName =
-        (eventLine?.replace(/^event:\s?/, "") || payload?.type) as string;
-      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 as string);
-        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 as string;
-        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 as string;
-        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 as string;
-        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 as string;
-        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 as ResponsesStreamState | undefined;
-          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");
-  }
-
-  private getState(itemId: string): ResponsesStreamState {
-    const current = this.state.get(itemId);
-    if (current) return current;
-    const created = { itemId, text: "", contentPartStarted: false };
-    this.state.set(itemId, created);
-    return created;
-  }
-
-  private serializeEvent(name: string, data: any): string {
-    return `event: ${name}\ndata: ${JSON.stringify(data)}`;
-  }
-}
-
 class SellerSettlementStreamExtractor {
   private pending = "";
   private settlement: SellerSettlementSummary | undefined;
@@ -410,6 +205,26 @@ export class TokenbuddyDaemon {
 
   private activePurchases = new Map<string, Promise<string>>();
 
+  // v1.2 fallback pipeline: model-index, prewarm-cache, credit-tracker,
+  // pool, and route-failover together replace the v1
+  // "fetchRegistry + manifest per request" path.
+  private readonly modelIndex = new ModelIndex();
+  private readonly prewarmCache = new PrewarmCache();
+  private readonly creditTracker = new CreditTracker();
+  private readonly sellerPool = new SellerPool({
+    modelIndex: this.modelIndex,
+    cache: this.prewarmCache,
+    creditTracker: this.creditTracker
+  });
+  private readonly 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.
+  private readonly prewarmScheduler!: PrewarmScheduler;
+
   constructor(config: DaemonConfig) {
     this.tokenStore = new BuyerStore({ dbPath: config.dbPath });
     const routingPreference =
@@ -422,6 +237,42 @@ 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
+      })
+    });
+  }
+
+  private buildHealthProber(timeoutMs: number): SellerProber {
+    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 };
+      }
+    };
   }
 
   private activeControlPort(): number {
@@ -434,8 +285,43 @@ export class TokenbuddyDaemon {
     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.
+  private lastRegistrySnapshot: SellerRegistryDocument | null = null;
+
   private async fetchRegistry(): Promise<SellerRegistryDocument> {
-    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;
+    }
   }
 
   private runtimeSummary() {
@@ -553,49 +439,41 @@ export class TokenbuddyDaemon {
       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: SellerRoute[] = [];
-    for (const seller of sellers) {
-      let manifest: SellerManifest;
-      try {
-        manifest = await fetchSellerManifest(seller);
-      } catch (error: unknown) {
-        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: SellerRoute[] = 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,
@@ -608,48 +486,56 @@ export class TokenbuddyDaemon {
     return routes;
   }
 
-  private logRouteSelected(route: SellerRoute, endpoint: string, routeIndex: number): void {
-    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
-    });
+  private failoverErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
   }
 
-  private shouldFailoverStatus(status: number): boolean {
-    return status === 429 || status >= 500;
+  /**
+   * 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.
+   */
+  private classifyFailureStatus(status: number): FailureKind {
+    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";
   }
 
-  private logFailover(
-    route: SellerRoute,
-    endpoint: string,
-    routeIndex: number,
-    reason: string,
-    status?: number
+  /**
+   * Emit the structured failover log line. The decision itself is
+   * produced by `RouteFailover.decide`; this helper exists only to keep
+   * the controller loop readable.
+   */
+  private handleFailoverDecision(
+    decision: FailoverDecision,
+    context: { sellerKey: string; endpoint: string; routeIndex: number; status?: number; reason?: string }
   ): void {
-    logger.warn("route.failover.triggered", "seller route failed over to backup candidate", {
-      sellerKey: route.seller.id,
-      model: route.modelId,
-      endpoint,
-      routeIndex,
-      reason,
-      status
-    });
-  }
-
-  private failoverErrorMessage(error: unknown): string {
-    return error instanceof Error ? error.message : String(error);
-  }
-
-  private async selectSeller(endpoint: string, modelId: string): Promise<SellerRoute> {
-    const routes = await this.selectSellerRoutes(endpoint, modelId);
-    const route = routes[0];
-    this.logRouteSelected(route, endpoint, 0);
-    return route;
+    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
+      });
+    }
   }
 
   private async listSellerBackedModels(): Promise<{
@@ -851,13 +737,60 @@ 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).
+   */
+  private requestDeadlineMs(): number {
+    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.
+   */
+  private tokenExpirySafetyMarginMs(): number {
+    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;
+  }
+
   private async getOrPurchaseToken(route: SellerRoute): Promise<string> {
     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,
@@ -870,7 +803,8 @@ export class TokenbuddyDaemon {
       sellerKey,
       model: modelId,
       balanceMicros: cached?.balanceMicros || 0,
-      rebuyMinBalanceMicros
+      rebuyMinBalanceMicros,
+      expired: Boolean(cached) && !tokenStillFresh
     });
 
     const purchaseKey = `${sellerKey}:${modelId}:${paymentMethod}`;
@@ -982,6 +916,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,
@@ -1157,58 +1094,141 @@ 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 as { stream?: unknown }).stream)
-          });
-          const sellerUrl = normalizeSellerUrl(route.seller);
-          const upstreamBody = this.applyResolvedModelToBody(endpoint, {
-            ...(body as Record<string, unknown>),
-            requestId
-          }, modelId);
-          const sendSellerRequest = async (token: string) => fetch(`${sellerUrl}${endpoint}`, {
-            method: "POST",
-            headers: {
+        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 as { stream?: unknown }).stream),
+              attempt
+            });
+            const sellerUrl = normalizeSellerUrl(route.seller);
+            const upstreamBody = this.applyResolvedModelToBody(endpoint, {
+              ...(body as Record<string, unknown>),
+              requestId
+            }, modelId);
+
+            logger.info("proxy.upstream_fetch.started", "proxy upstream fetch started", {
+              requestId,
+              sellerKey,
+              model: modelId,
+              endpoint,
+              stream: Boolean((body as { stream?: unknown }).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: string;
+            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: string) => {
+            const headers: Record<string, string> = {
               "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 as { stream?: unknown }).stream)
-          });
-          let token = await this.getOrPurchaseToken(route);
+            };
+            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
-                });
+            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,
@@ -1216,131 +1236,149 @@ export class TokenbuddyDaemon {
                   status: upstreamResponse.status,
                   durationMs: Date.now() - startedAt
                 });
-                this.copyUpstreamHeaders(upstreamResponse, res);
-                res.status(upstreamResponse.status);
-                res.send(retryErrorBody);
-                return;
+                const kind: FailureKind = 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<void>((resolve) => setTimeout(resolve, decision.retryDelayMs));
+                  }
+                  continue;
+                }
+                // failover_next
+                lastError = new Error(`seller ${sellerKey} returned ${upstreamResponse.status}`);
+                break;
               }
-            } else {
-            logger.warn("proxy.upstream_fetch.failed", "proxy upstream fetch returned non-ok status", {
+            }
+
+            // 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,
-              durationMs: Date.now() - startedAt
+              stream: Boolean((body as { stream?: unknown }).stream)
             });
-            if (this.shouldFailoverStatus(upstreamResponse.status) && routeIndex < routes.length - 1) {
-              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 as { stream?: unknown }).stream)
-          });
 
-          const contentType = upstreamResponse.headers.get("content-type") || "";
-          if (contentType.includes("text/event-stream") || Boolean((body as { stream?: unknown }).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;
+            const contentType = upstreamResponse.headers.get("content-type") || "";
+            if (contentType.includes("text/event-stream") || Boolean((body as { stream?: unknown }).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 {
-                res.write(settlementTrailing.downstream);
               }
-            }
-            if (endpoint === "/v1/responses") {
-              const trailing = responsesStreamNormalizer.finish();
-              if (trailing.length > 0) {
-                res.write(`${trailing}\n\n`);
+              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;
             }
-            res.end();
+
+            const responseBody = await upstreamResponse.text();
+            res.send(responseBody);
+            const usage = this.readUsage(responseBody);
             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)
+              usage,
+              this.parseSellerSettlementSummary(upstreamResponse.headers),
+              this.inferPromptForHash(body),
+              responseBody
             );
             return;
+          } catch (routeError: unknown) {
+            lastError = routeError;
+            const kind: FailureKind = "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<void>((resolve) => setTimeout(resolve, decision.retryDelayMs));
+              }
+              continue;
+            }
+            if (decision.action === "fail_fast" || decision.action === "abort") {
+              throw routeError;
+            }
+            // failover_next
+            break;
           }
-
-          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: unknown) {
-          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;
-          }
-          throw routeError;
         }
       }
 
@@ -1419,6 +1457,47 @@ export class TokenbuddyDaemon {
       });
     });
 
+    // 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();
@@ -1632,11 +1711,56 @@ 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.
+   */
+  private resolveFocusSet(): string[] {
+    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);
+  }
+
+  private async runStartupPrewarmSweep(): Promise<void> {
+    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)
+      });
+    }
   }
 
   public stop() {
     if (this.controlServer) this.controlServer.close();
     if (this.proxyServer) this.proxyServer.close();
+    void this.prewarmScheduler.stop();
     this.tokenStore.close();
   }
 }