@tokenbuddy/tokenbuddy 1.0.34 → 1.0.36

package/src/daemon.ts

@@ -313,6 +313,10 @@ interface UsageSummary {
   completionTokens: number;
   cacheReadTokens: number;
   billedMicros: number;
+  imageCount?: number;
+  imageSize?: string;
+  imageQuality?: string;
+  imageOutputFormat?: string;
 }
 
 interface ProxyBodySummary {
@@ -365,6 +369,7 @@ interface SellerSettlementSummary {
 }
 
 interface BillingBreakdownSummary {
+  billingUnit?: "tokens" | "images";
   inputPriceMicrosPer1m: number;
   outputPriceMicrosPer1m: number;
   cacheReadPriceMicrosPer1m: number;
@@ -374,6 +379,13 @@ interface BillingBreakdownSummary {
   originalUsdMicros: number;
   billingMultiplier: number;
   serviceTier?: string;
+  imageCount?: number;
+  imageSize?: string;
+  imageQuality?: string;
+  imageOutputFormat?: string;
+  imageOutputTokens?: number;
+  imageOutputCostMicros?: number;
+  imageCostMicrosPerImage?: number;
 }
 
 interface SellerAttemptRequestContext {
@@ -424,6 +436,17 @@ function safeBillingServiceTier(value: unknown): string | undefined {
   return /^[A-Za-z0-9 _.-]+$/.test(trimmed) ? trimmed : undefined;
 }
 
+function safeBillingUnit(value: unknown): "tokens" | "images" | undefined {
+  return value === "tokens" || value === "images" ? value : undefined;
+}
+
+function safeShortDisplayString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > 80) return undefined;
+  return /^[A-Za-z0-9 _./:-]+$/.test(trimmed) ? trimmed : undefined;
+}
+
 function billingBreakdownSummary(value: unknown): BillingBreakdownSummary | undefined {
   const data = usageRecord(value);
   if (!data) return undefined;
@@ -448,6 +471,7 @@ function billingBreakdownSummary(value: unknown): BillingBreakdownSummary | unde
     return undefined;
   }
   return {
+    billingUnit: safeBillingUnit(data.billingUnit ?? data.billing_unit),
     inputPriceMicrosPer1m,
     outputPriceMicrosPer1m,
     cacheReadPriceMicrosPer1m,
@@ -456,10 +480,36 @@ function billingBreakdownSummary(value: unknown): BillingBreakdownSummary | unde
     cacheReadCostMicros,
     originalUsdMicros,
     billingMultiplier,
-    serviceTier: safeBillingServiceTier(data.serviceTier ?? data.service_tier)
+    serviceTier: safeBillingServiceTier(data.serviceTier ?? data.service_tier),
+    imageCount: nonNegativeIntegerField(data.imageCount ?? data.image_count),
+    imageSize: safeShortDisplayString(data.imageSize ?? data.image_size),
+    imageQuality: safeShortDisplayString(data.imageQuality ?? data.image_quality),
+    imageOutputFormat: safeShortDisplayString(data.imageOutputFormat ?? data.image_output_format),
+    imageOutputTokens: nonNegativeIntegerField(data.imageOutputTokens ?? data.image_output_tokens),
+    imageOutputCostMicros: nonNegativeIntegerField(data.imageOutputCostMicros ?? data.image_output_cost_micros),
+    imageCostMicrosPerImage: nonNegativeIntegerField(data.imageCostMicrosPerImage ?? data.image_cost_micros_per_image)
   };
 }
 
+function imageUsageMetadata(responseBody: Record<string, unknown> | undefined, requestBody: Record<string, unknown> | undefined): Partial<UsageSummary> {
+  const responseImages = Array.isArray(responseBody?.data) ? responseBody.data : undefined;
+  const firstImage = responseImages?.find((item) => item && typeof item === "object") as Record<string, unknown> | undefined;
+  const requestedCount = nonNegativeIntegerField(requestBody?.n);
+  return {
+    imageCount: responseImages ? responseImages.length : requestedCount && requestedCount > 0 ? requestedCount : undefined,
+    imageSize: safeShortDisplayString(responseBody?.size) ?? safeShortDisplayString(firstImage?.size) ?? safeShortDisplayString(requestBody?.size),
+    imageQuality: safeShortDisplayString(responseBody?.quality) ?? safeShortDisplayString(firstImage?.quality) ?? safeShortDisplayString(requestBody?.quality),
+    imageOutputFormat: safeShortDisplayString(responseBody?.output_format) ?? safeShortDisplayString(firstImage?.output_format) ?? safeShortDisplayString(requestBody?.output_format)
+  };
+}
+
+function imageCostMicrosPerImage(totalMicros: number | undefined, imageCount: number | undefined): number | undefined {
+  if (totalMicros === undefined || imageCount === undefined || imageCount <= 0) {
+    return undefined;
+  }
+  return Math.ceil(totalMicros / imageCount);
+}
+
 function purchasePaymentSummaryFromQuote(value: unknown): PurchasePaymentSummary {
   const quote = usageRecord(value);
   if (!quote) return {};
@@ -860,7 +910,16 @@ export class TokenbuddyDaemon {
     const bundledDir = this.bundledClawtipStaticDir();
     const rechargeSourcePath = bundledDir ? path.join(bundledDir, CLAWTIP_RECHARGE_QR_FILE) : undefined;
     if (rechargeSourcePath && fs.existsSync(rechargeSourcePath)) {
-      fs.copyFileSync(rechargeSourcePath, rechargeOutputPath);
+      fs.mkdirSync(path.dirname(rechargeOutputPath), { recursive: true });
+      try {
+        fs.copyFileSync(rechargeSourcePath, rechargeOutputPath);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+          throw err;
+        }
+        fs.mkdirSync(path.dirname(rechargeOutputPath), { recursive: true });
+        fs.copyFileSync(rechargeSourcePath, rechargeOutputPath);
+      }
     }
   }
 
@@ -1319,6 +1378,19 @@ export class TokenbuddyDaemon {
     });
   }
 
+  /**
+   * 将 AutoProviderConfig 转换为 BuyerSellerRoutingConfig。
+   *
+   * 映射规则：
+   * - `recommended` 模式 → `fullAuto`：使用全部 registry sellers，由评分器自动排序
+   * - `custom` 模式 → `fixedSet`：使用 `config.sellerIds` 白名单内的 sellers
+   *
+   * 注意：`config.modelIds` 不直接用于路由过滤，而是通过 `applyFocusSet()` 设置焦点集合，
+   * 影响 UI 推荐和初始化向导，但不限制实际路由决策。
+   *
+   * @param config Auto provider 配置
+   * @returns Seller 路由配置
+   */
   private applyAutoProviderRoutingConfig(config: AutoProviderConfig): BuyerSellerRoutingConfig {
     const routing: BuyerSellerRoutingConfig = config.range === "custom"
       ? {
@@ -1340,7 +1412,19 @@ export class TokenbuddyDaemon {
   }
 
   private autoProviderCanRoute(config: AutoProviderConfig): boolean {
-    return config.enabled && (config.range !== "custom" || config.sellerIds.length > 0);
+    if (!config.enabled) {
+      logger.warn("route.auto_provider.disabled", "auto provider is disabled in config");
+      return false;
+    }
+    if (config.range === "custom" && config.sellerIds.length === 0) {
+      logger.warn("route.auto_provider.custom_empty", "auto provider custom mode requires sellerIds", {
+        range: config.range,
+        modelIds: config.modelIds,
+        scorer: config.scorer
+      });
+      return false;
+    }
+    return true;
   }
 
   private providerModePayload(): Record<string, unknown> {
@@ -1627,6 +1711,9 @@ export class TokenbuddyDaemon {
     if (endpoint === "/v1/messages" || endpoint === "/messages") {
       return "messages";
     }
+    if (endpoint === "/v1/images/generations") {
+      return "images_generations";
+    }
     return undefined;
   }
 
@@ -1761,6 +1848,20 @@ export class TokenbuddyDaemon {
       planReason: reason,
       planSellerCount: providers.length
     }));
+
+    // Log manual provider routing decision for auditability
+    logger.info("route.manual.decision", "manual provider routing decision", {
+      policy: config.routing.policy,
+      selectedProviderId: providers[0].id,
+      selectedProviderName: providers[0].name,
+      totalCandidates: providers.length,
+      candidateProviderIds: providers.map((p) => p.id),
+      endpoint,
+      modelId,
+      protocol,
+      reason
+    });
+
     return {
       routes,
       paymentMethod: "provider_key",
@@ -1842,11 +1943,15 @@ export class TokenbuddyDaemon {
       selectionMode: this.selectionMode,
       sellerRoutingMode: routing.mode,
       sellerRoutingScorer: routing.scorer,
+      autoProviderRange: this.currentAutoProviderConfig().range,
+      autoProviderCustomSellerIds: this.currentAutoProviderConfig().range === "custom" ? this.currentAutoProviderConfig().sellerIds : undefined,
       routeSource: planned.source,
       routeSourceReason: planned.sourceReason,
       routeReason: planned.reason,
       candidateDiagnostics: planned.diagnostics,
       sellerCount: planned.routes.length,
+      selectedSellerId: planned.routes[0]?.seller.id,
+      selectedSellerName: planned.routes[0]?.seller.name,
       sellers: planned.routes.map((route) => route.seller.id)
     });
 
@@ -2251,7 +2356,7 @@ export class TokenbuddyDaemon {
     };
   }
 
-  private readUsage(bodyText: string): UsageSummary {
+  private readUsage(bodyText: string, endpoint?: string, requestBody?: unknown): UsageSummary {
     const fallback: UsageSummary = {
       promptTokens: 0,
       completionTokens: 0,
@@ -2273,11 +2378,15 @@ export class TokenbuddyDaemon {
         ?? nonNegativeIntegerField(usage?.cache_read_input_tokens)
         ?? nonNegativeIntegerField(usage?.cache_read_tokens)
         ?? 0;
+      const imageMetadata = endpoint === "/v1/images/generations"
+        ? imageUsageMetadata(data, usageRecord(requestBody))
+        : {};
       return {
         promptTokens,
         completionTokens,
         cacheReadTokens,
-        billedMicros: (promptTokens + completionTokens) * 4
+        billedMicros: (promptTokens + completionTokens) * 4,
+        ...imageMetadata
       };
     } catch {
       return fallback;
@@ -2349,6 +2458,14 @@ export class TokenbuddyDaemon {
       originalUsdMicros: billingBreakdown?.originalUsdMicros,
       billingMultiplier: billingBreakdown?.billingMultiplier,
       serviceTier: billingBreakdown?.serviceTier,
+      billingUnit: billingBreakdown?.billingUnit ?? (endpoint === "/v1/images/generations" ? "images" : "tokens"),
+      imageCount: billingBreakdown?.imageCount ?? usage.imageCount,
+      imageSize: billingBreakdown?.imageSize ?? usage.imageSize,
+      imageQuality: billingBreakdown?.imageQuality ?? usage.imageQuality,
+      imageOutputFormat: billingBreakdown?.imageOutputFormat ?? usage.imageOutputFormat,
+      imageOutputTokens: billingBreakdown?.imageOutputTokens ?? (endpoint === "/v1/images/generations" ? usage.completionTokens : undefined),
+      imageOutputCostMicros: billingBreakdown?.imageOutputCostMicros ?? (endpoint === "/v1/images/generations" ? billingBreakdown?.outputCostMicros : undefined),
+      imageCostMicrosPerImage: billingBreakdown?.imageCostMicrosPerImage ?? imageCostMicrosPerImage(settledMicros ?? usage.billedMicros, billingBreakdown?.imageCount ?? usage.imageCount),
       balanceSnapshotMicros: settlement?.remainingCreditMicros,
       balanceSource: settlement ? "seller_authoritative" : "estimated",
       prompt,
@@ -2371,6 +2488,8 @@ export class TokenbuddyDaemon {
       settledMicros,
       settledUsdMicros: settlement?.settledUsdMicros,
       billedMicros: settledMicros ?? usage.billedMicros,
+      billingUnit: billingBreakdown?.billingUnit ?? (endpoint === "/v1/images/generations" ? "images" : "tokens"),
+      imageCount: billingBreakdown?.imageCount ?? usage.imageCount,
       promptTokens: usage.promptTokens,
       completionTokens: usage.completionTokens,
       cacheReadTokens: usage.cacheReadTokens,
@@ -3192,6 +3311,7 @@ export class TokenbuddyDaemon {
         billedMicros: Math.max(1, bytes),
         estimatedMicros: Math.max(1, bytes),
         priceVersion: `local-provider:${provider.id}`,
+        billingUnit: endpoint === "/v1/images/generations" ? "images" : "tokens",
         balanceSource: "self_funded_provider",
         prompt: this.inferPromptForHash(reqBody),
         ttftMs,
@@ -3208,7 +3328,7 @@ export class TokenbuddyDaemon {
     const responseBody = await response.text();
     markFirstByte();
     res.send(responseBody);
-    const usage = this.readUsage(responseBody);
+    const usage = this.readUsage(responseBody, endpoint, reqBody);
     const durationMs = Date.now() - startedAt;
     const ttftMs = Date.now() - attemptStartedAt;
     const completionTokens = usage.completionTokens;
@@ -3232,6 +3352,13 @@ export class TokenbuddyDaemon {
       billedMicros: usage.billedMicros,
       estimatedMicros: usage.billedMicros,
       priceVersion: `local-provider:${provider.id}`,
+      billingUnit: endpoint === "/v1/images/generations" ? "images" : "tokens",
+      imageCount: usage.imageCount,
+      imageSize: usage.imageSize,
+      imageQuality: usage.imageQuality,
+      imageOutputFormat: usage.imageOutputFormat,
+      imageOutputTokens: endpoint === "/v1/images/generations" ? usage.completionTokens : undefined,
+      imageCostMicrosPerImage: imageCostMicrosPerImage(usage.billedMicros, usage.imageCount),
       balanceSource: "self_funded_provider",
       prompt: this.inferPromptForHash(reqBody),
       response: responseBody,
@@ -3644,7 +3771,7 @@ export class TokenbuddyDaemon {
             lease.refresh();
             markFirstByte();
             res.send(responseBody);
-            const usage = this.readUsage(responseBody);
+            const usage = this.readUsage(responseBody, endpoint, body);
             void this.refreshSellerRuntimeMetrics(route, requestId);
             this.recordReconciledInference(
               route,
@@ -4857,7 +4984,7 @@ export class TokenbuddyDaemon {
       }
     });
 
-    for (const endpoint of ["/v1/chat/completions", "/v1/responses", "/v1/messages", "/messages"]) {
+    for (const endpoint of ["/v1/chat/completions", "/v1/responses", "/v1/messages", "/messages", "/v1/images/generations"]) {
       proxyApp.post(endpoint, async (req: Request, res: Response) => {
         await this.forwardProxyRequest(endpoint, req, res);
       });
@@ -5014,7 +5141,7 @@ export class TokenbuddyDaemon {
   }
 
   private resolvePrewarmProtocol(modelId: string, paymentMethod = "clawtip"): string | undefined {
-    for (const protocol of ["chat_completions", "messages", "responses"]) {
+    for (const protocol of ["chat_completions", "messages", "responses", "images_generations"]) {
       if (this.modelIndex.sellersFor(modelId, { protocol, paymentMethod }).length > 0) {
         return protocol;
       }

package/src/provider-routing-config.ts

@@ -7,7 +7,7 @@ export const MANUAL_PROVIDER_OBSERVATIONS_CONFIG_KEY = "manual-provider-observat
 
 export type ProviderMode = "manual" | "auto";
 export type ManualProviderKind = "openai-compatible";
-export type ProviderProtocol = "chat_completions" | "responses" | "messages";
+export type ProviderProtocol = "chat_completions" | "responses" | "messages" | "images_generations";
 export type AutoProviderRange = "recommended" | "custom";
 export type ManualProviderRoutingPolicy = "fallback" | "locked";
 
@@ -85,7 +85,7 @@ export interface ManualProviderObservationsConfig {
   updatedAt: string;
 }
 
-const VALID_PROTOCOLS = new Set<ProviderProtocol>(["chat_completions", "responses", "messages"]);
+const VALID_PROTOCOLS = new Set<ProviderProtocol>(["chat_completions", "responses", "messages", "images_generations"]);
 const VALID_SCORERS = new Set<SellerRoutingScorer>(["balanced", "speed", "discount"]);
 
 export function defaultProviderModeConfig(now = new Date().toISOString()): ProviderModeConfig {

package/src/seller-catalog.ts

@@ -11,7 +11,7 @@ const logger = createModuleLogger("tb-proxyd");
 /**
  * buyer 端协议偏好（用于按协议过滤 catalog）。`messages` 是 anthropic 协议的简称。
  */
-export type ProtocolPreference = "chat_completions" | "responses" | "messages";
+export type ProtocolPreference = "chat_completions" | "responses" | "messages" | "images_generations";
 
 /**
  * wallet-bootstrap `/registry/sellers` 里的 seller 描述。

package/src/seller-routing-strategy.ts

@@ -221,6 +221,21 @@ function compareCandidates(a: SortableCandidate, b: SortableCandidate, scorer: S
  * 计算单个 candidate 在指定 scorer 下的完整打分拆解（含各维度分量和缺失项）。
  * 不会修改输入 candidate，常用于 doctor 面板和调试日志。
  *
+ * 权重设计理由：
+ * - **Speed 评分器**：TTFT 65% + Tok/s 25% + Health 10%
+ *   - TTFT 占主导是因为首 token 延迟直接影响用户感知的响应速度
+ *   - Tok/s 次要，因为大多数场景下吞吐差异不如延迟显著
+ *   - Health 最低，只作为平局时的兜底
+ *
+ * - **Discount 评分器**：折扣 100%
+ *   - 纯成本优先，忽略性能指标
+ *   - 平局时按健康分和注册顺序兜底
+ *
+ * - **Balanced 评分器**：Health 35% + TTFT 20% + Tok/s 20% + Discount 25%
+ *   - Health 占比最高是为了避免选择不稳定的 seller
+ *   - 速度（TTFT + Tok/s）合计 40%，与折扣 25% 形成平衡
+ *   - 这是默认评分器，适合大多数生产场景
+ *
  * @param candidate 待打分的候选
  * @param scorer 评分器：`speed` / `discount` / `balanced`
  * @returns 打分拆解
@@ -266,6 +281,19 @@ export function scoreCandidateBreakdown(candidate: RoutingCandidate, scorer: Sel
   };
 }
 
+/**
+ * 将延迟（毫秒）转换为 0-100 分数。
+ * 公式：`100 - latency_ms / 10`
+ *
+ * 设计理由：
+ * - 0ms → 100分，1000ms → 0分（线性递减）
+ * - 除以 10 的比例来自经验：100ms 是"优秀"延迟，1000ms 是"不可接受"延迟
+ * - 线性公式的局限：100ms vs 200ms 的差异被等同于 900ms vs 1000ms
+ *   实际用户体验可能不是线性的，未来可考虑对数或分段函数
+ *
+ * @param latencyMs 延迟（毫秒），undefined 或非有限值返回 0 分
+ * @returns 0-100 分数
+ */
 function latencyScore(latencyMs: number | undefined): number {
   if (!Number.isFinite(latencyMs)) {
     return 0;
@@ -273,6 +301,19 @@ function latencyScore(latencyMs: number | undefined): number {
   return Math.max(0, 100 - Math.max(0, latencyMs as number) / 10);
 }
 
+/**
+ * 将输出吞吐（tokens/s）转换为 0-100 分数。
+ * 公式：直接取值并限制在 0-100 范围内
+ *
+ * 设计理由：
+ * - 假设大多数 seller 的吞吐在 0-100 tok/s 范围内
+ * - 100 tok/s 及以上都得满分（上界问题）
+ * - 这种线性映射的局限：无法区分 100 tok/s 和 200 tok/s 的差异
+ *   未来可考虑对数缩放，例如 `100 * log(1 + value) / log(101)`
+ *
+ * @param value 吞吐（tokens/s），undefined 或非有限值返回 0 分
+ * @returns 0-100 分数
+ */
 function tokensPerSecondScore(value: number | undefined): number {
   if (!Number.isFinite(value)) {
     return 0;