@tokenbuddy/tokenbuddy 1.0.11 → 1.0.13

package/src/seller-catalog.ts

@@ -2,13 +2,26 @@ import { createModuleLogger } from "@tokenbuddy/logging";
 
 const logger = createModuleLogger("tb-proxyd");
 
+/**
+ * buyer 端协议偏好（用于按协议过滤 catalog）。`messages` 是 anthropic 协议的简称。
+ */
 export type ProtocolPreference = "chat_completions" | "responses" | "messages";
 
+/**
+ * wallet-bootstrap `/registry/sellers` 里的 seller 描述。
+ * v1.2 起 `models` 是 buyer model-index 路由的权威依据；缺省会被报告为
+ * `models_refresh.seller_missing_models` 事件。
+ */
 export interface RegistrySeller {
+  /** seller 全局唯一 ID（也作为 token class） */
   id: string;
+  /** 人类可读名称 */
   name?: string;
+  /** seller 服务的公网 URL（去掉尾部 `/`） */
   url: string;
+  /** seller 支持的协议列表（包含 `anthropic_messages` 时内部 alias 到 `messages`） */
   supportedProtocols?: string[];
+  /** seller 支持的支付方式 */
   paymentMethods?: string[];
   /**
    * v1.2: authoritative model list for buyer-side model-index routing.
@@ -19,78 +32,152 @@ export interface RegistrySeller {
   models?: string[];
 }
 
+/**
+ * `/registry/sellers` 响应的最小形状（去掉了 buyer 不关心的 metadata）。
+ */
 export interface SellerRegistryDocument {
+  /** schema 版本号 */
   version: number;
+  /** 默认 seller ID（buyer 未指定时回落的目标） */
   defaultSeller?: string;
+  /** seller 列表 */
   sellers: RegistrySeller[];
 }
 
+/**
+ * 单个 seller 的 `/manifest` 响应，兼容 snake_case 与 camelCase 字段。
+ */
 export interface SellerManifest {
+  /** manifest schema 版本（camelCase） */
+  manifestVersion?: string;
+  /** manifest schema 版本（snake_case 兼容） */
+  manifest_version?: string;
+  /** seller 实例 ID（camelCase） */
   sellerId?: string;
+  /** seller 实例 ID（snake_case 兼容） */
   seller_id?: string;
+  /** seller 支持的协议（camelCase） */
   supportedProtocols?: string[];
+  /** seller 支持的协议（snake_case 兼容） */
   supported_protocols?: string[];
+  /** seller 支持的支付方式（camelCase） */
   paymentMethods?: string[];
+  /** seller 支持的支付方式（snake_case 兼容） */
   payment_methods?: string[];
+  /** 模型清单（含价格） */
   models?: ManifestModelRecord[];
+  /** 选择策略块（折扣等） */
   selection?: {
+    /** 折扣系数（camelCase） */
     discountRatio?: number;
+    /** 折扣系数（snake_case 兼容） */
     discount_ratio?: number;
   };
 }
 
+/**
+ * `/manifest` 响应里单个模型记录（兼容 snake_case）。
+ */
 export interface ManifestModelRecord {
+  /** 模型 ID */
   id: string;
+  /** 输入价格 USD micros/1M（camelCase） */
   inputPriceMicrosPer1m?: number;
+  /** 输出价格 USD micros/1M（camelCase） */
   outputPriceMicrosPer1m?: number;
+  /** 输入价格 USD micros/1M（snake_case 兼容） */
   input_price_micros_per_1m?: number;
+  /** 输出价格 USD micros/1M（snake_case 兼容） */
   output_price_micros_per_1m?: number;
+  /** 其它扩展字段（保留以便透传） */
   [key: string]: unknown;
 }
 
+/**
+ * 聚合后的模型目录条目（catalog 渲染 / provider install 选择的最小可消费形状）。
+ */
 export interface ModelCatalogEntry {
+  /** 模型 ID */
   id: string;
+  /** 所属 seller ID */
   sellerId: string;
+  /** seller 名称（可选） */
   sellerName?: string;
+  /** seller 公网 URL（去尾 `/`） */
   sellerUrl: string;
+  /** seller 支持的协议 */
   supportedProtocols: string[];
+  /** seller 支持的支付方式 */
   paymentMethods: string[];
+  /** 输入价格 USD micros/1M */
   inputPriceMicrosPer1m?: number;
+  /** 输出价格 USD micros/1M */
   outputPriceMicrosPer1m?: number;
 }
 
+/**
+ * seller 目录条目（聚合 seller 元信息 + manifest 拉取结果）。
+ * 用于 `tb doctor` 和 CLI 表格展示。
+ */
 export interface SellerCatalogEntry {
+  /** seller ID */
   id: string;
+  /** 人类可读名称 */
   name?: string;
+  /** seller 公网 URL（去尾 `/`） */
   url: string;
+  /** 当前状态（`active` / `error` / `manifest_unavailable`） */
   status: string;
+  /** manifest 报告的 sellerId（可能与 id 不同，跨 namespace 时有用） */
   manifestSellerId?: string;
+  /** 折扣系数（来自 manifest.selection） */
   discountRatio?: number;
+  /** 模型数（来自 manifest） */
   modelCount?: number;
+  /** seller 支持的协议（manifest > registry fallback） */
   supportedProtocols?: string[];
+  /** seller 支持的支付方式（manifest > registry fallback） */
   paymentMethods?: string[];
+  /** manifest 拉取失败时的错误消息 */
   errorMessage?: string;
 }
 
+/**
+ * `discoverSellerBackedModels` 的返回结果。
+ * 包含聚合后的 `models[]` 和 `sellers[]`，供 provider install / catalog 渲染消费。
+ */
 export interface SellerCatalogResult {
+  /** 拉取的 registry URL（去尾 `/`） */
   registryUrl: string;
+  /** registry schema 版本 */
   version: number;
+  /** 默认 seller ID（来自 registry） */
   defaultSeller?: string;
+  /** 模型目录条目列表（去重后） */
   models: ModelCatalogEntry[];
+  /** seller 元信息列表（拉取 manifest 后的快照） */
   sellers: SellerCatalogEntry[];
 }
 
-export type SellerRoutingMode = "auto" | "fixed";
-
-export interface SellerRoutingPreference {
-  mode: SellerRoutingMode;
-  sellerId?: string;
-}
-
+/**
+ * 去掉 seller URL 尾部的 `/`，避免路径拼接时出现 `//v1/messages`。
+ *
+ * @param seller registry seller
+ * @returns 规范化后的 URL
+ */
 export function normalizeSellerUrl(seller: RegistrySeller): string {
   return seller.url.replace(/\/+$/, "");
 }
 
+/**
+ * 解析 seller 实际支持的协议列表。
+ * 优先级：manifest.camelCase > manifest.snake_case > registry fallback。
+ * 包含 `anthropic_messages` 时内部 alias 到 `messages`（更短、内部统一用简称）。
+ *
+ * @param manifest seller 的 `/manifest` 响应
+ * @param seller 兜底用的 registry seller
+ * @returns 归一化后的协议列表
+ */
 export function manifestProtocols(manifest: SellerManifest, seller: RegistrySeller): string[] {
   const protocols = manifest.supportedProtocols || manifest.supported_protocols || seller.supportedProtocols || [];
   return protocols.includes("anthropic_messages") && !protocols.includes("messages")
@@ -98,10 +185,24 @@ export function manifestProtocols(manifest: SellerManifest, seller: RegistrySell
     : protocols;
 }
 
+/**
+ * 解析 seller 支持的支付方式。
+ * 优先级：manifest.camelCase > manifest.snake_case > registry fallback。
+ *
+ * @param manifest seller 的 `/manifest` 响应
+ * @param seller 兜底用的 registry seller
+ * @returns 支付方式列表
+ */
 export function manifestPaymentMethods(manifest: SellerManifest, seller: RegistrySeller): string[] {
   return manifest.paymentMethods || manifest.payment_methods || seller.paymentMethods || [];
 }
 
+/**
+ * 从 manifest 抽取所有模型 ID，过滤非字符串与空串、trim 空白。
+ *
+ * @param manifest seller 的 `/manifest` 响应
+ * @returns 清理后的模型 ID 列表（保序）
+ */
 export function manifestModelIds(manifest: SellerManifest): string[] {
   return (manifest.models || [])
     .map((model) => model.id)
@@ -119,11 +220,8 @@ function manifestModels(manifest: SellerManifest): ManifestModelRecord[] {
 }
 
 /**
- * v1.2 §18.9: thrown when the bootstrap's `/registry/sellers` endpoint
- * returns HTTP 413 with the `X-TokenBuddy-Registry-Too-Large: 1` header.
- * The daemon catches this in `TokenbuddyDaemon.fetchRegistry` and falls
- * back to the last-known snapshot so the buyer stays routable while the
- * operator shrinks the registry below the 1MB cap.
+ * v1.2 §18.9：bootstrap 的 `/registry/sellers` 返回 413 + `X-TokenBuddy-Registry-Too-Large: 1` 时抛出的错误。
+ * daemon 在 `TokenbuddyDaemon.fetchRegistry` 捕获并回退到上次成功快照，保证 buyer 仍可路由。
  */
 export class RegistryTooLargeError extends Error {
   readonly status: number;
@@ -140,6 +238,16 @@ export class RegistryTooLargeError extends Error {
   }
 }
 
+/**
+ * 拉取 `/registry/sellers` 响应。
+ * - HTTP 413：抛 `RegistryTooLargeError`（带 `sizeBytes` / `sellerCount` / `maxBytes` 元信息），让 daemon 决定是否回退快照。
+ * - 其它非 2xx：抛通用 Error。
+ * - 2xx 但缺 `sellers` 数组：抛 Error。
+ *
+ * @param registryUrl wallet-bootstrap 的 `/registry/sellers` 完整 URL
+ * @returns 解析后的注册表文档
+ * @throws RegistryTooLargeError / Error
+ */
 export async function fetchSellerRegistry(registryUrl: string): Promise<SellerRegistryDocument> {
   const response = await fetch(registryUrl);
   if (response.status === 413) {
@@ -170,6 +278,13 @@ export async function fetchSellerRegistry(registryUrl: string): Promise<SellerRe
   return data;
 }
 
+/**
+ * 拉取单个 seller 的 `/manifest` 响应。
+ *
+ * @param seller registry seller
+ * @returns 解析后的 manifest
+ * @throws Error 非 2xx
+ */
 export async function fetchSellerManifest(seller: RegistrySeller): Promise<SellerManifest> {
   const response = await fetch(`${normalizeSellerUrl(seller)}/manifest`);
   if (!response.ok) {
@@ -178,6 +293,16 @@ export async function fetchSellerManifest(seller: RegistrySeller): Promise<Selle
   return await response.json() as SellerManifest;
 }
 
+/**
+ * 端到端发现 seller-backed 模型目录：
+ * 1. 拉取 `/registry/sellers`。
+ * 2. 并发拉取每个 seller 的 `/manifest`（失败转成 `errorMessage` 字段，不阻断整体）。
+ * 3. 合并 model 列表、按 `(modelId, sellerId)` 去重。
+ * 4. 输出 `SellerCatalogResult`（含聚合的 `models[]` 与 `sellers[]`）。
+ *
+ * @param registryUrl wallet-bootstrap 注册表 URL
+ * @returns 聚合后的目录
+ */
 export async function discoverSellerBackedModels(registryUrl: string): Promise<SellerCatalogResult> {
   const registry = await fetchSellerRegistry(registryUrl);
   const sellerResults = await Promise.all(registry.sellers.map(async (seller) => {
@@ -237,6 +362,13 @@ export async function discoverSellerBackedModels(registryUrl: string): Promise<S
   };
 }
 
+/**
+ * 按协议过滤 catalog 条目。
+ *
+ * @param models 目录条目
+ * @param protocol 目标协议
+ * @returns 仅包含该协议的条目
+ */
 export function filterCatalogByProtocol(
   models: ModelCatalogEntry[],
   protocol: ProtocolPreference
@@ -244,6 +376,14 @@ export function filterCatalogByProtocol(
   return models.filter((entry) => entry.supportedProtocols.includes(protocol));
 }
 
+/**
+ * 按 seller ID 过滤 catalog 条目。
+ * `sellerId` 缺省时返回原列表。
+ *
+ * @param models 目录条目
+ * @param sellerId 目标 seller ID
+ * @returns 仅包含该 seller 的条目
+ */
 export function filterCatalogBySeller(
   models: ModelCatalogEntry[],
   sellerId: string | undefined
@@ -254,6 +394,12 @@ export function filterCatalogBySeller(
   return models.filter((entry) => entry.sellerId === sellerId);
 }
 
+/**
+ * 按 `(sellerId, modelId)` 去重 catalog 条目，保留首次出现的顺序。
+ *
+ * @param models 目录条目
+ * @returns 去重后的条目
+ */
 export function dedupeCatalogEntries(models: ModelCatalogEntry[]): ModelCatalogEntry[] {
   const seen = new Set<string>();
   const output: ModelCatalogEntry[] = [];

package/src/seller-metadata-cache.ts

@@ -0,0 +1,91 @@
+import type { RegistrySeller } from "./seller-catalog.js";
+import { fetchSellerManifest } from "./seller-catalog.js";
+import type { SellerRouteMetadata } from "./seller-route-planner.js";
+
+/**
+ * `SellerMetadataCache` 构造选项。
+ */
+export interface SellerMetadataCacheOptions {
+  /** 缓存条目有效期（毫秒），默认 10 分钟 */
+  ttlMs?: number;
+  /** 时间源，默认 `Date.now`；测试可注入受控时间 */
+  now?: () => number;
+}
+
+export const DEFAULT_SELLER_METADATA_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * seller 路由元数据缓存（`/manifest` 拉取结果）。
+ * 内部按 seller id 索引、按 TTL 过期；并发刷新合并到同一 `inFlight` Promise，避免重复打 seller。
+ */
+export class SellerMetadataCache {
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+  private readonly entries = new Map<string, SellerRouteMetadata>();
+  private readonly inFlight = new Map<string, Promise<void>>();
+
+  constructor(options: SellerMetadataCacheOptions = {}) {
+    this.ttlMs = options.ttlMs ?? DEFAULT_SELLER_METADATA_TTL_MS;
+    this.now = options.now ?? Date.now;
+  }
+
+  snapshot(): SellerRouteMetadata[] {
+    return Array.from(this.entries.values());
+  }
+
+  refreshIfStale(sellers: RegistrySeller[]): Promise<void> {
+    const refreshes = sellers
+      .filter((seller) => this.shouldRefresh(seller.id))
+      .map((seller) => this.refreshSeller(seller));
+    return Promise.all(refreshes).then(() => undefined);
+  }
+
+  private shouldRefresh(sellerId: string): boolean {
+    const existing = this.entries.get(sellerId);
+    if (!existing) {
+      return true;
+    }
+    return this.now() - (existing.lastRefreshAt ?? 0) >= this.ttlMs;
+  }
+
+  private refreshSeller(seller: RegistrySeller): Promise<void> {
+    const existing = this.inFlight.get(seller.id);
+    if (existing) {
+      return existing;
+    }
+    const refresh = this.fetchAndStore(seller).finally(() => {
+      this.inFlight.delete(seller.id);
+    });
+    this.inFlight.set(seller.id, refresh);
+    return refresh;
+  }
+
+  private async fetchAndStore(seller: RegistrySeller): Promise<void> {
+    const refreshedAt = this.now();
+    try {
+      const manifest = await fetchSellerManifest(seller);
+      this.entries.set(seller.id, {
+        sellerId: seller.id,
+        discountRatio: finiteNumber(manifest.selection?.discountRatio ?? manifest.selection?.discount_ratio),
+        manifestVersion: stringField(manifest.manifestVersion ?? manifest.manifest_version),
+        lastRefreshAt: refreshedAt,
+        source: "manifest_selection"
+      });
+    } catch (err) {
+      this.entries.set(seller.id, {
+        sellerId: seller.id,
+        lastRefreshAt: refreshedAt,
+        source: "manifest_selection",
+        errorMessage: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}

package/src/seller-pool.ts

@@ -6,8 +6,18 @@ import type { CreditTracker } from "./credit-tracker.js";
 
 const logger = createModuleLogger("tb-proxyd:seller-pool");
 
+/**
+ * seller 级熔断器状态。
+ * - `closed`：正常挑选
+ * - `open`：被踢出候选，等待 `openStateMs` 后降级到 `half_open`
+ * - `half_open`：放行一次试探，成功则回 `closed`
+ */
 export type CircuitState = "closed" | "half_open" | "open";
 
+/**
+ * 路由失败归一化后的错误分类。控制器据此决定切流 / 重试 / 计入 wasted。
+ * 与 `SellerPool.recordFailure` 的入参对齐。
+ */
 export type FailureKind =
   | "hard_4xx"           // 400/404/422 — the seller is wrong for this request
   | "auth_invalid"       // 401/403 token invalid
@@ -17,55 +27,116 @@ export type FailureKind =
   | "stream_aborted"     // upstream stream broken after first chunk
   | "no_compatible";     // pool had no candidates for the request
 
+/**
+ * 池里每个 seller 的运行时视图：registry 描述 + 熔断状态 + 健康画像。
+ * 由 `SellerPool.sync()` 从 prewarm cache 重建；写路径（recordSuccess/recordFailure）会原地更新。
+ */
 export interface PoolEntry {
+  /** seller 全局 ID */
   sellerId: string;
+  /** seller URL（去尾部斜杠） */
   url: string;
+  /** registry 原始描述（用于 planSellerRouteSet 等下游） */
   registrySeller: RegistrySeller;
+  /** 当前熔断状态 */
   circuit: CircuitState;
+  /** 连续失败次数（达到 `failureThreshold` 立即 open） */
   consecutiveFailures: number;
+  /** 滑动窗口内失败时间戳（毫秒），长度受 `windowMs` 约束 */
   recentFailures: number[];   // timestamps (ms) for sliding window
+  /** 最近一次成功的 unix 毫秒时间戳；0 表示尚无成功 */
   lastSuccessAt: number;
+  /** 最近一次失败的 unix 毫秒时间戳；0 表示尚无失败 */
   lastFailAt: number;
+  /** 最近一次被 probe 的 unix 毫秒时间戳（即 cache.warmedAt） */
   lastProbeAt: number;
   // Source-of-truth prewarm state; the pool keeps a copy so the hot path
   // can answer health questions without touching the cache map on every
   // request.
+  /** 综合健康分 0-100，热路径排序的主键 */
   healthScore: number;
+  /** 平均延迟（毫秒） */
   avgLatencyMs: number;
+  /** health probe 延迟（毫秒），可选 */
+  healthProbeLatencyMs?: number;
+  /** TTFT（毫秒），可选 */
+  ttftMs?: number;
+  /** 平均推理延迟（毫秒），可选 */
+  avgInferenceMs?: number;
+  /** 上游状态，可选 */
+  upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
+  /** 上游错误类名，可选 */
+  upstreamErrorClass?: string;
 }
 
+/**
+ * `SellerPool.pick()` 的入参：标识一次路由请求 + 可选的时间/数量约束。
+ */
 export interface PickOptions {
+  /** 目标模型 ID（已归一化或未归一化都可，pool 内部会归一化） */
   modelId: string;
+  /** 目标协议 */
   protocol: string;
+  /** 目标支付方式 */
   paymentMethod: string;
+  /** 最多返回几个候选，默认 4 */
   limit?: number;
+  /** 覆盖时钟（测试用） */
   now?: number;
 }
 
+/**
+ * `SellerPool.pick()` 的返回：候选列表 + 决策原因 + 底层 model index 解析结果。
+ * `reason` 用于日志和 doctor 区分"无缓存""有缓存但全 open""正常"等情况。
+ */
 export interface PickResult {
+  /** 已按 healthScore 排序的候选（不含 open 电路的 seller） */
   candidates: Array<{ entry: PoolEntry; registrySeller: RegistrySeller }>;
+  /** 决策原因，例：`prewarm_cache`、`prewarm_cache_empty`、`no_prewarm_candidates` */
   reason: string;
+  /** 底层 `ModelIndex.resolve()` 的结果（保留给上游做诊断） */
   resolved: ModelIndexResolution;
 }
 
+/**
+ * `SellerPool` 视角的 model-index 解析快照，与 `model-index.ts` 里的同名类型语义一致；
+ * 在 pick 路径上做轻量拷贝，避免循环依赖和暴露 `sellers` vs `candidates` 命名差异。
+ */
 export interface ModelIndexResolution {
+  /** 解析时使用的模型 ID（可能未归一化） */
   modelId: string;
+  /** 索引里是否至少有一个 seller 命中 */
   matched: boolean;
+  /** 命中的 seller 列表（按 default + 声明顺序） */
   candidates: RegistrySeller[];
+  /** 当前索引里 `models` 字段缺失的 seller 数（诊断用） */
   missingModelsFlag: number;
 }
 
+/**
+ * 构造 `SellerPool` 所需的依赖与可调参数。默认值见 `DEFAULTS`：
+ * 失败 3 次 open、滑动窗口 60s、失败率阈值 0.5、open 态 30s。
+ */
 export interface SellerPoolOptions {
+  /** 共享的 model index */
   modelIndex: ModelIndex;
+  /** 共享的 prewarm cache（pool 的真相源） */
   cache: PrewarmCache;
+  /** 共享的 credit tracker，wasted / auto-purchase 决策都依赖 */
   creditTracker: CreditTracker;
   // Circuit breaker thresholds (v1.2 §13).
+  /** 连续失败次数阈值，到达后立即 open，默认 3 */
   failureThreshold?: number;     // default 3
+  /** 滑动窗口长度（毫秒），默认 60000 */
   windowMs?: number;              // default 60_000 (1m sliding window)
+  /** 滑动窗口内失败率阈值（次/秒），默认 0.5 */
   windowFailureRate?: number;     // default 0.5
+  /** open 态保持时间（毫秒），过期后降级 half_open，默认 30000 */
   openStateMs?: number;           // default 30_000
+  /** 注入时钟（测试用），默认 `Date.now` */
   now?: () => number;
   // PoolEntry -> CircuitState transition hooks for tests.
+  /** 测试钩子：在 sync 后对 entry 列表做额外处理 */
   applyRegistry?: (entries: PoolEntry[], registry: RegistrySeller[]) => PoolEntry[];
 }
 
@@ -132,7 +203,12 @@ export class SellerPool {
           lastFailAt: candidate.lastFailAt || previous?.lastFailAt || 0,
           lastProbeAt: entry.warmedAt,
           healthScore: candidate.healthScore,
-          avgLatencyMs: candidate.avgLatencyMs
+          avgLatencyMs: candidate.avgLatencyMs,
+          healthProbeLatencyMs: candidate.healthProbeLatencyMs,
+          ttftMs: candidate.ttftMs,
+          avgInferenceMs: candidate.avgInferenceMs,
+          upstreamStatus: candidate.upstreamStatus,
+          upstreamErrorClass: candidate.upstreamErrorClass
         });
       }
     }