@tokenbuddy/tokenbuddy 1.0.11 → 1.0.13

package/src/provider-install.ts

@@ -7,7 +7,6 @@ import {
 } from "./buyer-store.js";
 import {
   ProtocolPreference,
-  SellerRoutingPreference,
 } from "./seller-catalog.js";
 
 export const PROXY_ACCESS_TOKEN_PLACEHOLDER = "TOKENBUDDY_PROXY";
@@ -16,7 +15,6 @@ const CLAUDE_ONE_M_MARKER = "[1M]";
 const CLAUDE_CLIENT_HAIKU_MODEL = "claude-haiku-4-5";
 const CLAUDE_CLIENT_SONNET_MODEL = "claude-sonnet-4-6";
 const CLAUDE_CLIENT_OPUS_MODEL = "claude-opus-4-7";
-const ROUTING_CONFIG_KEY = "routing";
 
 export const SUPPORTED_PROVIDER_IDS = [
   "codex",
@@ -30,23 +28,41 @@ export const SUPPORTED_PROVIDER_IDS = [
 export type ProviderId = typeof SUPPORTED_PROVIDER_IDS[number];
 export type ModelSelectionKind = "single-model" | "claude-role-mapping";
 
+/**
+ * provider 探测选项。
+ */
 export interface ProviderDetectOptions {
+  /** 用户 home 目录，默认 `os.homedir()`；测试可注入临时目录 */
   home?: string;
 }
 
+/**
+ * 单模型 provider 的 runtime config（适用于 codex / opencode / hermes / openclaw 等）。
+ * `defaultModel` 是 buyer 端默认转发到的上游模型 ID。
+ */
 export interface SingleModelProviderRuntimeConfig {
   selectionKind: "single-model";
   protocolPreference?: ProtocolPreference;
   defaultModel: string;
-  sellerId?: string;
 }
 
+/**
+ * Claude Code role 绑定：把 buyer 端的 `haiku/sonnet/opus` 角色映射到具体上游模型。
+ * `declareOneM` 用于在 UI 上声明 1M context（仅展示用途，不参与计费）。
+ */
 export interface ClaudeRoleBinding {
+  /** 实际转发到 seller 的上游模型 ID */
   upstreamModel: string;
+  /** UI 展示名（可选） */
   displayName?: string;
+  /** 是否在配置里标注 1M context（Claude Code 1M marker） */
   declareOneM?: boolean;
 }
 
+/**
+ * Claude Code provider 的 model mapping 配置。
+ * 三个 role 都可选；缺失时回退到 `fallbackModel`。
+ */
 export interface ClaudeCodeModelMappingConfig {
   selectionKind: "claude-role-mapping";
   protocolPreference?: ProtocolPreference;
@@ -58,24 +74,40 @@ export interface ClaudeCodeModelMappingConfig {
   };
 }
 
+/**
+ * 任何 provider 的 runtime config 联合类型。
+ * 通过 `selectionKind` 字段做类型守卫。
+ */
 export type ProviderRuntimeConfig =
   | SingleModelProviderRuntimeConfig
   | ClaudeCodeModelMappingConfig;
 
+/**
+ * `tb init` 期间为每个 provider 收集的最终选择（按 provider id 索引）。
+ */
 export type ProviderSelections = Partial<Record<ProviderId, ProviderRuntimeConfig>>;
 
+/**
+ * `applyProviderInstall` / `previewProviderInstall` 的输入。
+ * 必填 `providers`（要安装的 provider ID 列表）和 `proxyUrl`（buyer 代理 URL）。
+ */
 export interface ProviderInstallOptions extends ProviderDetectOptions {
   providers: string[];
   proxyUrl: string;
   model?: string;
   providerSelections?: ProviderSelections;
-  sellerRouting?: SellerRoutingPreference;
 }
 
+/**
+ * `rollbackProviderInstall` 的输入。
+ */
 export interface ProviderRollbackOptions extends ProviderDetectOptions {
   providers: string[];
 }
 
+/**
+ * provider 探测结果（供 `tb doctor` / install 流程使用）。
+ */
 export interface ProviderCandidate {
   id: ProviderId;
   name: string;
@@ -89,6 +121,9 @@ export interface ProviderCandidate {
   reason: string;
 }
 
+/**
+ * provider 安装时产生的单文件变更（preview 阶段用）。
+ */
 export interface ProviderFileChange {
   providerId: ProviderId;
   path: string;
@@ -98,12 +133,18 @@ export interface ProviderFileChange {
   content: string;
 }
 
+/**
+ * `applyProviderInstall` 的结果（每文件一行）。
+ */
 export interface ProviderApplyResult {
   providerId: ProviderId;
   path: string;
   action: "created" | "updated";
 }
 
+/**
+ * `rollbackProviderInstall` 的结果（每文件一行）。
+ */
 export interface ProviderRollbackResult {
   providerId: ProviderId;
   path: string;
@@ -116,6 +157,7 @@ interface ProviderDefinition {
   configPath(home: string): string;
   commandName?: string;
   observedPaths?(home: string): string[];
+  isConfigured?(filePath: string, home: string): boolean;
   changes(home: string, proxyUrl: string, config: ProviderRuntimeConfig): ProviderFileChange[];
   modelSelectionKind: ModelSelectionKind;
   protocolPreference?: ProtocolPreference;
@@ -167,6 +209,16 @@ function readJsonObject(filePath: string): Record<string, unknown> {
   }
 }
 
+function readObjectField(value: unknown, key: string): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const field = (value as Record<string, unknown>)[key];
+  return field && typeof field === "object" && !Array.isArray(field)
+    ? field as Record<string, unknown>
+    : undefined;
+}
+
 function jsonContent(value: unknown): string {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -243,13 +295,11 @@ function makeChange(providerId: ProviderId, filePath: string, summary: string, c
 function makeSingleModelRuntimeConfig(
   provider: ProviderDefinition,
   model: string,
-  sellerId?: string,
 ): SingleModelProviderRuntimeConfig {
   return {
     selectionKind: "single-model",
     protocolPreference: provider.protocolPreference,
     defaultModel: model,
-    sellerId,
   };
 }
 
@@ -275,11 +325,7 @@ function resolveProviderRuntimeConfig(
   if (!model) {
     throw new Error(`model is required for provider ${provider.id}`);
   }
-  return makeSingleModelRuntimeConfig(
-    provider,
-    model,
-    options.sellerRouting?.mode === "fixed" ? options.sellerRouting.sellerId : undefined,
-  );
+  return makeSingleModelRuntimeConfig(provider, model);
 }
 
 function codexConfig(home: string, proxyUrl: string, config: ProviderRuntimeConfig): ProviderFileChange[] {
@@ -469,12 +515,7 @@ function opencodeConfig(home: string, proxyUrl: string, config: ProviderRuntimeC
     : {};
   providers.tokenbuddy = {
     name: "TokenBuddy",
-    // v1.0.10 起默认走 OpenAI Responses API 协议（/v1/responses）。
-    // 验证：之前默认 @ai-sdk/openai（chat completions）也能 work，但 Responses API
-    // 才是上游（code.shoestravel.xin 等）原生支持的 SSE 事件链，type 字段更标准
-    // （response.created / response.output_text.delta / response.completed），
-    // 让 buyer 端 SseUsageExtractor 能稳定 parse usage 字段。
-    npm: "@ai-sdk/openai-responses",
+    npm: "@ai-sdk/openai-compatible",
     options: {
       apiKey: PROXY_ACCESS_TOKEN_PLACEHOLDER,
       baseURL: openAiBaseUrl(proxyUrl),
@@ -494,6 +535,25 @@ function opencodeConfig(home: string, proxyUrl: string, config: ProviderRuntimeC
   return [makeChange("opencode", configPath, "configure OpenCode provider for TokenBuddy proxy", jsonContent(current))];
 }
 
+function isOpencodeTokenBuddyConfigured(filePath: string): boolean {
+  const current = readJsonObject(filePath);
+  const tokenbuddy = readObjectField(readObjectField(current, "provider"), "tokenbuddy");
+  const options = readObjectField(tokenbuddy, "options");
+  if (!tokenbuddy || !options) {
+    return false;
+  }
+
+  return tokenbuddy.npm === "@ai-sdk/openai-compatible" &&
+    options.apiKey === PROXY_ACCESS_TOKEN_PLACEHOLDER &&
+    typeof options.baseURL === "string" &&
+    options.baseURL.includes("127.0.0.1") &&
+    options.baseURL.endsWith("/v1") &&
+    typeof current.model === "string" &&
+    current.model.startsWith("tokenbuddy/") &&
+    typeof current.small_model === "string" &&
+    current.small_model.startsWith("tokenbuddy/");
+}
+
 function hermesConfig(home: string, proxyUrl: string, config: ProviderRuntimeConfig): ProviderFileChange[] {
   const model = pickConfiguredModel(config);
   const configPath = path.join(home, ".hermes", "settings.json");
@@ -555,9 +615,10 @@ const PROVIDERS: ProviderDefinition[] = [
     name: "OpenCode",
     commandName: "opencode",
     configPath: (home) => path.join(home, ".config", "opencode", "opencode.json"),
+    isConfigured: isOpencodeTokenBuddyConfigured,
     changes: opencodeConfig,
     modelSelectionKind: "single-model",
-    protocolPreference: "responses",
+    protocolPreference: "chat_completions",
   },
   {
     id: "hermes",
@@ -582,14 +643,22 @@ function getProviderDefinition(providerId: ProviderId): ProviderDefinition {
   return provider;
 }
 
+/**
+ * 探测所有 SUPPORTED_PROVIDER_IDS：检查可执行文件、配置文件、原生 hints 目录。
+ * 状态机：`configured`（已存在配置且被识别） / `installed`（可执行/配置存在但未配置） / `missing`（都未找到）。
+ *
+ * @param options 探测选项
+ * @returns 探测结果列表
+ */
 export function detectProviders(options: ProviderDetectOptions = {}): ProviderCandidate[] {
   const home = resolveHome(options.home);
   return PROVIDERS.map((provider) => {
     const configPath = provider.configPath(home);
-    const configured = fs.existsSync(configPath);
+    const configExists = fs.existsSync(configPath);
+    const configured = configExists && (provider.isConfigured?.(configPath, home) ?? true);
     const executablePath = provider.commandName ? resolveExecutable(provider.commandName) : undefined;
     const observedPaths = provider.observedPaths?.(home).filter((entry) => fs.existsSync(entry)) || [];
-    const installed = Boolean(executablePath) || observedPaths.length > 0;
+    const installed = Boolean(executablePath) || observedPaths.length > 0 || configExists;
     const status: ProviderCandidate["status"] = configured
       ? "configured"
       : installed
@@ -624,14 +693,33 @@ export function detectProviders(options: ProviderDetectOptions = {}): ProviderCa
   });
 }
 
+/**
+ * 返回 provider 默认的协议偏好（未声明则返回 `undefined`，由运行时探测）。
+ *
+ * @param providerId provider ID
+ * @returns 协议偏好
+ */
 export function getProviderProtocolPreference(providerId: ProviderId): ProtocolPreference | undefined {
   return getProviderDefinition(providerId).protocolPreference;
 }
 
+/**
+ * 返回 provider 的 model selection kind（决定 init 走 single-model 还是 claude-role-mapping 流程）。
+ *
+ * @param providerId provider ID
+ * @returns selection kind
+ */
 export function getProviderModelSelectionKind(providerId: ProviderId): ModelSelectionKind {
   return getProviderDefinition(providerId).modelSelectionKind;
 }
 
+/**
+ * 预览 provider 安装会产生的文件变更（不实际写盘）。
+ * 给 `tb init` 在用户确认前展示"将要改哪些文件 / 改什么内容"。
+ *
+ * @param options 安装选项
+ * @returns 计划中的文件变更列表
+ */
 export function previewProviderInstall(options: ProviderInstallOptions): ProviderFileChange[] {
   const home = resolveHome(options.home);
   const providerIds = assertProviderIds(options.providers);
@@ -645,6 +733,14 @@ export function previewProviderInstall(options: ProviderInstallOptions): Provide
   });
 }
 
+/**
+ * 实际写盘 provider 配置。
+ * 同时把每个 provider 的原始文件快照写入 `store`（用于 `tb rollback`）。
+ *
+ * @param options 安装选项
+ * @param store buyer store（用于快照 + runtime config 持久化）
+ * @returns 实际写盘结果列表
+ */
 export function applyProviderInstall(options: ProviderInstallOptions, store: BuyerStore): ProviderApplyResult[] {
   const providerIds = assertProviderIds(options.providers);
   const changes = previewProviderInstall(options);
@@ -671,10 +767,6 @@ export function applyProviderInstall(options: ProviderInstallOptions, store: Buy
     store.saveProviderRuntimeConfig(providerId, runtimeConfig);
   }
 
-  if (options.sellerRouting) {
-    store.saveDaemonRuntimeConfig(ROUTING_CONFIG_KEY, options.sellerRouting);
-  }
-
   const applied: ProviderApplyResult[] = [];
   for (const change of changes) {
     const dir = path.dirname(change.path);
@@ -691,6 +783,15 @@ export function applyProviderInstall(options: ProviderInstallOptions, store: Buy
   return applied;
 }
 
+/**
+ * 回滚 provider 安装。
+ * 从 `store` 读取安装前的快照，恢复原文件（如果快照里有原始内容）。
+ * 没有快照的 provider 标记为 `missing_snapshot`。
+ *
+ * @param options 回滚选项
+ * @param store buyer store
+ * @returns 回滚结果列表
+ */
 export function rollbackProviderInstall(options: ProviderRollbackOptions, store: BuyerStore): ProviderRollbackResult[] {
   const providerIds = assertProviderIds(options.providers);
   const results: ProviderRollbackResult[] = [];
@@ -716,6 +817,5 @@ export function rollbackProviderInstall(options: ProviderRollbackOptions, store:
     store.removeProviderInstallSnapshot(providerId);
     store.removeProviderRuntimeConfig(providerId);
   }
-  store.removeDaemonRuntimeConfig(ROUTING_CONFIG_KEY);
   return results;
 }

package/src/route-failover.ts

@@ -5,42 +5,90 @@ import type { CreditTracker } from "./credit-tracker.js";
 
 const logger = createModuleLogger("tb-proxyd:route-failover");
 
+/**
+ * 路由失败后的下一步动作（控制器收到 `FailoverDecision` 后据此执行）。
+ * - `retry_same_seller`：在同 seller 上做 jittered backoff 重试
+ * - `failover_next`：从池里取出下一个候选 seller
+ * - `fail_fast`：立刻向上抛错，不再尝试其它候选
+ * - `abort`：候选已耗尽，放弃本轮
+ */
 export type RouteAction = "retry_same_seller" | "failover_next" | "fail_fast" | "abort";
 
+/**
+ * 一次失败后 `RouteFailover.decide()` 返回的结构化决策。
+ * 控制器根据 `action` 决定是否重试/切换/终止，并把 `wastedCreditMicros`
+ * 上报到 doctor 面板。
+ */
 export interface FailoverDecision {
+  /** 控制器要执行的下一步动作 */
   action: RouteAction;
+  /** 仅当 `action === "retry_same_seller"` 时使用，表示 backoff 后多久重试（毫秒） */
   retryDelayMs?: number;
+  /** 决策理由，结构化但可读，供日志 / doctor 渲染 */
   reason: string;
+  /** 本次失败后被废弃的 credit（USD micros），供 doctor 统计 */
   wastedCreditMicros?: number;
+  /** 失败发生在 fresh-purchase 窗口内（刚买不到 N 秒），用于触发软重试保护 */
   freshPurchase: boolean;
+  /** 在切走这个 seller 之前已经尝试的次数（含本次失败） */
   retryAttemptsBeforeFailover: number;
+  /** 当次会话是否已超出 auto-purchase 预算；true 时不再触发新一轮 buy */
   budgetExceeded: boolean;
 }
 
+/**
+ * 一次路由选择的最小可执行单元：池里的某个 entry + 关联的 registry 描述。
+ * `routeIndex` 仅用于日志排版，控制器自己维护尝试序号。
+ */
 export interface RouteCandidate {
+  /** 在本批候选中的序号（0-based），仅作日志可读性使用 */
   routeIndex: number;
+  /** 池里的 entry（包含 circuit / healthScore 等运行时状态） */
   entry: PoolEntry;
+  /** registry 里的原始 seller 描述 */
   registrySeller: RegistrySeller;
+  /** seller 全局 ID（同时也是 token class） */
   sellerId: string;
+  /** 去掉尾部斜杠后的 seller URL */
   url: string;
 }
 
+/**
+ * 控制器调用 `decide()` 时传入的失败上下文。
+ * 描述"这次失败发生在谁身上、是什么错误、第几次尝试"。
+ */
 export interface DecideContext {
+  /** 失败时正在调用的 seller ID */
   sellerId: string;
+  /** HTTP status（如有），用于区分 4xx/5xx */
   status?: number;
+  /** 错误分类，由调用方在边界层归一化为 `FailureKind` */
   errorKind: FailureKind;
+  /** 人类可读错误描述（不携带敏感字段），用于日志/doctor */
   errorMessage?: string;
+  /** 当前是该 seller 的第几次尝试（1-based） */
   attempt: number;
 }
 
+/**
+ * 构造 `RouteFailover` 所需的依赖与可调参数。
+ * 默认值见 `DEFAULTS`：软重试 2 次，jitter 100-400ms。
+ */
 export interface RouteFailoverOptions {
+  /** 共享的 seller pool，控制器只读 + 委托 recordSuccess/recordFailure */
   pool: SellerPool;
+  /** 共享的 credit tracker，用于 wasted 计算与 auto-purchase 预算 */
   creditTracker: CreditTracker;
   // v1.1 / v1.2 design defaults; exposed for tests.
+  /** 软重试次数上限，默认 2 */
   softRetryAttempts?: number;        // default 2
+  /** 软重试 backoff jitter 下界（毫秒），默认 100 */
   softRetryJitterMinMs?: number;     // default 100
+  /** 软重试 backoff jitter 上界（毫秒），默认 400 */
   softRetryJitterMaxMs?: number;     // default 400
+  /** 注入的随机源（测试用），默认 `Math.random` */
   random?: () => number;
+  /** 注入的时钟（测试用），默认 `Date.now` */
   now?: () => number;
 }