@tokenbuddy/tokenbuddy 1.0.5 → 1.0.7

package/src/seller-catalog.ts

@@ -0,0 +1,222 @@
+import { createModuleLogger } from "@tokenbuddy/logging";
+
+const logger = createModuleLogger("tb-proxyd");
+
+export type ProtocolPreference = "chat_completions" | "responses" | "messages";
+
+export interface RegistrySeller {
+  id: string;
+  name?: string;
+  url: string;
+  supportedProtocols?: string[];
+  paymentMethods?: string[];
+}
+
+export interface SellerRegistryDocument {
+  version: number;
+  defaultSeller?: string;
+  sellers: RegistrySeller[];
+}
+
+export interface SellerManifest {
+  sellerId?: string;
+  seller_id?: string;
+  supportedProtocols?: string[];
+  supported_protocols?: string[];
+  paymentMethods?: string[];
+  payment_methods?: string[];
+  models?: ManifestModelRecord[];
+  selection?: {
+    discountRatio?: number;
+    discount_ratio?: number;
+  };
+}
+
+export interface ManifestModelRecord {
+  id: string;
+  inputPriceMicrosPer1m?: number;
+  outputPriceMicrosPer1m?: number;
+  input_price_micros_per_1m?: number;
+  output_price_micros_per_1m?: number;
+  [key: string]: unknown;
+}
+
+export interface ModelCatalogEntry {
+  id: string;
+  sellerId: string;
+  sellerName?: string;
+  sellerUrl: string;
+  supportedProtocols: string[];
+  paymentMethods: string[];
+  inputPriceMicrosPer1m?: number;
+  outputPriceMicrosPer1m?: number;
+}
+
+export interface SellerCatalogEntry {
+  id: string;
+  name?: string;
+  url: string;
+  status: string;
+  manifestSellerId?: string;
+  discountRatio?: number;
+  modelCount?: number;
+  supportedProtocols?: string[];
+  paymentMethods?: string[];
+  errorMessage?: string;
+}
+
+export interface SellerCatalogResult {
+  registryUrl: string;
+  version: number;
+  defaultSeller?: string;
+  models: ModelCatalogEntry[];
+  sellers: SellerCatalogEntry[];
+}
+
+export type SellerRoutingMode = "auto" | "fixed";
+
+export interface SellerRoutingPreference {
+  mode: SellerRoutingMode;
+  sellerId?: string;
+}
+
+export function normalizeSellerUrl(seller: RegistrySeller): string {
+  return seller.url.replace(/\/+$/, "");
+}
+
+export function manifestProtocols(manifest: SellerManifest, seller: RegistrySeller): string[] {
+  const protocols = manifest.supportedProtocols || manifest.supported_protocols || seller.supportedProtocols || [];
+  return protocols.includes("anthropic_messages") && !protocols.includes("messages")
+    ? [...protocols, "messages"]
+    : protocols;
+}
+
+export function manifestPaymentMethods(manifest: SellerManifest, seller: RegistrySeller): string[] {
+  return manifest.paymentMethods || manifest.payment_methods || seller.paymentMethods || [];
+}
+
+export function manifestModelIds(manifest: SellerManifest): string[] {
+  return (manifest.models || [])
+    .map((model) => model.id)
+    .filter((id): id is string => typeof id === "string" && id.trim().length > 0)
+    .map((id) => id.trim());
+}
+
+function numericPriceField(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function manifestModels(manifest: SellerManifest): ManifestModelRecord[] {
+  return (manifest.models || [])
+    .filter((model): model is ManifestModelRecord => Boolean(model?.id && typeof model.id === "string"));
+}
+
+export async function fetchSellerRegistry(registryUrl: string): Promise<SellerRegistryDocument> {
+  const response = await fetch(registryUrl);
+  if (!response.ok) {
+    throw new Error(`registry returned ${response.status}`);
+  }
+  const data = await response.json() as SellerRegistryDocument;
+  if (!data || !Array.isArray(data.sellers)) {
+    throw new Error("registry response missing sellers");
+  }
+  return data;
+}
+
+export async function fetchSellerManifest(seller: RegistrySeller): Promise<SellerManifest> {
+  const response = await fetch(`${normalizeSellerUrl(seller)}/manifest`);
+  if (!response.ok) {
+    throw new Error(`manifest returned ${response.status}`);
+  }
+  return await response.json() as SellerManifest;
+}
+
+export async function discoverSellerBackedModels(registryUrl: string): Promise<SellerCatalogResult> {
+  const registry = await fetchSellerRegistry(registryUrl);
+  const sellerResults = await Promise.all(registry.sellers.map(async (seller) => {
+    try {
+      const manifest = await fetchSellerManifest(seller);
+      const protocols = manifestProtocols(manifest, seller);
+      const paymentMethods = manifestPaymentMethods(manifest, seller);
+      const models = manifestModels(manifest).map((model) => ({
+        id: model.id.trim(),
+        sellerId: seller.id,
+        sellerName: seller.name,
+        sellerUrl: seller.url,
+        supportedProtocols: protocols,
+        paymentMethods,
+        inputPriceMicrosPer1m: numericPriceField(model.inputPriceMicrosPer1m) ?? numericPriceField(model.input_price_micros_per_1m),
+        outputPriceMicrosPer1m: numericPriceField(model.outputPriceMicrosPer1m) ?? numericPriceField(model.output_price_micros_per_1m),
+      }));
+      return {
+        seller: {
+          id: seller.id,
+          name: seller.name,
+          url: seller.url,
+          status: "ok",
+          manifestSellerId: manifest.sellerId || manifest.seller_id || seller.id,
+          discountRatio: manifest.selection?.discountRatio ?? manifest.selection?.discount_ratio,
+          modelCount: models.length,
+          supportedProtocols: protocols,
+          paymentMethods,
+        },
+        models
+      };
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.warn("models.refresh.seller_failed", "seller manifest refresh failed", {
+        sellerId: seller.id,
+        errorMessage
+      });
+      return {
+        seller: {
+          id: seller.id,
+          name: seller.name,
+          url: seller.url,
+          status: "failed",
+          errorMessage
+        },
+        models: [] as ModelCatalogEntry[]
+      };
+    }
+  }));
+
+  return {
+    registryUrl,
+    version: registry.version,
+    defaultSeller: registry.defaultSeller,
+    models: sellerResults.flatMap((entry) => entry.models),
+    sellers: sellerResults.map((entry) => entry.seller)
+  };
+}
+
+export function filterCatalogByProtocol(
+  models: ModelCatalogEntry[],
+  protocol: ProtocolPreference
+): ModelCatalogEntry[] {
+  return models.filter((entry) => entry.supportedProtocols.includes(protocol));
+}
+
+export function filterCatalogBySeller(
+  models: ModelCatalogEntry[],
+  sellerId: string | undefined
+): ModelCatalogEntry[] {
+  if (!sellerId) {
+    return models;
+  }
+  return models.filter((entry) => entry.sellerId === sellerId);
+}
+
+export function dedupeCatalogEntries(models: ModelCatalogEntry[]): ModelCatalogEntry[] {
+  const seen = new Set<string>();
+  const output: ModelCatalogEntry[] = [];
+  for (const entry of models) {
+    const key = `${entry.sellerId}:${entry.id}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    output.push(entry);
+  }
+  return output;
+}

package/src/tb-proxyd.ts

@@ -9,13 +9,15 @@ const controlPort = parsePortEnv("TB_PROXYD_CONTROL_PORT", 17820);
 const proxyPort = parsePortEnv("TB_PROXYD_PROXY_PORT", 17821);
 const sellerRegistryUrl = process.env.TB_PROXYD_SELLER_REGISTRY_URL || "https://tb-wallet-bootstrap.fly.dev/registry/sellers";
 const selectionMode = parseSelectionModeEnv();
+const selectedSellerId = parseSelectedSellerIdEnv();
 
 const daemon = new TokenbuddyDaemon({
   controlPort,
   proxyPort,
   dbPath,
   sellerRegistryUrl,
-  selectionMode
+  selectionMode,
+  selectedSellerId
 });
 
 logger.info("proxy.process.initializing", "tb-proxyd process initializing", {
@@ -23,7 +25,8 @@ logger.info("proxy.process.initializing", "tb-proxyd process initializing", {
   controlPort,
   proxyPort,
   sellerRegistryUrl,
-  selectionMode
+  selectionMode,
+  selectedSellerId
 });
 daemon.start();
 
@@ -58,3 +61,12 @@ function parseSelectionModeEnv(): "auto" | "manual" {
   }
   throw new Error("TB_PROXYD_SELECTION_MODE must be auto or manual");
 }
+
+function parseSelectedSellerIdEnv(): string | undefined {
+  const rawValue = process.env.TB_PROXYD_SELECTED_SELLER_ID;
+  if (!rawValue) {
+    return undefined;
+  }
+  const trimmed = rawValue.trim();
+  return trimmed || undefined;
+}

package/src/terminal-image.ts

@@ -0,0 +1,187 @@
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+
+type TerminalEnv = Readonly<Record<string, string | undefined>>;
+
+export type TerminalImageDisplayMethod =
+  | "inline-iterm"
+  | "inline-kitty"
+  | "system-open"
+  | "manual";
+
+export interface TerminalImageDisplayResult {
+  method: TerminalImageDisplayMethod;
+  displayed: boolean;
+  message: string;
+  fallbackCommand?: string;
+}
+
+export interface DisplayTerminalImageOptions {
+  env?: TerminalEnv;
+  platform?: NodeJS.Platform;
+  stdoutIsTTY?: boolean;
+  write?: (chunk: string) => void;
+  runCommand?: (command: string, args: string[]) => Promise<void>;
+  fileExists?: (filePath: string) => boolean;
+  readFile?: (filePath: string) => Buffer;
+}
+
+type InlineImageProtocol = "iterm" | "kitty";
+
+function defaultRunCommand(command: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: "ignore",
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`${command} exited with ${code}`));
+    });
+  });
+}
+
+function terminalSupportsInlineImages(
+  env: TerminalEnv,
+  stdoutIsTTY: boolean,
+): InlineImageProtocol | undefined {
+  if (!stdoutIsTTY) {
+    return undefined;
+  }
+
+  const term = env.TERM || "";
+  if (env.KITTY_WINDOW_ID || term.includes("xterm-kitty")) {
+    return "kitty";
+  }
+
+  const termProgram = env.TERM_PROGRAM || "";
+  if (termProgram === "iTerm.app" || termProgram === "WezTerm" || env.WEZTERM_EXECUTABLE) {
+    return "iterm";
+  }
+
+  return undefined;
+}
+
+function basenameBase64(filePath: string): string {
+  return Buffer.from(path.basename(filePath), "utf8").toString("base64");
+}
+
+function itermInlineImageSequence(filePath: string, image: Buffer): string {
+  const payload = image.toString("base64");
+  return `\u001B]1337;File=name=${basenameBase64(filePath)};inline=1;width=60%;preserveAspectRatio=1:${payload}\u0007\n`;
+}
+
+function kittyInlineImageSequence(filePath: string): string {
+  const payload = Buffer.from(filePath, "utf8").toString("base64");
+  return `\u001B_Ga=T,t=f,f=100,c=60;${payload}\u001B\\\n`;
+}
+
+function openCommandForPlatform(platform: NodeJS.Platform, filePath: string): { command: string; args: string[]; label: string } | undefined {
+  if (platform === "darwin") {
+    return {
+      command: "open",
+      args: [filePath],
+      label: `open ${filePath}`,
+    };
+  }
+  if (platform === "linux") {
+    return {
+      command: "xdg-open",
+      args: [filePath],
+      label: `xdg-open ${filePath}`,
+    };
+  }
+  if (platform === "win32") {
+    return {
+      command: "cmd",
+      args: ["/c", "start", "", filePath],
+      label: `start ${filePath}`,
+    };
+  }
+  return undefined;
+}
+
+export function detectTerminalImageDisplay(
+  options: DisplayTerminalImageOptions = {},
+): InlineImageProtocol | undefined {
+  return terminalSupportsInlineImages(
+    options.env || process.env,
+    options.stdoutIsTTY ?? Boolean(process.stdout.isTTY),
+  );
+}
+
+export async function displayTerminalImage(
+  filePath: string,
+  options: DisplayTerminalImageOptions = {},
+): Promise<TerminalImageDisplayResult> {
+  const fileExists = options.fileExists || fs.existsSync;
+  const readFile = options.readFile || fs.readFileSync;
+  const write = options.write || ((chunk: string) => process.stdout.write(chunk));
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const stdoutIsTTY = options.stdoutIsTTY ?? Boolean(process.stdout.isTTY);
+  const openCommand = openCommandForPlatform(platform, filePath);
+  const fallbackCommand = openCommand?.label;
+
+  if (!fileExists(filePath)) {
+    return {
+      method: "manual",
+      displayed: false,
+      fallbackCommand,
+      message: `QR image file is missing: ${filePath}`,
+    };
+  }
+
+  const inlineProtocol = terminalSupportsInlineImages(env, stdoutIsTTY);
+  if (inlineProtocol === "kitty") {
+    write(kittyInlineImageSequence(filePath));
+    return {
+      method: "inline-kitty",
+      displayed: true,
+      fallbackCommand,
+      message: "Displayed the ClawTip wallet QR image inline using the Kitty graphics protocol.",
+    };
+  }
+
+  if (inlineProtocol === "iterm") {
+    write(itermInlineImageSequence(filePath, readFile(filePath)));
+    return {
+      method: "inline-iterm",
+      displayed: true,
+      fallbackCommand,
+      message: "Displayed the ClawTip wallet QR image inline using the iTerm2 image protocol.",
+    };
+  }
+
+  if (openCommand) {
+    try {
+      const runCommand = options.runCommand || defaultRunCommand;
+      await runCommand(openCommand.command, openCommand.args);
+      return {
+        method: "system-open",
+        displayed: true,
+        fallbackCommand,
+        message: `Opened the ClawTip wallet QR image with the system image viewer: ${openCommand.label}`,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        method: "manual",
+        displayed: false,
+        fallbackCommand,
+        message: `Could not open QR image automatically: ${message}`,
+      };
+    }
+  }
+
+  return {
+    method: "manual",
+    displayed: false,
+    fallbackCommand,
+    message: "This terminal does not advertise inline image support and no system opener is available.",
+  };
+}

package/tests/e2e.test.ts

@@ -1,6 +1,7 @@
 import { buildApp as buildBootstrapApp } from "../../wallet-bootstrap/src/server.js";
 import { buildSellerApp } from "../../seller/src/server.js";
 import { TokenbuddyDaemon } from "../src/daemon.js";
+import { BuyerStore } from "../src/buyer-store.js";
 import { AdminClient } from "../../admin-cli/src/client.js";
 import * as path from "path";
 import * as fs from "fs";
@@ -39,6 +40,14 @@ describe("TokenBuddy Full End-to-End Integration Flow Tests", () => {
     if (fs.existsSync(TEMP_BUYER_DB)) {
       try { fs.unlinkSync(TEMP_BUYER_DB); } catch (e) {}
     }
+    const buyerStore = new BuyerStore({ dbPath: TEMP_BUYER_DB });
+    buyerStore.savePayment({
+      method: "mock",
+      enabled: true,
+      isDefault: true,
+      config: { channel: "e2e-test" }
+    });
+    buyerStore.close();
 
     // 1. Launch Mock Upstream OpenAI completions server
     upstreamServer = http.createServer((req, res) => {
@@ -234,6 +243,32 @@ describe("TokenBuddy Full End-to-End Integration Flow Tests", () => {
 
     verifyDb.close();
 
+    const buyerAfterConcurrent = new BuyerStore({ dbPath: TEMP_BUYER_DB });
+    try {
+      const tokenCache = buyerAfterConcurrent.getToken("seller-e2e-node");
+      expect(tokenCache).toMatchObject({
+        balanceMicros: 1999450,
+        reservedMicros: 0,
+        spentMicros: 550,
+        balanceSource: "seller_settlement_summary"
+      });
+      const inferenceLedger = buyerAfterConcurrent.listInferenceLedger();
+      expect(inferenceLedger.filter((entry) => entry.requestId.startsWith("req_p_"))).toHaveLength(5);
+      expect(inferenceLedger).toEqual(expect.arrayContaining([
+        expect.objectContaining({
+          requestId: "req_p_1",
+          billedMicros: 110,
+          estimatedMicros: 200,
+          settledMicros: 110,
+          settledUsdMicros: 110,
+          priceVersion: "openrouter_usd.v1",
+          balanceSource: "seller_authoritative"
+        })
+      ]));
+    } finally {
+      buyerAfterConcurrent.close();
+    }
+
     // Step 7: Fire subsequent inference request and assert it HITS local daemon token cache immediately (Zero-Purchase)
     // We capture time elapsed to verify cache speed
     const start = Date.now();
@@ -251,14 +286,62 @@ describe("TokenBuddy Full End-to-End Integration Flow Tests", () => {
     expect(purchaseCount).toBe(1);
     verifyDb2.close();
 
-    // Step 8: Verify newly implemented admin query billing APIs (purchases & requests)
+    // Step 8: Force seller-authoritative insufficiency while buyer cache still looks funded.
+    // The daemon must refresh /v1/balance, auto-purchase once, and retry the same request idempotently.
+    const forcedDb = new DatabaseSync(TEMP_SELLER_DB);
+    const oldCredential = forcedDb.prepare("SELECT credential_id FROM credentials ORDER BY created_at ASC LIMIT 1").get() as any;
+    forcedDb.prepare("UPDATE credentials SET credit_balance_micros = 1, reserved_micros = 0 WHERE credential_id = ?").run(oldCredential.credential_id);
+    forcedDb.prepare("UPDATE tokens SET credit_balance_micros = 1, reserved_micros = 0 WHERE credential_id = ?").run(oldCredential.credential_id);
+    forcedDb.close();
+    const buyerBefore402 = new BuyerStore({ dbPath: TEMP_BUYER_DB });
+    try {
+      const cached = buyerBefore402.getToken("seller-e2e-node");
+      expect(cached?.balanceMicros).toBeGreaterThan(200000);
+    } finally {
+      buyerBefore402.close();
+    }
+
+    const retryResponse = await sendProxyRequest("req_402_rebuy_retry");
+    expect(retryResponse.ok).toBe(true);
+    const retryData = await retryResponse.json() as any;
+    expect(retryData.id).toBe("chatcmpl-e2e-ok");
+
+    const verifyDb3 = new DatabaseSync(TEMP_SELLER_DB);
+    const purchaseCountAfterRetry = (verifyDb3.prepare("SELECT COUNT(*) as count FROM purchases").get() as any).count;
+    const retryRows = verifyDb3.prepare("SELECT state, settled_micros FROM requests WHERE request_id = ?").all("req_402_rebuy_retry") as any[];
+    expect(purchaseCountAfterRetry).toBe(2);
+    expect(retryRows).toEqual([
+      expect.objectContaining({ state: "settled", settled_micros: 110 })
+    ]);
+    verifyDb3.close();
+
+    const buyerAfterRetry = new BuyerStore({ dbPath: TEMP_BUYER_DB });
+    try {
+      expect(buyerAfterRetry.listInferenceLedger()).toEqual(expect.arrayContaining([
+        expect.objectContaining({
+          requestId: "req_402_rebuy_retry",
+          billedMicros: 110,
+          estimatedMicros: 200,
+          settledMicros: 110,
+          balanceSource: "seller_authoritative"
+        })
+      ]));
+      expect(buyerAfterRetry.getToken("seller-e2e-node")).toMatchObject({
+        balanceMicros: 1999890,
+        balanceSource: "seller_settlement_summary"
+      });
+    } finally {
+      buyerAfterRetry.close();
+    }
+
+    // Step 9: Verify newly implemented admin query billing APIs (purchases & requests)
     const billingPurchases = await admin.get("/operator/admin/purchases");
-    expect(billingPurchases.purchases.length).toBe(1);
-    expect(billingPurchases.purchases[0].state).toBe("funded");
+    expect(billingPurchases.purchases.length).toBe(2);
+    expect(billingPurchases.purchases.every((purchase: any) => purchase.state === "funded")).toBe(true);
 
     const billingRequests = await admin.get("/operator/admin/requests");
-    // 5 concurrent requests + 1 subsequent hit = 6 total inference requests tracked on seller database
-    expect(billingRequests.requests.length).toBe(6);
+    // 5 concurrent requests + 1 cache hit + 1 retry-after-402 request = 7 settled inference requests.
+    expect(billingRequests.requests.length).toBe(7);
     expect(billingRequests.requests.every((r: any) => r.state === "settled")).toBe(true);
   });
 });