@tokenbuddy/tokenbuddy 1.0.9 → 1.0.11

package/src/seller-pool.test.ts

@@ -0,0 +1,231 @@
+import { CreditTracker } from "../src/credit-tracker.js";
+import { ModelIndex } from "../src/model-index.js";
+import { PrewarmCache } from "../src/prewarm-cache.js";
+import { SellerPool, type FailureKind } 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 makeClock(start = 1_000_000): { now: number; advance: (ms: number) => void } {
+  const clock = { now: start, advance: (ms: number) => { clock.now += ms; } };
+  return clock;
+}
+
+function build(seed: { id: string; healthScore?: number }[] = []): { index: ModelIndex; cache: PrewarmCache; credit: CreditTracker; sellers: RegistrySeller[] } {
+  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();
+  return { index, cache, credit, sellers };
+}
+
+describe("SellerPool", () => {
+  test("sync rebuilds entries from the prewarm cache", () => {
+    const ctx = build([{ id: "s1" }, { id: "s2" }]);
+    const pool = new SellerPool({
+      modelIndex: ctx.index,
+      cache: ctx.cache,
+      creditTracker: ctx.credit
+    });
+    const size = pool.sync();
+    expect(size).toBe(2);
+    expect(pool.snapshot().map((e) => e.sellerId).sort()).toEqual(["s1", "s2"]);
+  });
+
+  test("sync drops entries whose seller disappeared from the registry index", () => {
+    const ctx = build([{ id: "s1" }, { id: "s2" }]);
+    const pool = new SellerPool({
+      modelIndex: ctx.index,
+      cache: ctx.cache,
+      creditTracker: ctx.credit
+    });
+    pool.sync();
+    expect(pool.size()).toBe(2);
+
+    // Mutate the index so only s1 remains.
+    ctx.index.rebuild([makeSeller({ id: "s1", models: ["gpt-4o"] })], { registryVersion: 2 });
+    const size = pool.sync();
+    expect(size).toBe(1);
+    expect(pool.snapshot().map((e) => e.sellerId)).toEqual(["s1"]);
+  });
+
+  test("pick returns candidates sorted by health score and skips open circuit entries", () => {
+    const ctx = build([{ id: "s1", healthScore: 90 }, { id: "s2", healthScore: 50 }, { id: "s3", healthScore: 70 }]);
+    const pool = new SellerPool({ modelIndex: ctx.index, cache: ctx.cache, creditTracker: ctx.credit });
+    pool.sync();
+
+    const result = pool.pick({ modelId: "gpt-4o", protocol: "chat_completions", paymentMethod: "clawtip" });
+    expect(result.candidates.map((c) => c.entry.sellerId)).toEqual(["s1", "s3", "s2"]);
+
+    // Force s1 into the open circuit and verify it is skipped.
+    pool.markOpen("s1", "registry_gone");
+    const filtered = pool.pick({ modelId: "gpt-4o", protocol: "chat_completions", paymentMethod: "clawtip" });
+    expect(filtered.candidates.map((c) => c.entry.sellerId)).toEqual(["s3", "s2"]);
+  });
+
+  test("half_open recycle happens after openStateMs has elapsed", () => {
+    const clock = makeClock();
+    const ctx = build([{ id: "s1" }]);
+    const pool = new SellerPool({
+      modelIndex: ctx.index,
+      cache: ctx.cache,
+      creditTracker: ctx.credit,
+      failureThreshold: 1, // open after the very first failure to keep the test focused
+      openStateMs: 1000,
+      now: () => clock.now
+    });
+    pool.sync();
+    pool.recordFailure("s1", "soft_5xx");
+    expect(pool.snapshot()[0].circuit).toBe("open");
+
+    // Within the open window: still skipped.
+    clock.advance(500);
+    let result = pool.pick({ modelId: "gpt-4o", protocol: "chat_completions", paymentMethod: "clawtip" });
+    expect(result.candidates).toEqual([]);
+
+    // After the open window: recycled to half_open and re-included.
+    clock.advance(600);
+    result = pool.pick({ modelId: "gpt-4o", protocol: "chat_completions", paymentMethod: "clawtip" });
+    expect(result.candidates.map((c) => c.entry.sellerId)).toEqual(["s1"]);
+    expect(pool.snapshot()[0].circuit).toBe("half_open");
+  });
+
+  test("recordFailure escalates to open after the configured threshold", () => {
+    const clock = makeClock();
+    const ctx = build([{ id: "s1" }]);
+    const pool = new SellerPool({
+      modelIndex: ctx.index,
+      cache: ctx.cache,
+      creditTracker: ctx.credit,
+      failureThreshold: 3,
+      now: () => clock.now
+    });
+    pool.sync();
+
+    pool.recordFailure("s1", "soft_5xx");
+    expect(pool.snapshot()[0].circuit).toBe("closed");
+    pool.recordFailure("s1", "soft_5xx");
+    expect(pool.snapshot()[0].circuit).toBe("closed");
+    pool.recordFailure("s1", "soft_5xx");
+    expect(pool.snapshot()[0].circuit).toBe("open");
+  });
+
+  test("recordSuccess closes the circuit and reports to the credit tracker", () => {
+    const clock = makeClock();
+    const ctx = build([{ id: "s1" }]);
+    const pool = new SellerPool({
+      modelIndex: ctx.index,
+      cache: ctx.cache,
+      creditTracker: ctx.credit,
+      failureThreshold: 1, // open after the first failure
+      now: () => clock.now
+    });
+    pool.sync();
+
+    ctx.credit.recordPurchase("s1", 1_000_000, 1_000_000);
+    pool.recordFailure("s1", "soft_5xx");
+    expect(pool.snapshot()[0].circuit).toBe("open");
+
+    clock.advance(31_000); // wait past the open window
+    pool.recordSuccess("s1", 250_000);
+    const entry = pool.snapshot()[0];
+    expect(entry.circuit).toBe("closed");
+    expect(entry.consecutiveFailures).toBe(0);
+    expect(ctx.credit.getEntry("s1")?.currentBalanceMicros).toBe(250_000);
+  });
+
+  test("hard failure kinds (hard_4xx, auth_invalid) immediately open the circuit and transfer leftover", () => {
+    const ctx = build([{ id: "s1" }]);
+    const pool = new SellerPool({ modelIndex: ctx.index, cache: ctx.cache, creditTracker: ctx.credit });
+    pool.sync();
+
+    ctx.credit.recordPurchase("s1", 1_000_000, 500_000);
+    const kinds: FailureKind[] = ["hard_4xx", "auth_invalid"];
+    for (const kind of kinds) {
+      ctx.credit.recordPurchase("s1", 1_000_000, 500_000);
+      const entry = pool.recordFailure("s1", kind, { reason: "test" });
+      expect(entry?.circuit).toBe("open");
+    }
+    const summary = ctx.credit.summary();
+    expect(summary.totalWastedMicros).toBeGreaterThan(0);
+  });
+
+  test("inspect surfaces freshPurchase and autoPurchaseAvailable flags", () => {
+    const ctx = build([{ id: "s1" }]);
+    const pool = new SellerPool({ modelIndex: ctx.index, cache: ctx.cache, creditTracker: ctx.credit });
+    pool.sync();
+
+    ctx.credit.recordPurchase("s1", 1_000_000, 1_000_000);
+    const info = pool.inspect("s1");
+    expect(info.entry?.sellerId).toBe("s1");
+    expect(info.freshPurchase).toBe(true);
+    expect(info.autoPurchaseAvailable).toBe(true);
+  });
+
+  test("markOpen force-opens a circuit without changing other state", () => {
+    const ctx = build([{ id: "s1" }]);
+    const pool = new SellerPool({ modelIndex: ctx.index, cache: ctx.cache, creditTracker: ctx.credit });
+    pool.sync();
+    pool.markOpen("s1", "registry_disappeared");
+    expect(pool.snapshot()[0].circuit).toBe("open");
+  });
+
+  test("pick returns an empty result when the prewarm cache has no entry for the model", () => {
+    const index = new ModelIndex();
+    index.rebuild([makeSeller({ id: "s1", models: ["gpt-4o"] })], { registryVersion: 1 });
+    const cache = new PrewarmCache();
+    const credit = new CreditTracker();
+    const pool = new SellerPool({ modelIndex: index, cache, creditTracker: credit });
+    pool.sync();
+
+    const result = pool.pick({ modelId: "gpt-4o", protocol: "chat_completions", paymentMethod: "clawtip" });
+    expect(result.candidates).toEqual([]);
+    // No prewarm has been committed for this model yet, so the pool
+    // surfaces "no_prewarm_candidates" (not "prewarm_cache_empty"); the
+    // distinction matters for the caller deciding whether to schedule a
+    // lazy prewarm.
+    expect(result.reason).toBe("no_prewarm_candidates");
+  });
+
+  test("pick falls back to the registry index when the cache has no entry yet", () => {
+    const index = new ModelIndex();
+    index.rebuild(
+      [makeSeller({ id: "s1", models: ["gpt-4o"] }), makeSeller({ id: "s2", models: ["gpt-4o"] })],
+      { registryVersion: 1 }
+    );
+    const cache = new PrewarmCache();
+    const credit = new CreditTracker();
+    const pool = new SellerPool({ modelIndex: index, cache, creditTracker: credit });
+    pool.sync();
+
+    // No probe has run yet, so pool is empty. pick should report "no candidates" and
+    // also surface the registry-level model resolution so the caller can decide
+    // whether to schedule a lazy prewarm.
+    const result = pool.pick({ modelId: "gpt-4o", protocol: "chat_completions", paymentMethod: "clawtip" });
+    expect(result.candidates).toEqual([]);
+    expect(result.resolved.matched).toBe(true);
+    expect(result.resolved.candidates).toHaveLength(2);
+  });
+});

package/src/seller-pool.ts

@@ -0,0 +1,333 @@
+import { createModuleLogger } from "@tokenbuddy/logging";
+import type { RegistrySeller } from "./seller-catalog.js";
+import type { ModelIndex } from "./model-index.js";
+import type { PrewarmCache, PrewarmCandidate, PrewarmEntry } from "./prewarm-cache.js";
+import type { CreditTracker } from "./credit-tracker.js";
+
+const logger = createModuleLogger("tb-proxyd:seller-pool");
+
+export type CircuitState = "closed" | "half_open" | "open";
+
+export type FailureKind =
+  | "hard_4xx"           // 400/404/422 — the seller is wrong for this request
+  | "auth_invalid"       // 401/403 token invalid
+  | "insufficient_funds" // 402
+  | "soft_5xx"           // 429/5xx/timeout/network
+  | "deadline"           // buyer deadline exceeded
+  | "stream_aborted"     // upstream stream broken after first chunk
+  | "no_compatible";     // pool had no candidates for the request
+
+export interface PoolEntry {
+  sellerId: string;
+  url: string;
+  registrySeller: RegistrySeller;
+  circuit: CircuitState;
+  consecutiveFailures: number;
+  recentFailures: number[];   // timestamps (ms) for sliding window
+  lastSuccessAt: number;
+  lastFailAt: number;
+  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.
+  healthScore: number;
+  avgLatencyMs: number;
+}
+
+export interface PickOptions {
+  modelId: string;
+  protocol: string;
+  paymentMethod: string;
+  limit?: number;
+  now?: number;
+}
+
+export interface PickResult {
+  candidates: Array<{ entry: PoolEntry; registrySeller: RegistrySeller }>;
+  reason: string;
+  resolved: ModelIndexResolution;
+}
+
+export interface ModelIndexResolution {
+  modelId: string;
+  matched: boolean;
+  candidates: RegistrySeller[];
+  missingModelsFlag: number;
+}
+
+export interface SellerPoolOptions {
+  modelIndex: ModelIndex;
+  cache: PrewarmCache;
+  creditTracker: CreditTracker;
+  // Circuit breaker thresholds (v1.2 §13).
+  failureThreshold?: number;     // default 3
+  windowMs?: number;              // default 60_000 (1m sliding window)
+  windowFailureRate?: number;     // default 0.5
+  openStateMs?: number;           // default 30_000
+  now?: () => number;
+  // PoolEntry -> CircuitState transition hooks for tests.
+  applyRegistry?: (entries: PoolEntry[], registry: RegistrySeller[]) => PoolEntry[];
+}
+
+const DEFAULTS = {
+  failureThreshold: 3,
+  windowMs: 60_000,
+  windowFailureRate: 0.5,
+  openStateMs: 30_000
+};
+
+/**
+ * v2 SellerPool: combines `ModelIndex` (registry index), `PrewarmCache`
+ * (probe results), and `CreditTracker` (balance protection) into a single
+ * source of truth used by the route-failover controller. The pool is
+ * process-local and rebuilds its entry list from the cache whenever the
+ * cache mutates; entries not yet present in the cache are not in the pool.
+ */
+export class SellerPool {
+  private readonly modelIndex: ModelIndex;
+  private readonly cache: PrewarmCache;
+  private readonly creditTracker: CreditTracker;
+  private readonly failureThreshold: number;
+  private readonly windowMs: number;
+  private readonly windowFailureRate: number;
+  private readonly openStateMs: number;
+  private readonly now: () => number;
+
+  private entries = new Map<string, PoolEntry>();
+
+  constructor(options: SellerPoolOptions) {
+    this.modelIndex = options.modelIndex;
+    this.cache = options.cache;
+    this.creditTracker = options.creditTracker;
+    this.failureThreshold = options.failureThreshold ?? DEFAULTS.failureThreshold;
+    this.windowMs = options.windowMs ?? DEFAULTS.windowMs;
+    this.windowFailureRate = options.windowFailureRate ?? DEFAULTS.windowFailureRate;
+    this.openStateMs = options.openStateMs ?? DEFAULTS.openStateMs;
+    this.now = options.now ?? Date.now;
+  }
+
+  /**
+   * Rebuild entries from the current prewarm cache. Called by
+   * `route-failover` whenever the cache is mutated (commit, invalidate,
+   * etc.) so the pool always reflects the latest probe results.
+   */
+  sync(): number {
+    const fresh = new Map<string, PoolEntry>();
+    for (const entry of this.cache.snapshot()) {
+      for (const candidate of entry.candidates) {
+        const registry = this.modelIndex.getSeller(candidate.sellerId);
+        if (!registry) {
+          // Seller disappeared from the registry since the probe; skip.
+          continue;
+        }
+        const previous = this.entries.get(candidate.sellerId);
+        fresh.set(candidate.sellerId, {
+          sellerId: candidate.sellerId,
+          url: candidate.url,
+          registrySeller: registry,
+          circuit: previous?.circuit ?? "closed",
+          consecutiveFailures: previous?.consecutiveFailures ?? 0,
+          recentFailures: previous?.recentFailures ?? [],
+          lastSuccessAt: candidate.lastSuccessAt || previous?.lastSuccessAt || 0,
+          lastFailAt: candidate.lastFailAt || previous?.lastFailAt || 0,
+          lastProbeAt: entry.warmedAt,
+          healthScore: candidate.healthScore,
+          avgLatencyMs: candidate.avgLatencyMs
+        });
+      }
+    }
+    this.entries = fresh;
+    return this.entries.size;
+  }
+
+  /**
+   * Pick up to `limit` candidates for a (model, protocol, payment) triple.
+   * Sellers in the `open` circuit are skipped unless their open state has
+   * expired (they are flipped to `half_open` and included). Candidates are
+   * sorted by health score (descending) so the strongest seller goes first.
+   */
+  pick(options: PickOptions): PickResult {
+    const now = options.now ?? this.now();
+    const limit = options.limit ?? 4;
+    const freshness = this.cache.freshness(options.modelId, options.protocol, options.paymentMethod);
+    const resolved = this.modelIndex.resolve(options.modelId, {
+      protocol: options.protocol,
+      paymentMethod: options.paymentMethod
+    });
+
+    if (freshness.entry && freshness.entry.candidates.length === 0) {
+      return {
+        candidates: [],
+        reason: "prewarm_cache_empty",
+        resolved: asResolution(resolved)
+      };
+    }
+
+    const candidates = (freshness.entry?.candidates ?? [])
+      .map((candidate) => {
+        const entry = this.entries.get(candidate.sellerId);
+        if (!entry) {
+          return null;
+        }
+        return { entry, registrySeller: entry.registrySeller, candidate };
+      })
+      .filter((row): row is { entry: PoolEntry; registrySeller: RegistrySeller; candidate: PrewarmCandidate } => row !== null)
+      .map((row) => {
+        const entry = this.maybeRecycleFromOpen(row.entry, now);
+        return { entry, registrySeller: row.registrySeller };
+      })
+      .filter((row) => row.entry.circuit !== "open")
+      .sort((a, b) => b.entry.healthScore - a.entry.healthScore)
+      .slice(0, limit);
+
+    return {
+      candidates,
+      reason: candidates.length > 0 ? "prewarm_cache" : "no_prewarm_candidates",
+      resolved: asResolution(resolved)
+    };
+  }
+
+  /**
+   * Record a successful inference against `sellerId`. The circuit closes
+   * (if it was half-open) and the credit tracker observes the latest
+   * balance via `recordSpend`.
+   */
+  recordSuccess(sellerId: string, balanceMicros: number, now: number = this.now()): PoolEntry | undefined {
+    const entry = this.entries.get(sellerId);
+    if (!entry) {
+      return undefined;
+    }
+    const next: PoolEntry = {
+      ...entry,
+      circuit: "closed",
+      consecutiveFailures: 0,
+      recentFailures: [],
+      lastSuccessAt: now,
+      healthScore: Math.min(100, Math.max(entry.healthScore, 60))
+    };
+    this.entries.set(sellerId, next);
+    this.creditTracker.recordSpend(sellerId, balanceMicros);
+    logger.info("pool.success.recorded", "seller pool entry marked successful", {
+      sellerId,
+      balanceMicros,
+      healthScore: next.healthScore
+    });
+    return next;
+  }
+
+  /**
+   * Record a failure against `sellerId`. Returns the new PoolEntry. The
+   * caller (route-failover) uses the returned `entry.circuit` and the
+   * entry's `lastFailAt` to decide whether to fail over, retry, or stop.
+   * On a non-recoverable failure (`hard_4xx`, `auth_invalid`,
+   * `insufficient_funds`) the credit is also transferred to the wasted
+   * bucket so the wasted-micros counter stays accurate.
+   */
+  recordFailure(
+    sellerId: string,
+    kind: FailureKind,
+    options: { transferLeftover?: boolean; reason?: string; now?: number } = {}
+  ): PoolEntry | undefined {
+    const entry = this.entries.get(sellerId);
+    if (!entry) {
+      return undefined;
+    }
+    const now = options.now ?? this.now();
+    const recentFailures = [...entry.recentFailures, now].filter((ts) => ts >= now - this.windowMs);
+    const consecutiveFailures = entry.consecutiveFailures + 1;
+    const failureRate = recentFailures.length / Math.max(1, this.windowMs / 1000);
+    const overThreshold = consecutiveFailures >= this.failureThreshold;
+    const overRate = failureRate >= this.windowFailureRate;
+    const isHard = kind === "hard_4xx" || kind === "auth_invalid" || kind === "no_compatible";
+    const circuit: CircuitState = isHard || overThreshold || overRate ? "open" : entry.circuit;
+    const next: PoolEntry = {
+      ...entry,
+      circuit,
+      consecutiveFailures,
+      recentFailures,
+      lastFailAt: now
+    };
+    this.entries.set(sellerId, next);
+    if (options.transferLeftover || isHard) {
+      this.creditTracker.transferLeftoverToWasted(sellerId, options.reason ?? kind);
+    }
+    if (circuit === "open") {
+      logger.warn("pool.circuit_opened", "seller pool entry transitioned to circuit_open", {
+        sellerId,
+        kind,
+        consecutiveFailures,
+        recentFailureRate: failureRate,
+        threshold: this.failureThreshold
+      });
+    }
+    return next;
+  }
+
+  /**
+   * Expose a per-seller credit / circuit snapshot to the route-failover.
+   * Used to decide whether a soft failure should retry on the same seller
+   * (刚买窗口保护) or fail over immediately.
+   */
+  inspect(sellerId: string): { entry?: PoolEntry; freshPurchase: boolean; autoPurchaseAvailable: boolean } {
+    const entry = this.entries.get(sellerId);
+    const freshPurchase = this.creditTracker.isInFreshPurchaseWindow(sellerId, this.now());
+    const autoPurchaseAvailable = this.creditTracker.canAutoPurchase(this.now());
+    return { entry, freshPurchase, autoPurchaseAvailable };
+  }
+
+  /**
+   * Manually mark an entry as `open`. Used by the registry loop when a
+   * seller is removed from the registry: the entry lingers for a grace
+   * period but is unreachable, so opening the circuit prevents any
+   * further selection.
+   */
+  markOpen(sellerId: string, reason: string, now: number = this.now()): void {
+    const entry = this.entries.get(sellerId);
+    if (!entry) {
+      return;
+    }
+    this.entries.set(sellerId, { ...entry, circuit: "open", lastFailAt: now });
+    logger.warn("pool.circuit_force_opened", "seller pool entry forced to circuit_open", {
+      sellerId,
+      reason
+    });
+  }
+
+  /**
+   * List all known pool entries. Used by `tb doctor` and tests.
+   */
+  snapshot(): PoolEntry[] {
+    return Array.from(this.entries.values()).map((entry) => ({ ...entry, recentFailures: [...entry.recentFailures] }));
+  }
+
+  size(): number {
+    return this.entries.size;
+  }
+
+  private maybeRecycleFromOpen(entry: PoolEntry, now: number): PoolEntry {
+    if (entry.circuit !== "open") {
+      return entry;
+    }
+    if (now - entry.lastFailAt < this.openStateMs) {
+      return entry;
+    }
+    const recycled: PoolEntry = { ...entry, circuit: "half_open" };
+    this.entries.set(entry.sellerId, recycled);
+    logger.info("pool.circuit_half_opened", "seller pool entry recycled to half_open", {
+      sellerId: entry.sellerId,
+      openStateMs: this.openStateMs
+    });
+    return recycled;
+  }
+}
+
+function asResolution(resolved: { modelId: string; matched: boolean; sellers: RegistrySeller[]; missingModelsFlag: number }): ModelIndexResolution {
+  return {
+    modelId: resolved.modelId,
+    matched: resolved.matched,
+    candidates: resolved.sellers,
+    missingModelsFlag: resolved.missingModelsFlag
+  };
+}
+
+export type { PrewarmEntry };

package/src/stream-failover.test.ts

@@ -0,0 +1,52 @@
+import { STREAM_FAILOVER_RETRY_HINT, StreamFailover } from "../src/stream-failover.js";
+
+describe("StreamFailover", () => {
+  test("fresh state reports no chunks committed", () => {
+    const sf = new StreamFailover();
+    expect(sf.snapshot()).toEqual({ firstChunkCommitted: false, bytesFlushed: 0 });
+  });
+
+  test("markFirstChunkCommitted transitions once and only once", () => {
+    const sf = new StreamFailover();
+    sf.markFirstChunkCommitted();
+    sf.markFirstChunkCommitted();
+    expect(sf.snapshot().firstChunkCommitted).toBe(true);
+  });
+
+  test("recordBytesWritten accumulates flushed bytes", () => {
+    const sf = new StreamFailover();
+    sf.recordBytesWritten(128);
+    sf.recordBytesWritten(64);
+    expect(sf.snapshot().bytesFlushed).toBe(192);
+  });
+
+  test("decideOnStreamAbort before first chunk defers to the controller", () => {
+    const sf = new StreamFailover();
+    const decision = sf.decideOnStreamAbort("upstream_reset");
+    expect(decision.action).toBe("let_stream_complete");
+    expect(decision.retryHintValue).toBe("0");
+  });
+
+  test("decideOnStreamAbort after first chunk aborts and surfaces retry hint", () => {
+    const sf = new StreamFailover();
+    sf.markFirstChunkCommitted();
+    sf.recordBytesWritten(2048);
+    const decision = sf.decideOnStreamAbort("upstream_reset");
+    expect(decision.action).toBe("abort_with_retry_hint");
+    expect(decision.retryHintValue).toBe(STREAM_FAILOVER_RETRY_HINT);
+    expect(decision.bytesFlushed).toBe(2048);
+  });
+
+  test("reset clears the chunk and byte counters", () => {
+    const sf = new StreamFailover();
+    sf.markFirstChunkCommitted();
+    sf.recordBytesWritten(999);
+    sf.reset();
+    expect(sf.snapshot()).toEqual({ firstChunkCommitted: false, bytesFlushed: 0 });
+  });
+
+  test("default header name is X-TokenBuddy-Retry-Hint and is overridable", () => {
+    expect(new StreamFailover().headerName).toBe("X-TokenBuddy-Retry-Hint");
+    expect(new StreamFailover({ retryHintHeader: "X-Custom-Retry" }).headerName).toBe("X-Custom-Retry");
+  });
+});