@tokenbuddy/tokenbuddy 1.0.13 → 1.0.15

package/src/model-index.ts

@@ -1,5 +1,5 @@
 import { createModuleLogger } from "@tokenbuddy/logging";
-import type { RegistrySeller } from "./seller-catalog.js";
+import { isBuyerVisibleRegistrySeller, type RegistrySeller } from "./seller-catalog.js";
 
 const logger = createModuleLogger("tb-proxyd:model-index");
 
@@ -73,6 +73,9 @@ export class ModelIndex {
       if (!seller || !seller.id) {
         continue;
       }
+      if (!isBuyerVisibleRegistrySeller(seller)) {
+        continue;
+      }
       // v1.2 registry schema 用 "anthropic_messages" 作为协议名（OpenAI / ClawTip
       // / 外部 client 都用这个），但 buyer 内部 `endpointProtocol` 对 /v1/messages
       // 返 "messages"（更短、更易读）。在 modelIndex 重建时做 alias 映射，让两边

package/src/prewarm-cache.ts

@@ -46,6 +46,8 @@ export interface PrewarmCandidate {
   upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
   /** 上游错误类名（HTTP status / 错误码），仅在失败时存在 */
   upstreamErrorClass?: string;
+  /** 临时容量避让截止时间；大于当前时间时不参与路由 */
+  capacityBlockedUntil?: number;
 }
 
 /**
@@ -100,6 +102,8 @@ export interface PrewarmCandidateInput {
   upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
   /** 上游错误类名，可选 */
   upstreamErrorClass?: string;
+  /** 临时容量避让截止时间；大于当前时间时不参与路由 */
+  capacityBlockedUntil?: number;
 }
 
 /**
@@ -449,7 +453,8 @@ function toCandidate(input: PrewarmCandidateInput): PrewarmCandidate {
     ttftMs: finiteNonNegative(input.ttftMs),
     avgInferenceMs: finiteNonNegative(input.avgInferenceMs),
     upstreamStatus: input.upstreamStatus,
-    upstreamErrorClass: input.upstreamErrorClass
+    upstreamErrorClass: input.upstreamErrorClass,
+    capacityBlockedUntil: finiteNonNegative(input.capacityBlockedUntil)
   };
 }
 

package/src/prewarm-scheduler.ts

@@ -35,6 +35,8 @@ export interface ProbeResult {
   ttftMs?: number;
   /** 平均推理延迟（毫秒），可选 */
   avgInferenceMs?: number;
+  /** 临时容量避让截止时间；大于当前时间时不参与路由 */
+  capacityBlockedUntil?: number;
 }
 
 /**
@@ -498,7 +500,8 @@ export class PrewarmScheduler {
           ttftMs: result.ttftMs,
           avgInferenceMs: result.avgInferenceMs,
           upstreamStatus: result.upstreamStatus,
-          upstreamErrorClass: result.upstreamErrorClass
+          upstreamErrorClass: result.upstreamErrorClass,
+          capacityBlockedUntil: result.capacityBlockedUntil
         });
         logger.info("prewarm.succeeded", "seller probe succeeded", {
           taskId: task.id,
@@ -524,7 +527,8 @@ export class PrewarmScheduler {
           ttftMs: result.ttftMs,
           avgInferenceMs: result.avgInferenceMs,
           upstreamStatus: result.upstreamStatus,
-          upstreamErrorClass: result.upstreamErrorClass
+          upstreamErrorClass: result.upstreamErrorClass,
+          capacityBlockedUntil: result.capacityBlockedUntil
         });
         logger.warn("prewarm.failed", "seller probe failed", {
           taskId: task.id,

package/src/route-failover.ts

@@ -169,6 +169,7 @@ export class RouteFailover {
   decide(context: DecideContext, totalCandidates: number): FailoverDecision {
     const isHard = context.errorKind === "hard_4xx" || context.errorKind === "auth_invalid" || context.errorKind === "no_compatible";
     const isSoft = context.errorKind === "soft_5xx" || context.errorKind === "deadline";
+    const isBusyCapacity = context.errorKind === "busy_capacity";
     const info = this.pool.inspect(context.sellerId);
     const freshPurchase = info.freshPurchase;
     const budgetExceeded = !this.creditTracker.canAutoPurchase(this.now());
@@ -179,6 +180,16 @@ export class RouteFailover {
       now: this.now()
     });
 
+    if (isBusyCapacity) {
+      return {
+        action: "failover_next",
+        reason: "busy_capacity",
+        freshPurchase,
+        retryAttemptsBeforeFailover: context.attempt,
+        budgetExceeded
+      };
+    }
+
     if (isHard) {
       // Hard failures are not eligible for retry; the seller is wrong
       // for this request. The pool has already transferred leftover

package/src/seller-catalog.ts

@@ -17,6 +17,8 @@ export interface RegistrySeller {
   id: string;
   /** 人类可读名称 */
   name?: string;
+  /** registry 发布状态；只有 `active` 参与 buyer 自动路由，缺省兼容旧 registry 为可用 */
+  status?: string;
   /** seller 服务的公网 URL（去掉尾部 `/`） */
   url: string;
   /** seller 支持的协议列表（包含 `anthropic_messages` 时内部 alias 到 `messages`） */
@@ -44,6 +46,19 @@ export interface SellerRegistryDocument {
   sellers: RegistrySeller[];
 }
 
+/**
+ * Buyer 自动路由 / 模型目录可见性门禁。
+ * 新 registry 会显式写 `status`，只有 `active` 参与 buyer 可见路径；
+ * 旧 registry 缺省 status 时按历史行为保留可用，避免升级后隐藏存量节点。
+ *
+ * @param seller registry seller
+ * @returns seller 是否应进入 buyer 路由和模型目录
+ */
+export function isBuyerVisibleRegistrySeller(seller: RegistrySeller): boolean {
+  const status = seller.status?.trim().toLowerCase();
+  return !status || status === "active";
+}
+
 /**
  * 单个 seller 的 `/manifest` 响应，兼容 snake_case 与 camelCase 字段。
  */
@@ -72,6 +87,10 @@ export interface SellerManifest {
     discountRatio?: number;
     /** 折扣系数（snake_case 兼容） */
     discount_ratio?: number;
+    /** 服务手续费系数（camelCase） */
+    serviceFeeRatio?: number;
+    /** 服务手续费系数（snake_case 兼容） */
+    service_fee_ratio?: number;
   };
 }
 
@@ -132,6 +151,8 @@ export interface SellerCatalogEntry {
   manifestSellerId?: string;
   /** 折扣系数（来自 manifest.selection） */
   discountRatio?: number;
+  /** 服务手续费系数（来自 manifest.selection） */
+  serviceFeeRatio?: number;
   /** 模型数（来自 manifest） */
   modelCount?: number;
   /** seller 支持的协议（manifest > registry fallback） */
@@ -305,7 +326,8 @@ export async function fetchSellerManifest(seller: RegistrySeller): Promise<Selle
  */
 export async function discoverSellerBackedModels(registryUrl: string): Promise<SellerCatalogResult> {
   const registry = await fetchSellerRegistry(registryUrl);
-  const sellerResults = await Promise.all(registry.sellers.map(async (seller) => {
+  const visibleSellers = registry.sellers.filter(isBuyerVisibleRegistrySeller);
+  const sellerResults = await Promise.all(visibleSellers.map(async (seller) => {
     try {
       const manifest = await fetchSellerManifest(seller);
       const protocols = manifestProtocols(manifest, seller);
@@ -328,6 +350,7 @@ export async function discoverSellerBackedModels(registryUrl: string): Promise<S
           status: "ok",
           manifestSellerId: manifest.sellerId || manifest.seller_id || seller.id,
           discountRatio: manifest.selection?.discountRatio ?? manifest.selection?.discount_ratio,
+          serviceFeeRatio: manifest.selection?.serviceFeeRatio ?? manifest.selection?.service_fee_ratio,
           modelCount: models.length,
           supportedProtocols: protocols,
           paymentMethods,

package/src/seller-pool.ts

@@ -22,6 +22,7 @@ export type FailureKind =
   | "hard_4xx"           // 400/404/422 — the seller is wrong for this request
   | "auth_invalid"       // 401/403 token invalid
   | "insufficient_funds" // 402
+  | "busy_capacity"      // 429 busy_capacity — seller is temporarily full
   | "soft_5xx"           // 429/5xx/timeout/network
   | "deadline"           // buyer deadline exceeded
   | "stream_aborted"     // upstream stream broken after first chunk
@@ -67,6 +68,8 @@ export interface PoolEntry {
   upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
   /** 上游错误类名，可选 */
   upstreamErrorClass?: string;
+  /** 临时容量避让截止时间；大于当前时间时不参与路由 */
+  capacityBlockedUntil?: number;
 }
 
 /**
@@ -133,6 +136,8 @@ export interface SellerPoolOptions {
   windowFailureRate?: number;     // default 0.5
   /** open 态保持时间（毫秒），过期后降级 half_open，默认 30000 */
   openStateMs?: number;           // default 30_000
+  /** `busy_capacity` 的短期避让时间，默认 2000ms */
+  capacityBlockMs?: number;
   /** 注入时钟（测试用），默认 `Date.now` */
   now?: () => number;
   // PoolEntry -> CircuitState transition hooks for tests.
@@ -144,7 +149,8 @@ const DEFAULTS = {
   failureThreshold: 3,
   windowMs: 60_000,
   windowFailureRate: 0.5,
-  openStateMs: 30_000
+  openStateMs: 30_000,
+  capacityBlockMs: 2_000
 };
 
 /**
@@ -162,6 +168,7 @@ export class SellerPool {
   private readonly windowMs: number;
   private readonly windowFailureRate: number;
   private readonly openStateMs: number;
+  private readonly capacityBlockMs: number;
   private readonly now: () => number;
 
   private entries = new Map<string, PoolEntry>();
@@ -174,6 +181,7 @@ export class SellerPool {
     this.windowMs = options.windowMs ?? DEFAULTS.windowMs;
     this.windowFailureRate = options.windowFailureRate ?? DEFAULTS.windowFailureRate;
     this.openStateMs = options.openStateMs ?? DEFAULTS.openStateMs;
+    this.capacityBlockMs = options.capacityBlockMs ?? DEFAULTS.capacityBlockMs;
     this.now = options.now ?? Date.now;
   }
 
@@ -183,7 +191,7 @@ export class SellerPool {
    * etc.) so the pool always reflects the latest probe results.
    */
   sync(): number {
-    const fresh = new Map<string, PoolEntry>();
+    const fresh = new Map<string, PoolEntry>(this.entries);
     for (const entry of this.cache.snapshot()) {
       for (const candidate of entry.candidates) {
         const registry = this.modelIndex.getSeller(candidate.sellerId);
@@ -208,14 +216,52 @@ export class SellerPool {
           ttftMs: candidate.ttftMs,
           avgInferenceMs: candidate.avgInferenceMs,
           upstreamStatus: candidate.upstreamStatus,
-          upstreamErrorClass: candidate.upstreamErrorClass
+          upstreamErrorClass: candidate.upstreamErrorClass,
+          capacityBlockedUntil: candidate.capacityBlockedUntil ?? previous?.capacityBlockedUntil
         });
       }
     }
+    for (const sellerId of fresh.keys()) {
+      if (!this.modelIndex.getSeller(sellerId)) {
+        fresh.delete(sellerId);
+      }
+    }
     this.entries = fresh;
     return this.entries.size;
   }
 
+  /**
+   * Ensure registry-fallback candidates also have runtime state. A seller
+   * may be selected before prewarm has produced a cache entry; failures
+   * from that first live request still need to affect the next route plan.
+   */
+  ensureRegistrySellers(sellers: RegistrySeller[], now: number = this.now()): void {
+    for (const seller of sellers) {
+      const previous = this.entries.get(seller.id);
+      if (previous) {
+        this.entries.set(seller.id, {
+          ...previous,
+          registrySeller: seller,
+          url: seller.url.replace(/\/+$/, "")
+        });
+        continue;
+      }
+      this.entries.set(seller.id, {
+        sellerId: seller.id,
+        url: seller.url.replace(/\/+$/, ""),
+        registrySeller: seller,
+        circuit: "closed",
+        consecutiveFailures: 0,
+        recentFailures: [],
+        lastSuccessAt: 0,
+        lastFailAt: 0,
+        lastProbeAt: now,
+        healthScore: 60,
+        avgLatencyMs: 0
+      });
+    }
+  }
+
   /**
    * Pick up to `limit` candidates for a (model, protocol, payment) triple.
    * Sellers in the `open` circuit are skipped unless their open state has
@@ -253,6 +299,7 @@ export class SellerPool {
         return { entry, registrySeller: row.registrySeller };
       })
       .filter((row) => row.entry.circuit !== "open")
+      .filter((row) => !isCapacityBlocked(row.entry, now))
       .sort((a, b) => b.entry.healthScore - a.entry.healthScore)
       .slice(0, limit);
 
@@ -279,7 +326,8 @@ export class SellerPool {
       consecutiveFailures: 0,
       recentFailures: [],
       lastSuccessAt: now,
-      healthScore: Math.min(100, Math.max(entry.healthScore, 60))
+      healthScore: Math.min(100, Math.max(entry.healthScore, 60)),
+      capacityBlockedUntil: undefined
     };
     this.entries.set(sellerId, next);
     this.creditTracker.recordSpend(sellerId, balanceMicros);
@@ -309,8 +357,11 @@ export class SellerPool {
       return undefined;
     }
     const now = options.now ?? this.now();
-    const recentFailures = [...entry.recentFailures, now].filter((ts) => ts >= now - this.windowMs);
-    const consecutiveFailures = entry.consecutiveFailures + 1;
+    const isBusyCapacity = kind === "busy_capacity";
+    const recentFailures = (
+      isBusyCapacity ? entry.recentFailures : [...entry.recentFailures, now]
+    ).filter((ts) => ts >= now - this.windowMs);
+    const consecutiveFailures = isBusyCapacity ? entry.consecutiveFailures : entry.consecutiveFailures + 1;
     const failureRate = recentFailures.length / Math.max(1, this.windowMs / 1000);
     const overThreshold = consecutiveFailures >= this.failureThreshold;
     const overRate = failureRate >= this.windowFailureRate;
@@ -321,7 +372,8 @@ export class SellerPool {
       circuit,
       consecutiveFailures,
       recentFailures,
-      lastFailAt: now
+      lastFailAt: now,
+      capacityBlockedUntil: isBusyCapacity ? now + this.capacityBlockMs : entry.capacityBlockedUntil
     };
     this.entries.set(sellerId, next);
     if (options.transferLeftover || isHard) {
@@ -335,6 +387,12 @@ export class SellerPool {
         recentFailureRate: failureRate,
         threshold: this.failureThreshold
       });
+    } else if (isBusyCapacity) {
+      logger.warn("pool.capacity_blocked", "seller pool entry temporarily blocked by busy capacity", {
+        sellerId,
+        capacityBlockMs: this.capacityBlockMs,
+        blockedUntil: next.capacityBlockedUntil
+      });
     }
     return next;
   }
@@ -397,6 +455,10 @@ export class SellerPool {
   }
 }
 
+function isCapacityBlocked(entry: PoolEntry, now: number): boolean {
+  return Number.isFinite(entry.capacityBlockedUntil) && (entry.capacityBlockedUntil as number) > now;
+}
+
 function asResolution(resolved: { modelId: string; matched: boolean; sellers: RegistrySeller[]; missingModelsFlag: number }): ModelIndexResolution {
   return {
     modelId: resolved.modelId,

package/src/seller-route-planner.ts

@@ -1,4 +1,4 @@
-import type { RegistrySeller } from "./seller-catalog.js";
+import { isBuyerVisibleRegistrySeller, type RegistrySeller } from "./seller-catalog.js";
 import {
   planSellerRoutes,
   type RoutingCandidate,
@@ -24,10 +24,16 @@ export interface SellerRouteMetric {
   healthScore?: number;
   /** 平均延迟（毫秒），可选 */
   avgLatencyMs?: number;
+  /** TTFT（毫秒），可选 */
+  ttftMs?: number;
+  /** 平均推理延迟（毫秒），可选 */
+  avgInferenceMs?: number;
   /** 折扣系数（0-1），可选；缺省时 scoring 视为"无折扣信息" */
   discountRatio?: number;
   /** 当前熔断状态，可选；`open` 的 seller 直接被剔除候选 */
   circuit?: SellerCircuitState;
+  /** 临时容量避让截止时间；大于当前时间时直接剔除候选 */
+  capacityBlockedUntil?: number;
 }
 
 /**
@@ -75,6 +81,8 @@ export interface SellerRoutePlannerInput {
   prewarmCandidates?: SellerRoutePrewarmCandidate[];
   /** seller 实时指标（可选；`circuit=open` 的 seller 被剔除） */
   sellerMetrics?: SellerRouteMetric[];
+  /** 当前时间戳，用于判断容量避让窗口；默认 `Date.now()` */
+  now?: number;
 }
 
 /**
@@ -89,6 +97,8 @@ export interface PlannedSellerRoute {
   metrics: {
     healthScore?: number;
     avgLatencyMs?: number;
+    ttftMs?: number;
+    avgInferenceMs?: number;
     discountRatio?: number;
     /** 在 registry 里的声明顺序（0-based，tie-breaker） */
     registryOrder: number;
@@ -128,7 +138,7 @@ interface IndexedSeller {
 
 interface MetricIndex {
   bySellerId: Map<string, SellerRouteMetric>;
-  openSellerIds: Set<string>;
+  blockedSellerIds: Set<string>;
 }
 
 /**
@@ -145,7 +155,7 @@ interface MetricIndex {
  */
 export function planSellerRouteSet(input: SellerRoutePlannerInput): SellerRoutePlan {
   const indexed = indexRegistrySellers(input.registrySellers);
-  const metrics = indexMetrics(input.sellerMetrics);
+  const metrics = indexMetrics(input.sellerMetrics, input.now ?? Date.now());
   const source = chooseCandidateSource(input, indexed, metrics);
   const strategyPlan = planSellerRoutes(source.candidates, input.routing);
   const routes = strategyPlan.routes.map((candidate) => {
@@ -159,6 +169,8 @@ export function planSellerRouteSet(input: SellerRoutePlannerInput): SellerRouteP
       metrics: {
         healthScore: candidate.healthScore,
         avgLatencyMs: candidate.avgLatencyMs,
+        ttftMs: candidate.ttftMs,
+        avgInferenceMs: candidate.avgInferenceMs,
         discountRatio: candidate.discountRatio,
         registryOrder: candidate.registryOrder
       }
@@ -189,7 +201,7 @@ function chooseCandidateSource(
         if (!indexedSeller) {
           return undefined;
         }
-        if (metrics.openSellerIds.has(indexedSeller.seller.id)) {
+        if (metrics.blockedSellerIds.has(indexedSeller.seller.id)) {
           return undefined;
         }
         return buildCandidate({
@@ -217,7 +229,7 @@ function chooseCandidateSource(
     source: "registry_fallback",
     sourceReason: prewarm.length > 0 ? "prewarm_no_compatible_candidates" : "prewarm_missing",
     candidates: indexed.ordered
-      .filter((entry) => !metrics.openSellerIds.has(entry.seller.id))
+      .filter((entry) => !metrics.blockedSellerIds.has(entry.seller.id))
       .map((entry) => buildCandidate({
         seller: entry.seller,
         registryOrder: entry.registryOrder,
@@ -246,6 +258,8 @@ function buildCandidate(input: {
     supportsPayment: sellerSupportsPayment(input.seller, input.paymentMethod),
     healthScore: input.metric?.healthScore,
     avgLatencyMs: input.metric?.avgLatencyMs,
+    ttftMs: input.metric?.ttftMs,
+    avgInferenceMs: input.metric?.avgInferenceMs,
     discountRatio: input.metric?.discountRatio,
     registryOrder: input.registryOrder
   };
@@ -261,6 +275,7 @@ function indexRegistrySellers(sellers: RegistrySeller[]): {
 } {
   const ordered = sellers
     .filter((seller) => Boolean(seller?.id && seller.url))
+    .filter((seller) => isBuyerVisibleRegistrySeller(seller))
     .map((seller, registryOrder) => ({ seller, registryOrder }));
   return {
     ordered,
@@ -268,15 +283,15 @@ function indexRegistrySellers(sellers: RegistrySeller[]): {
   };
 }
 
-function indexMetrics(metrics: SellerRouteMetric[] | undefined): MetricIndex {
-  const openSellerIds = new Set((metrics ?? [])
-    .filter((metric) => metric.circuit === "open")
+function indexMetrics(metrics: SellerRouteMetric[] | undefined, now: number): MetricIndex {
+  const blockedSellerIds = new Set((metrics ?? [])
+    .filter((metric) => metric.circuit === "open" || isCapacityBlocked(metric, now))
     .map((metric) => metric.sellerId));
   return {
     bySellerId: new Map((metrics ?? [])
-      .filter((metric) => metric.circuit !== "open")
+      .filter((metric) => !blockedSellerIds.has(metric.sellerId))
       .map((metric) => [metric.sellerId, metric])),
-    openSellerIds
+    blockedSellerIds
   };
 }
 
@@ -288,11 +303,18 @@ function mergeMetric(
     sellerId: prewarm.sellerId,
     healthScore: prewarm.healthScore ?? metric?.healthScore,
     avgLatencyMs: prewarm.avgLatencyMs ?? metric?.avgLatencyMs,
+    ttftMs: metric?.ttftMs,
+    avgInferenceMs: metric?.avgInferenceMs,
     discountRatio: metric?.discountRatio,
-    circuit: metric?.circuit
+    circuit: metric?.circuit,
+    capacityBlockedUntil: metric?.capacityBlockedUntil
   };
 }
 
+function isCapacityBlocked(metric: SellerRouteMetric, now: number): boolean {
+  return Number.isFinite(metric.capacityBlockedUntil) && (metric.capacityBlockedUntil as number) > now;
+}
+
 function sellerSupportsModel(seller: RegistrySeller, modelId: string): boolean {
   const normalized = normalizeLookupValue(modelId);
   return (seller.models ?? []).some((model) => normalizeLookupValue(model) === normalized);

package/src/seller-routing-config.ts

@@ -18,6 +18,8 @@ export interface BuyerSellerRoutingConfig extends SellerRoutingStrategyConfig {
   mode: SellerRoutingMode;
   /** 评分器：`speed` / `discount` / `balanced` */
   scorer: SellerRoutingScorer;
+  /** fixed 模式下按模型固定 seller；缺省时回退到全局 sellerId。 */
+  fixedByModel?: Record<string, string>;
 }
 
 /**
@@ -53,6 +55,7 @@ export function normalizeSellerRoutingConfig(value: unknown): BuyerSellerRouting
     return {
       mode,
       sellerId: readOptionalString(value.sellerId),
+      fixedByModel: readFixedByModel(value.fixedByModel),
       scorer
     };
   }
@@ -151,7 +154,7 @@ export function parseSellerIdList(value: string): string[] {
  * @throws 当 `fixedSet` 模式缺少 `sellerIds` 时
  */
 export function assertSellerRoutingConfig(config: BuyerSellerRoutingConfig): void {
-  if (config.mode === "fixed" && !config.sellerId?.trim()) {
+  if (config.mode === "fixed" && !config.sellerId?.trim() && Object.keys(config.fixedByModel ?? {}).length === 0) {
     throw new Error("fixed routing requires --seller <sellerId>");
   }
   if (config.mode === "fixedSet" && (!config.sellerIds || config.sellerIds.length === 0)) {
@@ -193,6 +196,16 @@ function readSellerIds(value: unknown): string[] {
   return [];
 }
 
+function readFixedByModel(value: unknown): Record<string, string> | undefined {
+  if (!isObject(value)) {
+    return undefined;
+  }
+  const entries = Object.entries(value)
+    .map(([modelId, sellerId]) => [modelId.trim(), typeof sellerId === "string" ? sellerId.trim() : ""] as const)
+    .filter(([modelId, sellerId]) => modelId.length > 0 && sellerId.length > 0);
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
 function isObject(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }