@tokenbuddy/tokenbuddy 1.0.12 → 1.0.14

package/tests/seller-route-planner.test.ts

@@ -0,0 +1,150 @@
+import { planSellerRouteSet, type SellerRoutePlannerInput } from "../src/seller-route-planner.js";
+import type { RegistrySeller } from "../src/seller-catalog.js";
+
+function seller(overrides: Partial<RegistrySeller> & { id: string; models?: string[] }): RegistrySeller {
+  return {
+    id: overrides.id,
+    name: overrides.name ?? overrides.id,
+    url: overrides.url ?? `https://${overrides.id}.example.com`,
+    supportedProtocols: overrides.supportedProtocols ?? ["chat_completions"],
+    paymentMethods: overrides.paymentMethods ?? ["clawtip"],
+    models: overrides.models ?? ["gpt-5.4"]
+  };
+}
+
+function plan(overrides: Partial<SellerRoutePlannerInput> = {}) {
+  return planSellerRouteSet({
+    modelId: "gpt-5.4",
+    protocol: "chat_completions",
+    paymentMethod: "clawtip",
+    registrySellers: [
+      seller({ id: "s1" }),
+      seller({ id: "s2" }),
+      seller({ id: "s3", supportedProtocols: ["responses"] })
+    ],
+    routing: { mode: "fullAuto", scorer: "balanced" },
+    ...overrides
+  });
+}
+
+describe("seller route planner", () => {
+  test("uses compatible prewarm candidates before registry fallback", () => {
+    const result = plan({
+      prewarmCandidates: [
+        { sellerId: "s2", url: "https://s2.example.com", healthScore: 95, avgLatencyMs: 120 },
+        { sellerId: "s1", url: "https://s1.example.com", healthScore: 50, avgLatencyMs: 80 },
+        { sellerId: "missing", url: "https://missing.example.com", healthScore: 100, avgLatencyMs: 1 }
+      ],
+      sellerMetrics: [
+        { sellerId: "s1", discountRatio: 0.5 },
+        { sellerId: "s2", discountRatio: 0.01 }
+      ]
+    });
+
+    expect(result.source).toBe("prewarm_cache");
+    expect(result.routes.map((route) => route.seller.id)).toEqual(["s2", "s1"]);
+    expect(result.candidateCount).toBe(2);
+    expect(result.routes[0].metrics).toEqual({
+      healthScore: 95,
+      avgLatencyMs: 120,
+      discountRatio: 0.01,
+      registryOrder: 1
+    });
+  });
+
+  test("falls back to registry candidates when prewarm has no usable sellers", () => {
+    const result = plan({
+      prewarmCandidates: [
+        { sellerId: "missing", url: "https://missing.example.com", healthScore: 100 },
+        { sellerId: "s3", url: "https://s3.example.com", healthScore: 100 }
+      ]
+    });
+
+    expect(result.source).toBe("registry_fallback");
+    expect(result.sourceReason).toBe("prewarm_no_compatible_candidates");
+    expect(result.routes.map((route) => route.seller.id)).toEqual(["s1", "s2"]);
+  });
+
+  test("filters registry fallback by requested model, protocol, and payment method", () => {
+    const result = plan({
+      registrySellers: [
+        seller({ id: "ok", models: ["gpt-5.4"], supportedProtocols: ["chat_completions"], paymentMethods: ["clawtip"] }),
+        seller({ id: "wrong-model", models: ["MiniMax-M2.7"], supportedProtocols: ["chat_completions"], paymentMethods: ["clawtip"] }),
+        seller({ id: "wrong-protocol", models: ["gpt-5.4"], supportedProtocols: ["responses"], paymentMethods: ["clawtip"] }),
+        seller({ id: "wrong-payment", models: ["gpt-5.4"], supportedProtocols: ["chat_completions"], paymentMethods: ["mock"] })
+      ]
+    });
+
+    expect(result.source).toBe("registry_fallback");
+    expect(result.routes.map((route) => route.seller.id)).toEqual(["ok"]);
+    expect(result.reason).toBe("fullAuto:balanced:routes_1");
+  });
+
+  test("fixed mode fails closed when selected seller is outside compatibility", () => {
+    const result = plan({
+      routing: { mode: "fixed", sellerId: "s3", scorer: "speed" }
+    });
+
+    expect(result.routes).toEqual([]);
+    expect(result.reason).toBe("fixed_seller_not_compatible");
+  });
+
+  test("fixedSet mode does not select outside the configured seller pool", () => {
+    const result = plan({
+      routing: { mode: "fixedSet", sellerIds: ["s1", "s2"], scorer: "speed" },
+      sellerMetrics: [
+        { sellerId: "outside", healthScore: 100, avgLatencyMs: 10 },
+        { sellerId: "s1", healthScore: 40, avgLatencyMs: 20 },
+        { sellerId: "s2", healthScore: 90, avgLatencyMs: 30 }
+      ],
+      registrySellers: [
+        seller({ id: "outside" }),
+        seller({ id: "s1" }),
+        seller({ id: "s2" })
+      ]
+    });
+
+    expect(result.routes.map((route) => route.seller.id)).toEqual(["s2", "s1"]);
+  });
+
+  test("discount scorer uses planner metrics during registry fallback", () => {
+    const result = plan({
+      routing: { mode: "fullAuto", scorer: "discount" },
+      sellerMetrics: [
+        { sellerId: "s1", healthScore: 100, discountRatio: 1 },
+        { sellerId: "s2", healthScore: 30, discountRatio: 0.01 }
+      ]
+    });
+
+    expect(result.routes.map((route) => route.seller.id)).toEqual(["s2", "s1"]);
+  });
+
+  test("messages protocol accepts anthropic_messages registry sellers", () => {
+    const result = plan({
+      modelId: "MiniMax-M2.7",
+      protocol: "messages",
+      registrySellers: [
+        seller({
+          id: "minimax",
+          models: ["MiniMax-M2.7"],
+          supportedProtocols: ["anthropic_messages"],
+          paymentMethods: ["clawtip"]
+        })
+      ]
+    });
+
+    expect(result.routes.map((route) => route.seller.id)).toEqual(["minimax"]);
+  });
+
+  test("open circuit observations are excluded before strategy selection", () => {
+    const result = plan({
+      routing: { mode: "fullAuto", scorer: "speed" },
+      sellerMetrics: [
+        { sellerId: "s1", healthScore: 100, circuit: "open" },
+        { sellerId: "s2", healthScore: 20, circuit: "closed" }
+      ]
+    });
+
+    expect(result.routes.map((route) => route.seller.id)).toEqual(["s2"]);
+  });
+});

package/tests/seller-routing-config.test.ts

@@ -0,0 +1,111 @@
+import {
+  assertSellerRoutingConfig,
+  defaultSellerRoutingConfig,
+  mergeSellerRoutingConfig,
+  normalizeSellerRoutingConfig,
+  parseSellerIdList,
+  parseSellerRoutingEnv
+} from "../src/seller-routing-config.js";
+
+describe("seller routing config", () => {
+  test("defaults to fullAuto balanced routing", () => {
+    expect(defaultSellerRoutingConfig()).toEqual({
+      mode: "fullAuto",
+      scorer: "balanced"
+    });
+  });
+
+  test("normalizes fixed and fixedSet configs", () => {
+    expect(normalizeSellerRoutingConfig({
+      mode: "fixed",
+      sellerId: " tbs-1 ",
+      scorer: "speed"
+    })).toEqual({
+      mode: "fixed",
+      sellerId: "tbs-1",
+      scorer: "speed"
+    });
+
+    expect(normalizeSellerRoutingConfig({
+      mode: "fixedSet",
+      sellerIds: ["tbs-1", " ", "tbs-2", "tbs-1"],
+      scorer: "discount"
+    })).toEqual({
+      mode: "fixedSet",
+      sellerIds: ["tbs-1", "tbs-2"],
+      scorer: "discount"
+    });
+  });
+
+  test("does not accept legacy auto/manual modes", () => {
+    expect(() => normalizeSellerRoutingConfig({ mode: "auto" })).toThrow("seller routing mode");
+    expect(() => parseSellerRoutingEnv({ TB_PROXYD_ROUTING_MODE: "manual" })).toThrow("seller routing mode");
+  });
+
+  test("rejects invalid routing scorer values", () => {
+    expect(() => normalizeSellerRoutingConfig({ mode: "fullAuto", scorer: "fast" })).toThrow("seller routing scorer");
+    expect(() => parseSellerRoutingEnv({ TB_PROXYD_ROUTING_SCORER: "random" })).toThrow("seller routing scorer");
+  });
+
+  test("parses only the new routing environment variables", () => {
+    expect(parseSellerRoutingEnv({
+      TB_PROXYD_ROUTING_MODE: "fixedSet",
+      TB_PROXYD_ROUTING_SELLER_IDS: "tbs-1,tbs-2,tbs-1",
+      TB_PROXYD_ROUTING_SCORER: "speed"
+    })).toEqual({
+      mode: "fixedSet",
+      sellerIds: ["tbs-1", "tbs-2"],
+      scorer: "speed"
+    });
+
+    expect(parseSellerRoutingEnv({
+      TB_PROXYD_SELECTION_MODE: "manual",
+      TB_PROXYD_SELECTED_SELLER_ID: "old-seller"
+    })).toBeUndefined();
+  });
+
+  test("infers routing mode from individual environment variables", () => {
+    expect(parseSellerRoutingEnv({
+      TB_PROXYD_ROUTING_SELLER_ID: "tbs-1"
+    })).toEqual({
+      mode: "fixed",
+      sellerId: "tbs-1",
+      scorer: "balanced"
+    });
+
+    expect(parseSellerRoutingEnv({
+      TB_PROXYD_ROUTING_SELLER_IDS: "tbs-1,tbs-2"
+    })).toEqual({
+      mode: "fixedSet",
+      sellerIds: ["tbs-1", "tbs-2"],
+      scorer: "balanced"
+    });
+
+    expect(parseSellerRoutingEnv({
+      TB_PROXYD_ROUTING_SCORER: "discount"
+    })).toEqual({
+      mode: "fullAuto",
+      scorer: "discount"
+    });
+  });
+
+  test("merges explicit overrides over stored config", () => {
+    expect(mergeSellerRoutingConfig(
+      { mode: "fullAuto", scorer: "balanced" },
+      { mode: "fixed", sellerId: "tbs-1", scorer: "discount" }
+    )).toEqual({
+      mode: "fixed",
+      sellerId: "tbs-1",
+      scorer: "discount"
+    });
+  });
+
+  test("validates required fixed strategy parameters", () => {
+    expect(() => assertSellerRoutingConfig({ mode: "fixed", scorer: "balanced" })).toThrow("--seller");
+    expect(() => assertSellerRoutingConfig({ mode: "fixedSet", sellerIds: [], scorer: "balanced" })).toThrow("--seller-set");
+  });
+
+  test("parses comma-separated seller id lists", () => {
+    expect(parseSellerIdList(" a, b,,a ")).toEqual(["a", "b"]);
+  });
+});

package/tests/seller-routing-strategy.test.ts

@@ -0,0 +1,166 @@
+import { planSellerRoutes, type RoutingCandidate, type SellerRoutingStrategyConfig } from "../src/seller-routing-strategy.js";
+
+function candidate(overrides: Partial<RoutingCandidate> & { sellerId: string; registryOrder: number }): RoutingCandidate {
+  return {
+    sellerId: overrides.sellerId,
+    url: overrides.url ?? `https://${overrides.sellerId}.example.com`,
+    supportsModel: overrides.supportsModel ?? true,
+    supportsProtocol: overrides.supportsProtocol ?? true,
+    supportsPayment: overrides.supportsPayment ?? true,
+    healthScore: overrides.healthScore,
+    avgLatencyMs: overrides.avgLatencyMs,
+    healthProbeLatencyMs: overrides.healthProbeLatencyMs,
+    ttftMs: overrides.ttftMs,
+    avgInferenceMs: overrides.avgInferenceMs,
+    discountRatio: overrides.discountRatio,
+    registryOrder: overrides.registryOrder
+  };
+}
+
+function planIds(candidates: RoutingCandidate[], config: SellerRoutingStrategyConfig): string[] {
+  return planSellerRoutes(candidates, config).routes.map((route) => route.sellerId);
+}
+
+describe("seller routing strategy", () => {
+  test("fixed mode returns only the configured seller", () => {
+    const result = planSellerRoutes(
+      [
+        candidate({ sellerId: "s1", registryOrder: 0, healthScore: 40 }),
+        candidate({ sellerId: "s2", registryOrder: 1, healthScore: 99 })
+      ],
+      { mode: "fixed", sellerId: "s1", scorer: "speed" }
+    );
+
+    expect(result.routes.map((route) => route.sellerId)).toEqual(["s1"]);
+    expect(result.reason).toBe("fixed:speed:routes_1");
+  });
+
+  test("fixed mode matches seller ids case-insensitively", () => {
+    const ids = planIds(
+      [
+        candidate({ sellerId: "TBS-1", registryOrder: 0 }),
+        candidate({ sellerId: "tbs-2", registryOrder: 1 })
+      ],
+      { mode: "fixed", sellerId: "tbs-1" }
+    );
+
+    expect(ids).toEqual(["TBS-1"]);
+  });
+
+  test("fixed mode fails closed when the configured seller is not compatible", () => {
+    const result = planSellerRoutes(
+      [
+        candidate({ sellerId: "s1", registryOrder: 0, supportsPayment: false }),
+        candidate({ sellerId: "s2", registryOrder: 1 })
+      ],
+      { mode: "fixed", sellerId: "s1" }
+    );
+
+    expect(result.routes).toEqual([]);
+    expect(result.reason).toBe("fixed_seller_not_compatible");
+  });
+
+  test("fixed mode requires a seller id", () => {
+    const result = planSellerRoutes([candidate({ sellerId: "s1", registryOrder: 0 })], { mode: "fixed" });
+
+    expect(result.routes).toEqual([]);
+    expect(result.reason).toBe("fixed_seller_missing");
+  });
+
+  test("fixedSet mode never selects sellers outside the configured pool", () => {
+    const ids = planIds(
+      [
+        candidate({ sellerId: "outside-fast", registryOrder: 0, healthScore: 100 }),
+        candidate({ sellerId: "pool-a", registryOrder: 1, healthScore: 30 }),
+        candidate({ sellerId: "pool-b", registryOrder: 2, healthScore: 70 })
+      ],
+      { mode: "fixedSet", sellerIds: ["pool-a", "pool-b"], scorer: "speed" }
+    );
+
+    expect(ids).toEqual(["pool-b", "pool-a"]);
+  });
+
+  test("fixedSet mode matches seller pools case-insensitively", () => {
+    const ids = planIds(
+      [
+        candidate({ sellerId: "TBS-A", registryOrder: 0, healthScore: 30 }),
+        candidate({ sellerId: "tbs-B", registryOrder: 1, healthScore: 70 })
+      ],
+      { mode: "fixedSet", sellerIds: ["TBS-A", "TBS-B"], scorer: "balanced" }
+    );
+
+    expect(ids).toEqual(["tbs-B", "TBS-A"]);
+  });
+
+  test("fixedSet mode reports empty pool before routing", () => {
+    const result = planSellerRoutes([candidate({ sellerId: "s1", registryOrder: 0 })], { mode: "fixedSet", sellerIds: [] });
+
+    expect(result.routes).toEqual([]);
+    expect(result.reason).toBe("fixed_set_empty");
+  });
+
+  test("fullAuto mode uses all compatible candidates", () => {
+    const ids = planIds(
+      [
+        candidate({ sellerId: "s1", registryOrder: 0 }),
+        candidate({ sellerId: "s2", registryOrder: 1, supportsProtocol: false }),
+        candidate({ sellerId: "s3", registryOrder: 2 })
+      ],
+      { mode: "fullAuto" }
+    );
+
+    expect(ids).toEqual(["s1", "s3"]);
+  });
+
+  test("speed scorer prefers lower TTFT and average inference time, then health", () => {
+    const ids = planIds(
+      [
+        candidate({ sellerId: "high-slow", registryOrder: 0, healthScore: 90, ttftMs: 800, avgInferenceMs: 800 }),
+        candidate({ sellerId: "high-fast", registryOrder: 1, healthScore: 90, ttftMs: 100, avgInferenceMs: 100 }),
+        candidate({ sellerId: "low-fast", registryOrder: 2, healthScore: 40, ttftMs: 10, avgInferenceMs: 10 })
+      ],
+      { mode: "fullAuto", scorer: "speed" }
+    );
+
+    expect(ids).toEqual(["low-fast", "high-fast", "high-slow"]);
+  });
+
+  test("discount scorer prefers lower discount ratio, then health", () => {
+    const ids = planIds(
+      [
+        candidate({ sellerId: "expensive", registryOrder: 0, discountRatio: 1, healthScore: 100 }),
+        candidate({ sellerId: "cheap-low-health", registryOrder: 1, discountRatio: 0.01, healthScore: 20 }),
+        candidate({ sellerId: "cheap-high-health", registryOrder: 2, discountRatio: 0.01, healthScore: 90 })
+      ],
+      { mode: "fullAuto", scorer: "discount" }
+    );
+
+    expect(ids).toEqual(["cheap-high-health", "cheap-low-health", "expensive"]);
+  });
+
+  test("balanced scorer combines health, latency, and discount", () => {
+    const ids = planIds(
+      [
+        candidate({ sellerId: "healthy-expensive", registryOrder: 0, healthScore: 90, avgLatencyMs: 100, discountRatio: 1 }),
+        candidate({ sellerId: "balanced", registryOrder: 1, healthScore: 80, avgLatencyMs: 100, discountRatio: 0.01 }),
+        candidate({ sellerId: "cheap-unhealthy", registryOrder: 2, healthScore: 20, avgLatencyMs: 100, discountRatio: 0.01 })
+      ],
+      { mode: "fullAuto", scorer: "balanced" }
+    );
+
+    expect(ids).toEqual(["balanced", "cheap-unhealthy", "healthy-expensive"]);
+  });
+
+  test("registry order is the stable tie breaker", () => {
+    const ids = planIds(
+      [
+        candidate({ sellerId: "s2", registryOrder: 2, healthScore: 80, avgLatencyMs: 100, discountRatio: 0.5 }),
+        candidate({ sellerId: "s0", registryOrder: 0, healthScore: 80, avgLatencyMs: 100, discountRatio: 0.5 }),
+        candidate({ sellerId: "s1", registryOrder: 1, healthScore: 80, avgLatencyMs: 100, discountRatio: 0.5 })
+      ],
+      { mode: "fullAuto", scorer: "balanced" }
+    );
+
+    expect(ids).toEqual(["s0", "s1", "s2"]);
+  });
+});