@tokenbuddy/tokenbuddy 1.0.9 → 1.0.12

package/src/route-failover.test.ts

@@ -0,0 +1,193 @@
+import { CreditTracker } from "../src/credit-tracker.js";
+import { ModelIndex } from "../src/model-index.js";
+import { PrewarmCache } from "../src/prewarm-cache.js";
+import { RouteFailover, type DecideContext } from "../src/route-failover.js";
+import { SellerPool } from "../src/seller-pool.js";
+import type { RegistrySeller } from "../src/seller-catalog.js";
+
+function makeSeller(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
+  };
+}
+
+function buildHarness(seed: { id: string; healthScore?: number }[] = []) {
+  const sellers: RegistrySeller[] = seed.map((s) => makeSeller({ id: s.id, models: ["gpt-4o"] }));
+  const index = new ModelIndex();
+  index.rebuild(sellers, { registryVersion: 1, defaultSellerId: seed[0]?.id });
+  const cache = new PrewarmCache();
+  cache.commitWarm({
+    modelId: "gpt-4o",
+    protocol: "chat_completions",
+    paymentMethod: "clawtip",
+    candidates: seed.map((s) => ({
+      sellerId: s.id,
+      url: `https://${s.id}.example.com`,
+      healthScore: s.healthScore ?? 80
+    }))
+  });
+  const credit = new CreditTracker();
+  const pool = new SellerPool({ modelIndex: index, cache, creditTracker: credit });
+  pool.sync();
+  const failover = new RouteFailover({ pool, creditTracker: credit });
+  return { index, cache, credit, pool, failover, sellers };
+}
+
+describe("RouteFailover", () => {
+  test("pickNext returns the highest-scoring candidate from the pool", () => {
+    const { failover } = buildHarness([{ id: "s1", healthScore: 50 }, { id: "s2", healthScore: 90 }, { id: "s3", healthScore: 70 }]);
+    const next = failover.pickNext("gpt-4o", "chat_completions", "clawtip");
+    expect(next?.sellerId).toBe("s2");
+  });
+
+  test("pickNext returns undefined when the pool is exhausted", () => {
+    const index = new ModelIndex();
+    index.rebuild([], { registryVersion: 1 });
+    const cache = new PrewarmCache();
+    const credit = new CreditTracker();
+    const pool = new SellerPool({ modelIndex: index, cache, creditTracker: credit });
+    pool.sync();
+    const failover = new RouteFailover({ pool, creditTracker: credit });
+    expect(failover.pickNext("gpt-4o", "chat_completions", "clawtip")).toBeUndefined();
+  });
+
+  test("decide on hard_4xx immediately returns failover_next and never retries", () => {
+    const { failover, credit } = buildHarness([{ id: "s1" }]);
+    credit.recordPurchase("s1", 1_000_000, 800_000);
+    const context: DecideContext = {
+      sellerId: "s1",
+      status: 404,
+      errorKind: "hard_4xx",
+      errorMessage: "model not found",
+      attempt: 0
+    };
+    const decision = failover.decide(context, 1);
+    expect(decision.action).toBe("failover_next");
+    expect(decision.reason).toBe("hard_failure:hard_4xx");
+    expect(decision.freshPurchase).toBe(true);
+    // Hard failure transfers leftover to wasted.
+    expect(decision.wastedCreditMicros).toBeGreaterThan(0);
+  });
+
+  test("decide on auth_invalid opens the circuit and surfaces failover", () => {
+    const { failover, pool } = buildHarness([{ id: "s1" }]);
+    const context: DecideContext = {
+      sellerId: "s1",
+      status: 401,
+      errorKind: "auth_invalid",
+      errorMessage: "token_invalid",
+      attempt: 0
+    };
+    const decision = failover.decide(context, 1);
+    expect(decision.action).toBe("failover_next");
+    expect(pool.snapshot()[0].circuit).toBe("open");
+  });
+
+  test("decide on soft_5xx inside fresh-purchase window retries the same seller with jitter", () => {
+    const { failover, credit } = buildHarness([{ id: "s1" }]);
+    credit.recordPurchase("s1", 1_000_000, 1_000_000);
+    const decision = failover.decide(
+      { sellerId: "s1", status: 503, errorKind: "soft_5xx", errorMessage: "upstream", attempt: 0 },
+      1
+    );
+    expect(decision.action).toBe("retry_same_seller");
+    expect(decision.retryDelayMs).toBeGreaterThanOrEqual(100);
+    expect(decision.retryDelayMs).toBeLessThanOrEqual(400);
+    expect(decision.freshPurchase).toBe(true);
+    expect(decision.reason).toBe("soft_failure_fresh_purchase_window");
+  });
+
+  test("decide on soft_5xx after exhausting retries returns failover_next", () => {
+    const { failover, credit } = buildHarness([{ id: "s1" }]);
+    credit.recordPurchase("s1", 1_000_000, 1_000_000);
+    const decision = failover.decide(
+      { sellerId: "s1", status: 503, errorKind: "soft_5xx", errorMessage: "upstream", attempt: 2 },
+      1
+    );
+    expect(decision.action).toBe("failover_next");
+    expect(decision.reason).toBe("soft_failure_exhausted_retries");
+  });
+
+  test("decide on soft_5xx outside the fresh-purchase window still allows the first retry", () => {
+    const { failover, credit } = buildHarness([{ id: "s1" }]);
+    // Record a purchase, then spend it past the threshold so the window exits.
+    credit.recordPurchase("s1", 1_000_000, 1_000_000);
+    credit.recordSpend("s1", 100_000);
+    const decision = failover.decide(
+      { sellerId: "s1", status: 503, errorKind: "soft_5xx", errorMessage: "upstream", attempt: 0 },
+      1
+    );
+    expect(decision.action).toBe("retry_same_seller");
+    expect(decision.freshPurchase).toBe(false);
+    expect(decision.reason).toBe("soft_failure_retry");
+  });
+
+  test("decide on deadline uses the soft-error path", () => {
+    const { failover, credit } = buildHarness([{ id: "s1" }]);
+    credit.recordPurchase("s1", 1_000_000, 1_000_000);
+    const decision = failover.decide(
+      { sellerId: "s1", errorKind: "deadline", errorMessage: "buyer timeout", attempt: 0 },
+      1
+    );
+    expect(decision.action).toBe("retry_same_seller");
+    expect(decision.freshPurchase).toBe(true);
+  });
+
+  test("budgetExceeded flag is set when the per-minute purchase budget is exhausted", () => {
+    const { failover, credit } = buildHarness([{ id: "s1" }]);
+    // Burn through the per-minute budget.
+    credit.recordPurchase("s1", 100, 100);
+    credit.recordPurchase("s2" in credit.summary().perSeller ? "s2" : "s1", 100, 100);
+    credit.recordPurchase("s1", 100, 100);
+    credit.recordPurchase("s1", 100, 100);
+    const decision = failover.decide(
+      { sellerId: "s1", errorKind: "soft_5xx", attempt: 0 },
+      1
+    );
+    expect(decision.budgetExceeded).toBe(true);
+  });
+
+  test("recordSuccess resets failure counters and reports to the credit tracker", () => {
+    const { failover, credit, pool } = buildHarness([{ id: "s1" }]);
+    credit.recordPurchase("s1", 1_000_000, 1_000_000);
+    failover.decide(
+      { sellerId: "s1", errorKind: "soft_5xx", attempt: 0 },
+      1
+    );
+    failover.decide(
+      { sellerId: "s1", errorKind: "soft_5xx", attempt: 1 },
+      1
+    );
+    failover.recordSuccess("s1", 750_000);
+    const entry = pool.snapshot()[0];
+    expect(entry.consecutiveFailures).toBe(0);
+    expect(credit.getEntry("s1")?.currentBalanceMicros).toBe(750_000);
+  });
+
+  test("shouldAbort returns true when no more candidates are available", () => {
+    const { failover } = buildHarness([{ id: "s1" }]);
+    expect(failover.shouldAbort(1, false)).toBe(true);
+    expect(failover.shouldAbort(1, true)).toBe(false);
+  });
+
+  test("canAutoPurchase mirrors the credit tracker budget", () => {
+    const { failover, credit } = buildHarness([{ id: "s1" }]);
+    expect(failover.canAutoPurchase()).toBe(true);
+    credit.recordPurchase("s1", 100, 100);
+    credit.recordPurchase("s1", 100, 100);
+    credit.recordPurchase("s1", 100, 100);
+    expect(failover.canAutoPurchase()).toBe(false);
+  });
+
+  test("wastedMicrosFor returns the latest known balance for a seller", () => {
+    const { failover, credit } = buildHarness([{ id: "s1" }]);
+    expect(failover.wastedMicrosFor("s1")).toBe(0);
+    credit.recordPurchase("s1", 1_000_000, 500_000);
+    expect(failover.wastedMicrosFor("s1")).toBe(500_000);
+  });
+});

package/src/route-failover.ts

@@ -0,0 +1,233 @@
+import { createModuleLogger } from "@tokenbuddy/logging";
+import type { RegistrySeller } from "./seller-catalog.js";
+import type { SellerPool, FailureKind, PoolEntry } from "./seller-pool.js";
+import type { CreditTracker } from "./credit-tracker.js";
+
+const logger = createModuleLogger("tb-proxyd:route-failover");
+
+export type RouteAction = "retry_same_seller" | "failover_next" | "fail_fast" | "abort";
+
+export interface FailoverDecision {
+  action: RouteAction;
+  retryDelayMs?: number;
+  reason: string;
+  wastedCreditMicros?: number;
+  freshPurchase: boolean;
+  retryAttemptsBeforeFailover: number;
+  budgetExceeded: boolean;
+}
+
+export interface RouteCandidate {
+  routeIndex: number;
+  entry: PoolEntry;
+  registrySeller: RegistrySeller;
+  sellerId: string;
+  url: string;
+}
+
+export interface DecideContext {
+  sellerId: string;
+  status?: number;
+  errorKind: FailureKind;
+  errorMessage?: string;
+  attempt: number;
+}
+
+export interface RouteFailoverOptions {
+  pool: SellerPool;
+  creditTracker: CreditTracker;
+  // v1.1 / v1.2 design defaults; exposed for tests.
+  softRetryAttempts?: number;        // default 2
+  softRetryJitterMinMs?: number;     // default 100
+  softRetryJitterMaxMs?: number;     // default 400
+  random?: () => number;
+  now?: () => number;
+}
+
+const DEFAULTS = {
+  softRetryAttempts: 2,
+  softRetryJitterMinMs: 100,
+  softRetryJitterMaxMs: 400
+};
+
+/**
+ * Decision engine that wraps the v2 `SellerPool` and the
+ * `CreditTracker`. v1.2 §17.3 - §17.8 defines the rules: the controller
+ * calls `decide()` after a failure to learn whether to retry the same
+ * seller, fail over to the next candidate, fail fast, or give up.
+ *
+ * The controller is intentionally side-effect-light: it delegates
+ * bookkeeping (circuit transitions, wasted-credit transfer) to the pool
+ * and tracker via `recordFailure`, and only returns a structured
+ * decision. This makes the rules unit-testable without a live HTTP server.
+ */
+export class RouteFailover {
+  private readonly pool: SellerPool;
+  private readonly creditTracker: CreditTracker;
+  private readonly softRetryAttempts: number;
+  private readonly softRetryJitterMinMs: number;
+  private readonly softRetryJitterMaxMs: number;
+  private readonly random: () => number;
+  private readonly now: () => number;
+
+  constructor(options: RouteFailoverOptions) {
+    this.pool = options.pool;
+    this.creditTracker = options.creditTracker;
+    this.softRetryAttempts = options.softRetryAttempts ?? DEFAULTS.softRetryAttempts;
+    this.softRetryJitterMinMs = options.softRetryJitterMinMs ?? DEFAULTS.softRetryJitterMinMs;
+    this.softRetryJitterMaxMs = options.softRetryJitterMaxMs ?? DEFAULTS.softRetryJitterMaxMs;
+    this.random = options.random ?? Math.random;
+    this.now = options.now ?? Date.now;
+  }
+
+  /**
+   * Pick the next candidate from the pool. Returns `undefined` when the
+   * pool is exhausted, which the caller treats as `abort` (no more routes
+   * to try). The returned `routeIndex` is informational (used for log
+   * lines) and tracks the absolute ordering across attempts; the controller
+   * maintains its own counter.
+   */
+  pickNext(modelId: string, protocol: string, paymentMethod: string, limit: number = 4): RouteCandidate | undefined {
+    const result = this.pool.pick({ modelId, protocol, paymentMethod, limit });
+    if (result.candidates.length === 0) {
+      return undefined;
+    }
+    const first = result.candidates[0];
+    return {
+      routeIndex: 0,
+      entry: first.entry,
+      registrySeller: first.registrySeller,
+      sellerId: first.entry.sellerId,
+      url: first.entry.url
+    };
+  }
+
+  /**
+   * Mark a successful inference against `sellerId` with the latest known
+   * balance. Mirrors `SellerPool.recordSuccess` semantics: resets the
+   * failure counter, closes the circuit, and reports the spend to the
+   * credit tracker.
+   */
+  recordSuccess(sellerId: string, balanceMicros: number): void {
+    this.pool.recordSuccess(sellerId, balanceMicros, this.now());
+  }
+
+  /**
+   * Decide what to do after a failure. Returns a structured
+   * `FailoverDecision`; the controller (daemon.ts) executes the action.
+   * The decision also drives accounting: on a failover, the wasted
+   * balance is reported in `wastedCreditMicros` for the doctor's summary.
+   */
+  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 info = this.pool.inspect(context.sellerId);
+    const freshPurchase = info.freshPurchase;
+    const budgetExceeded = !this.creditTracker.canAutoPurchase(this.now());
+
+    // Always mark the failure on the pool so circuit thresholds advance.
+    const updated = this.pool.recordFailure(context.sellerId, context.errorKind, {
+      reason: context.errorMessage,
+      now: this.now()
+    });
+
+    if (isHard) {
+      // Hard failures are not eligible for retry; the seller is wrong
+      // for this request. The pool has already transferred leftover
+      // credit to the wasted bucket.
+      return {
+        action: "failover_next",
+        reason: `hard_failure:${context.errorKind}`,
+        wastedCreditMicros: this.creditTracker.getEntry(context.sellerId)?.leftoverCreditMicros,
+        freshPurchase,
+        retryAttemptsBeforeFailover: context.attempt,
+        budgetExceeded
+      };
+    }
+
+    if (isSoft && freshPurchase && context.attempt < this.softRetryAttempts) {
+      // Soft failure inside the fresh-purchase window: retry the same
+      // seller with jittered backoff. This is the v1.1 protection against
+      // throwing freshly bought credit onto a flaky upstream.
+      const span = Math.max(0, this.softRetryJitterMaxMs - this.softRetryJitterMinMs);
+      const delay = this.softRetryJitterMinMs + Math.floor(this.random() * span);
+      logger.info("route.retry_same_seller.soft", "soft failure in fresh-purchase window; retrying same seller", {
+        sellerId: context.sellerId,
+        attempt: context.attempt,
+        delayMs: delay
+      });
+      return {
+        action: "retry_same_seller",
+        retryDelayMs: delay,
+        reason: "soft_failure_fresh_purchase_window",
+        freshPurchase: true,
+        retryAttemptsBeforeFailover: context.attempt,
+        budgetExceeded
+      };
+    }
+
+    if (isSoft && context.attempt < this.softRetryAttempts) {
+      // Soft failure but not in the fresh-purchase window: still retry
+      // once (caller asked for `attempt < softRetryAttempts`) but log the
+      // reason. This keeps the "give the seller a second chance" window
+      // available for cold sellers without burning any credit.
+      const span = Math.max(0, this.softRetryJitterMaxMs - this.softRetryJitterMinMs);
+      const delay = this.softRetryJitterMinMs + Math.floor(this.random() * span);
+      logger.info("route.retry_same_seller.soft", "soft failure retry outside fresh-purchase window", {
+        sellerId: context.sellerId,
+        attempt: context.attempt,
+        delayMs: delay
+      });
+      return {
+        action: "retry_same_seller",
+        retryDelayMs: delay,
+        reason: "soft_failure_retry",
+        freshPurchase: false,
+        retryAttemptsBeforeFailover: context.attempt,
+        budgetExceeded
+      };
+    }
+
+    // Default: fail over. The wasted credit is whatever current balance
+    // remained on the seller after the failure was recorded (the pool
+    // transfers it to the leftover bucket for hard failures; for soft
+    // failures we surface the *pre-failure* balance so the user sees the
+    // impact of the cut-over).
+    const wasted = updated?.lastFailAt
+      ? this.creditTracker.getEntry(context.sellerId)?.currentBalanceMicros
+      : undefined;
+    return {
+      action: "failover_next",
+      reason: isSoft ? "soft_failure_exhausted_retries" : `${context.errorKind}`,
+      wastedCreditMicros: wasted,
+      freshPurchase,
+      retryAttemptsBeforeFailover: context.attempt,
+      budgetExceeded
+    };
+  }
+
+  /**
+   * Convenience: returns true when the next request should be aborted
+   * outright (no more candidates).
+   */
+  shouldAbort(totalCandidates: number, hasMoreCandidates: boolean): boolean {
+    return !hasMoreCandidates;
+  }
+
+  /**
+   * Inspect the auto-purchase budget. The controller calls this before
+   * triggering a fresh `purchase/create` round-trip so it can refuse to
+   * auto-purchase once the session is at risk.
+   */
+  canAutoPurchase(): boolean {
+    return this.creditTracker.canAutoPurchase(this.now());
+  }
+
+  /**
+   * Surface the wasted credit so far for the route currently failing over.
+   * Returned in micros.
+   */
+  wastedMicrosFor(sellerId: string): number {
+    return this.creditTracker.getEntry(sellerId)?.currentBalanceMicros ?? 0;
+  }
+}

package/src/seller-catalog-413.test.ts

@@ -0,0 +1,61 @@
+import { RegistryTooLargeError, fetchSellerRegistry } from "../src/seller-catalog.js";
+
+/**
+ * v1.2 §18.9: registry-too-large fallback. The bootstrap returns 413
+ * with a structured body when the serialized registry exceeds 1MB; the
+ * buyer must surface this as a typed error so the daemon can fall back
+ * to the last-known snapshot.
+ */
+describe("RegistryTooLargeError + fetchSellerRegistry 413", () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  function mockJsonResponse(status: number, body: unknown): Response {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+
+  test("fetchSellerRegistry throws RegistryTooLargeError on HTTP 413 with the bootstrap's payload", async () => {
+    globalThis.fetch = (async () =>
+      mockJsonResponse(413, {
+        error: "registry_too_large",
+        sizeBytes: 1_500_000,
+        sellerCount: 2_400,
+        maxBytes: 1_000_000
+      })) as unknown as typeof globalThis.fetch;
+    await expect(
+      fetchSellerRegistry("https://bootstrap.example/registry/sellers")
+    ).rejects.toMatchObject({
+      name: "RegistryTooLargeError",
+      status: 413,
+      sizeBytes: 1_500_000,
+      sellerCount: 2_400,
+      maxBytes: 1_000_000
+    });
+  });
+
+  test("fetchSellerRegistry still surfaces generic non-2xx as plain errors", async () => {
+    globalThis.fetch = (async () => mockJsonResponse(500, { error: "internal" })) as unknown as typeof globalThis.fetch;
+    await expect(
+      fetchSellerRegistry("https://bootstrap.example/registry/sellers")
+    ).rejects.toThrow(/registry returned 500/);
+  });
+
+  test("RegistryTooLargeError is a stable Error subclass with a useful message", () => {
+    const err = new RegistryTooLargeError({
+      status: 413,
+      sizeBytes: 2_500_000,
+      sellerCount: 1500,
+      maxBytes: 1_000_000
+    });
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("RegistryTooLargeError");
+    expect(err.message).toContain("1500 sellers");
+    expect(err.message).toContain("2500000");
+  });
+});

package/src/seller-catalog.ts

@@ -10,6 +10,13 @@ export interface RegistrySeller {
   url: string;
   supportedProtocols?: string[];
   paymentMethods?: string[];
+  /**
+   * v1.2: authoritative model list for buyer-side model-index routing.
+   * Optional at the buyer boundary for backward compatibility with older
+   * registry payloads, but the upstream wallet-bootstrap registry schema
+   * requires it. Missing entries are reported via `models_refresh.seller_missing_models`.
+   */
+  models?: string[];
 }
 
 export interface SellerRegistryDocument {
@@ -111,8 +118,48 @@ function manifestModels(manifest: SellerManifest): ManifestModelRecord[] {
     .filter((model): model is ManifestModelRecord => Boolean(model?.id && typeof model.id === "string"));
 }
 
+/**
+ * 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.
+ */
+export class RegistryTooLargeError extends Error {
+  readonly status: number;
+  readonly sizeBytes: number;
+  readonly sellerCount: number;
+  readonly maxBytes: number;
+  constructor(detail: { status: number; sizeBytes: number; sellerCount: number; maxBytes: number }) {
+    super(`registry response exceeds ${detail.maxBytes} bytes (got ${detail.sizeBytes}, ${detail.sellerCount} sellers, status ${detail.status})`);
+    this.name = "RegistryTooLargeError";
+    this.status = detail.status;
+    this.sizeBytes = detail.sizeBytes;
+    this.sellerCount = detail.sellerCount;
+    this.maxBytes = detail.maxBytes;
+  }
+}
+
 export async function fetchSellerRegistry(registryUrl: string): Promise<SellerRegistryDocument> {
   const response = await fetch(registryUrl);
+  if (response.status === 413) {
+    // v1.2 §18.9: parse the structured 413 body so the caller can
+    // decide whether to fall back to a stale snapshot.
+    let sizeBytes = 0;
+    let sellerCount = 0;
+    let maxBytes = 0;
+    try {
+      const body = (await response.json()) as { sizeBytes?: number; sellerCount?: number; maxBytes?: number };
+      sizeBytes = body.sizeBytes ?? 0;
+      sellerCount = body.sellerCount ?? 0;
+      maxBytes = body.maxBytes ?? 0;
+    } catch {
+      // Fall through with zeroes; the error message still carries the
+      // status code which is enough for the daemon's stale-cache
+      // branch to fire.
+    }
+    throw new RegistryTooLargeError({ status: response.status, sizeBytes, sellerCount, maxBytes });
+  }
   if (!response.ok) {
     throw new Error(`registry returned ${response.status}`);
   }