@tokenbuddy/tokenbuddy 1.0.6 → 1.0.8

package/src/daemon.ts

@@ -52,6 +52,34 @@ interface UsageSummary {
   billedMicros: number;
 }
 
+interface SellerSettlementSummary {
+  requestId: string;
+  settledMicros: number;
+  settledUsdMicros?: number;
+  remainingCreditMicros: number;
+  reservedBalanceMicros?: number;
+  spentMicros?: number;
+  priceVersion?: string;
+}
+
+interface SellerBalanceSnapshot {
+  creditMicros: number;
+  reservedMicros: number;
+  spentMicros: number;
+  availableMicros: number;
+}
+
+function numericHeaderField(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
 interface ResponsesStreamState {
   itemId: string;
   text: string;
@@ -271,6 +299,83 @@ class ResponsesStreamNormalizer {
   }
 }
 
+class SellerSettlementStreamExtractor {
+  private pending = "";
+  private settlement: SellerSettlementSummary | undefined;
+
+  public push(chunk: string): string {
+    this.pending += chunk;
+    const blocks = this.pending.split("\n\n");
+    this.pending = blocks.pop() || "";
+    return blocks
+      .map((block) => this.processBlock(block))
+      .filter((block) => block.length > 0)
+      .join("\n\n");
+  }
+
+  public finish(): { downstream: string; settlement: SellerSettlementSummary | undefined } {
+    const downstream = this.pending.trim() ? this.processBlock(this.pending) : "";
+    this.pending = "";
+    return { downstream, settlement: this.settlement };
+  }
+
+  public current(): SellerSettlementSummary | undefined {
+    return this.settlement;
+  }
+
+  private processBlock(block: string): string {
+    if (!block.trim()) {
+      return "";
+    }
+    const lines = block.split("\n");
+    const eventLine = lines.find((line) => line.startsWith("event:"));
+    const eventName = eventLine?.replace(/^event:\s?/, "").trim();
+    if (eventName !== "tokenbuddy.settlement") {
+      return block;
+    }
+    const dataLine = lines.find((line) => line.startsWith("data:"));
+    if (!dataLine) {
+      return "";
+    }
+    const parsed = parseSellerSettlementObject(dataLine.replace(/^data:\s?/, ""));
+    if (parsed) {
+      this.settlement = parsed;
+    }
+    return "";
+  }
+}
+
+function parseSellerSettlementObject(raw: string): SellerSettlementSummary | undefined {
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const requestId = typeof parsed.requestId === "string"
+      ? parsed.requestId
+      : typeof parsed.request_id === "string"
+        ? parsed.request_id
+        : undefined;
+    const settledMicros = numericHeaderField(parsed.settledMicros ?? parsed.settled_micros);
+    const remainingCreditMicros = numericHeaderField(parsed.remainingCreditMicros ?? parsed.remaining_credit_micros);
+    if (!requestId || settledMicros === undefined || remainingCreditMicros === undefined) {
+      return undefined;
+    }
+    return {
+      requestId,
+      settledMicros,
+      settledUsdMicros: numericHeaderField(parsed.settledUsdMicros ?? parsed.settled_usd_micros),
+      remainingCreditMicros,
+      reservedBalanceMicros: numericHeaderField(parsed.reservedBalanceMicros ?? parsed.reserved_balance_micros),
+      spentMicros: numericHeaderField(parsed.spentMicros ?? parsed.spent_micros),
+      priceVersion: typeof parsed.priceVersion === "string"
+        ? parsed.priceVersion
+        : typeof parsed.price_version === "string"
+          ? parsed.price_version
+          : undefined
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 interface PurchaseCreateResponse {
   purchaseId?: string;
   purchase_id?: string;
@@ -588,6 +693,138 @@ export class TokenbuddyDaemon {
     }
   }
 
+  private parseSellerSettlementSummary(headers: Headers): SellerSettlementSummary | undefined {
+    const raw = headers.get("x-tokenbuddy-settlement");
+    if (!raw) {
+      return undefined;
+    }
+    return parseSellerSettlementObject(raw);
+  }
+
+  private recordReconciledInference(
+    route: SellerRoute,
+    endpoint: string,
+    requestId: string,
+    usage: UsageSummary,
+    settlement: SellerSettlementSummary | undefined,
+    prompt: string | undefined,
+    response?: string
+  ): void {
+    if (settlement) {
+      this.tokenStore.reconcileTokenBalance({
+        sellerKey: route.seller.id,
+        balanceMicros: settlement.remainingCreditMicros,
+        reservedMicros: settlement.reservedBalanceMicros ?? 0,
+        spentMicros: settlement.spentMicros ?? 0,
+        balanceSource: "seller_settlement_summary"
+      });
+    }
+
+    const settledMicros = settlement?.settledMicros;
+    this.tokenStore.recordInferenceLedger({
+      requestId: settlement?.requestId || requestId,
+      sellerKey: route.seller.id,
+      modelId: route.modelId,
+      endpoint,
+      status: settlement ? "settled" : "estimated",
+      promptTokens: usage.promptTokens,
+      completionTokens: usage.completionTokens,
+      billedMicros: settledMicros ?? usage.billedMicros,
+      estimatedMicros: usage.billedMicros,
+      settledMicros,
+      settledUsdMicros: settlement?.settledUsdMicros,
+      priceVersion: settlement?.priceVersion,
+      balanceSnapshotMicros: settlement?.remainingCreditMicros,
+      balanceSource: settlement ? "seller_authoritative" : "estimated",
+      prompt,
+      response
+    });
+    logger.info("inference.ledger.recorded", "safe inference ledger recorded", {
+      requestId: settlement?.requestId || requestId,
+      sellerKey: route.seller.id,
+      model: route.modelId,
+      endpoint,
+      status: settlement ? "settled" : "estimated",
+      estimatedMicros: usage.billedMicros,
+      settledMicros,
+      balanceSource: settlement ? "seller_authoritative" : "estimated"
+    });
+  }
+
+  private async refreshSellerBalance(route: SellerRoute, token: string, balanceSource: string): Promise<SellerBalanceSnapshot | undefined> {
+    const sellerKey = route.seller.id;
+    const sellerUrl = normalizeSellerUrl(route.seller);
+    const response = await fetch(`${sellerUrl}/v1/balance`, {
+      headers: { "Authorization": `Bearer ${token}` }
+    });
+    if (!response.ok) {
+      logger.warn("token.balance_refresh.failed", "seller balance refresh failed", {
+        sellerKey,
+        model: route.modelId,
+        status: response.status
+      });
+      return undefined;
+    }
+    const data = await response.json() as Record<string, unknown>;
+    const creditMicros = numericHeaderField(data.creditMicros ?? data.credit_micros) ?? 0;
+    const reservedMicros = numericHeaderField(data.reservedMicros ?? data.reserved_micros) ?? 0;
+    const spentMicros = numericHeaderField(data.spentMicros ?? data.spent_micros) ?? 0;
+    const snapshot = {
+      creditMicros,
+      reservedMicros,
+      spentMicros,
+      availableMicros: Math.max(0, creditMicros - reservedMicros)
+    };
+    this.tokenStore.reconcileTokenBalance({
+      sellerKey,
+      balanceMicros: snapshot.availableMicros,
+      reservedMicros,
+      spentMicros,
+      balanceSource
+    });
+    logger.info("token.balance_refresh.succeeded", "seller balance refreshed", {
+      sellerKey,
+      model: route.modelId,
+      availableMicros: snapshot.availableMicros,
+      reservedMicros,
+      spentMicros,
+      balanceSource
+    });
+    return snapshot;
+  }
+
+  private isInsufficientFundsResponse(status: number, bodyText: string): boolean {
+    if (status !== 402) {
+      return false;
+    }
+    try {
+      const parsed = JSON.parse(bodyText) as { error?: { code?: string; message?: string } };
+      const code = parsed.error?.code || "";
+      const message = parsed.error?.message || "";
+      return code === "insufficient_funds" || /insufficient funds/i.test(message);
+    } catch {
+      return /insufficient funds/i.test(bodyText);
+    }
+  }
+
+  private async recoverFromInsufficientFunds(route: SellerRoute, token: string): Promise<string> {
+    const sellerKey = route.seller.id;
+    this.tokenStore.markTokenStale(sellerKey);
+    const snapshot = await this.refreshSellerBalance(route, token, "seller_402_refresh");
+    const rebuyMinBalanceMicros = this.tokenRebuyMinBalanceMicros();
+    if (!snapshot || snapshot.availableMicros <= rebuyMinBalanceMicros) {
+      logger.info("purchase.retry_after_402.started", "seller 402 triggered one-shot auto purchase retry", {
+        sellerKey,
+        model: route.modelId,
+        availableMicros: snapshot?.availableMicros ?? 0,
+        rebuyMinBalanceMicros
+      });
+      return await this.getOrPurchaseToken(route);
+    }
+    const cached = this.tokenStore.getToken(sellerKey);
+    return cached?.token || token;
+  }
+
   private inferPromptForHash(body: unknown): string | undefined {
     if (!body || typeof body !== "object") {
       return undefined;
@@ -930,21 +1167,12 @@ export class TokenbuddyDaemon {
             endpoint,
             stream: Boolean((body as { stream?: unknown }).stream)
           });
-          const token = await this.getOrPurchaseToken(route);
           const sellerUrl = normalizeSellerUrl(route.seller);
           const upstreamBody = this.applyResolvedModelToBody(endpoint, {
             ...(body as Record<string, unknown>),
             requestId
           }, modelId);
-
-          logger.info("proxy.upstream_fetch.started", "proxy upstream fetch started", {
-            requestId,
-            sellerKey,
-            model: modelId,
-            endpoint,
-            stream: Boolean((body as { stream?: unknown }).stream)
-          });
-          const upstreamResponse = await fetch(`${sellerUrl}${endpoint}`, {
+          const sendSellerRequest = async (token: string) => fetch(`${sellerUrl}${endpoint}`, {
             method: "POST",
             headers: {
               "Content-Type": "application/json",
@@ -955,8 +1183,45 @@ export class TokenbuddyDaemon {
             body: JSON.stringify(upstreamBody)
           });
 
+          logger.info("proxy.upstream_fetch.started", "proxy upstream fetch started", {
+            requestId,
+            sellerKey,
+            model: modelId,
+            endpoint,
+            stream: Boolean((body as { stream?: unknown }).stream)
+          });
+          let token = await this.getOrPurchaseToken(route);
+          let upstreamResponse = await sendSellerRequest(token);
+
           if (!upstreamResponse.ok) {
             const errorBody = await upstreamResponse.text();
+            if (this.isInsufficientFundsResponse(upstreamResponse.status, errorBody)) {
+              token = await this.recoverFromInsufficientFunds(route, token);
+              upstreamResponse = await sendSellerRequest(token);
+              if (upstreamResponse.ok) {
+                logger.info("proxy.retry_after_402.succeeded", "seller request succeeded after one-shot auto purchase retry", {
+                  requestId,
+                  sellerKey,
+                  model: modelId,
+                  endpoint,
+                  durationMs: Date.now() - startedAt
+                });
+              } else {
+                const retryErrorBody = await upstreamResponse.text();
+                logger.warn("proxy.retry_after_402.failed", "seller request still failed after one-shot auto purchase retry", {
+                  requestId,
+                  sellerKey,
+                  model: modelId,
+                  endpoint,
+                  status: upstreamResponse.status,
+                  durationMs: Date.now() - startedAt
+                });
+                this.copyUpstreamHeaders(upstreamResponse, res);
+                res.status(upstreamResponse.status);
+                res.send(retryErrorBody);
+                return;
+              }
+            } else {
             logger.warn("proxy.upstream_fetch.failed", "proxy upstream fetch returned non-ok status", {
               requestId,
               sellerKey,
@@ -974,6 +1239,7 @@ export class TokenbuddyDaemon {
             res.status(upstreamResponse.status);
             res.send(errorBody);
             return;
+            }
           }
 
           this.copyUpstreamHeaders(upstreamResponse, res);
@@ -997,20 +1263,36 @@ export class TokenbuddyDaemon {
             let bytes = 0;
             const decoder = new TextDecoder();
             const responsesStreamNormalizer = new ResponsesStreamNormalizer();
+            const settlementExtractor = new SellerSettlementStreamExtractor();
             while (true) {
               const { done, value } = await reader.read();
               if (done) {
                 break;
               }
               bytes += value.byteLength;
+              const chunk = decoder.decode(value, { stream: true });
+              const sellerChunk = settlementExtractor.push(chunk);
+              if (sellerChunk.length === 0) {
+                continue;
+              }
               if (endpoint === "/v1/responses") {
-                const chunk = decoder.decode(value, { stream: true });
-                const normalized = responsesStreamNormalizer.push(chunk);
+                const normalized = responsesStreamNormalizer.push(sellerChunk);
                 if (normalized.length > 0) {
                   res.write(`${normalized}\n\n`);
                 }
               } else {
-                res.write(Buffer.from(value));
+                res.write(sellerChunk);
+              }
+            }
+            const settlementTrailing = settlementExtractor.finish();
+            if (settlementTrailing.downstream.length > 0) {
+              if (endpoint === "/v1/responses") {
+                const normalized = responsesStreamNormalizer.push(settlementTrailing.downstream);
+                if (normalized.length > 0) {
+                  res.write(`${normalized}\n\n`);
+                }
+              } else {
+                res.write(settlementTrailing.downstream);
               }
             }
             if (endpoint === "/v1/responses") {
@@ -1020,56 +1302,29 @@ export class TokenbuddyDaemon {
               }
             }
             res.end();
-            const billedMicros = Math.max(1, bytes);
-            this.tokenStore.deductBalance(sellerKey, billedMicros);
-            this.tokenStore.recordInferenceLedger({
-              requestId,
-              sellerKey,
-              modelId,
+            this.recordReconciledInference(
+              route,
               endpoint,
-              status: "settled",
-              promptTokens: 0,
-              completionTokens: 0,
-              billedMicros,
-              prompt: this.inferPromptForHash(body)
-            });
-            logger.info("inference.ledger.recorded", "safe inference ledger recorded", {
               requestId,
-              sellerKey,
-              model: modelId,
-              endpoint,
-              status: "settled",
-              billedMicros
-            });
+              { promptTokens: 0, completionTokens: 0, billedMicros: Math.max(1, bytes) },
+              this.parseSellerSettlementSummary(upstreamResponse.headers) ?? settlementTrailing.settlement ?? settlementExtractor.current(),
+              this.inferPromptForHash(body)
+            );
             return;
           }
 
           const responseBody = await upstreamResponse.text();
           res.send(responseBody);
           const usage = this.readUsage(responseBody);
-          this.tokenStore.deductBalance(sellerKey, usage.billedMicros);
-          this.tokenStore.recordInferenceLedger({
-            requestId,
-            sellerKey,
-            modelId,
+          this.recordReconciledInference(
+            route,
             endpoint,
-            status: "settled",
-            promptTokens: usage.promptTokens,
-            completionTokens: usage.completionTokens,
-            billedMicros: usage.billedMicros,
-            prompt: this.inferPromptForHash(body),
-            response: responseBody
-          });
-          logger.info("inference.ledger.recorded", "safe inference ledger recorded", {
             requestId,
-            sellerKey,
-            model: modelId,
-            endpoint,
-            status: "settled",
-            promptTokens: usage.promptTokens,
-            completionTokens: usage.completionTokens,
-            billedMicros: usage.billedMicros
-          });
+            usage,
+            this.parseSellerSettlementSummary(upstreamResponse.headers),
+            this.inferPromptForHash(body),
+            responseBody
+          );
           return;
         } catch (routeError: unknown) {
           lastError = routeError;

package/src/doctor-clawtip-wallet.ts

@@ -0,0 +1,70 @@
+import { BuyerStore } from "./buyer-store.js";
+import {
+  inspectClawtipWalletReadiness,
+  type ClawtipWalletStatus,
+} from "./init-payment-options.js";
+
+export interface DoctorClawtipWalletSummary {
+  status: ClawtipWalletStatus;
+  ready: boolean;
+  paymentMetadataPresent: boolean;
+  walletConfigPresent: boolean;
+  configsDirExists: boolean;
+  expectedPath: string;
+  alternatePaths: string[];
+  message: string;
+}
+
+function clawtipWalletStatusIcon(status: ClawtipWalletStatus): string {
+  if (status === "ready") {
+    return "✅";
+  }
+  if (status === "metadata_missing_wallet") {
+    return "❌";
+  }
+  if (status === "wallet_missing_metadata") {
+    return "🟡";
+  }
+  return "🔘";
+}
+
+export function readDoctorClawtipWallet(): DoctorClawtipWalletSummary {
+  const store = new BuyerStore();
+  try {
+    const readiness = inspectClawtipWalletReadiness(store.getPayment("clawtip"));
+    return {
+      status: readiness.status,
+      ready: readiness.status === "ready",
+      paymentMetadataPresent: Boolean(readiness.savedBinding),
+      walletConfigPresent: readiness.walletConfig.exists,
+      configsDirExists: readiness.walletConfig.configsDirExists,
+      expectedPath: readiness.walletConfig.expectedPath,
+      alternatePaths: readiness.walletConfig.alternatePaths,
+      message: readiness.message,
+    };
+  } finally {
+    store.close();
+  }
+}
+
+export function printDoctorClawtipWallet(
+  wallet: DoctorClawtipWalletSummary,
+  writeLine: (line: string) => void,
+): void {
+  writeLine("\n--- ClawTip Wallet ---");
+  writeLine(`${clawtipWalletStatusIcon(wallet.status)} ClawTip Wallet [${wallet.status}]`);
+  writeLine(`   Payment metadata: ${wallet.paymentMetadataPresent ? "present" : "missing"}`);
+  writeLine(`   Wallet config: ${wallet.walletConfigPresent ? "found" : "missing"}`);
+  writeLine(`   Expected: ${wallet.expectedPath}`);
+  if (wallet.alternatePaths.length > 0) {
+    writeLine(`   Nearby files: ${wallet.alternatePaths.join(", ")}`);
+  }
+  writeLine(`   Notes: ${wallet.message}`);
+  if (wallet.status === "metadata_missing_wallet") {
+    writeLine("   Action: Run `tb init` and choose ClawTip to bind the local wallet again.");
+  } else if (wallet.status === "wallet_missing_metadata") {
+    writeLine("   Action: Run `tb init` and choose ClawTip so TokenBuddy can save payment metadata.");
+  } else if (!wallet.ready) {
+    writeLine("   Action: Run `tb init` and choose ClawTip to bind a wallet before using ClawTip-backed purchases.");
+  }
+}

package/src/doctor-diagnostics.ts

@@ -13,6 +13,11 @@ import {
   type ModelCatalogEntry,
   type SellerCatalogEntry,
 } from "./seller-catalog.js";
+import {
+  printDoctorClawtipWallet,
+  readDoctorClawtipWallet,
+  type DoctorClawtipWalletSummary,
+} from "./doctor-clawtip-wallet.js";
 
 export interface DoctorProviderView extends ProviderCandidate {
   runtimeConfig?: ProviderRuntimeConfig;
@@ -34,6 +39,7 @@ export interface DoctorSellerEntry {
 
 export interface DoctorDiagnostics {
   access: DoctorAccessSummary;
+  clawtipWallet: DoctorClawtipWalletSummary;
   models: DoctorModelsSummary;
   providers: DoctorProviderView[];
   sellers: DoctorSellersSummary;
@@ -749,6 +755,7 @@ export async function collectDoctorDiagnostics(options: DoctorCollectOptions): P
         modelsError: models.error,
       },
     ),
+    clawtipWallet: readDoctorClawtipWallet(),
     models,
     providers: options.providers,
     sellers,
@@ -784,6 +791,7 @@ export async function collectDoctorModelsSummary(options: Omit<DoctorCollectOpti
 
 export async function renderDoctorDiagnosticsProgressively(options: DoctorRenderOptions): Promise<DoctorDiagnostics> {
   const writeLine = options.writeLine || defaultWriter;
+  const clawtipWallet = readDoctorClawtipWallet();
   const fetches = startDoctorFetches(
     options.controlPort,
     options.proxyPort,
@@ -792,6 +800,8 @@ export async function renderDoctorDiagnosticsProgressively(options: DoctorRender
     options.sellerRegistryUrl,
   );
 
+  printDoctorClawtipWallet(clawtipWallet, writeLine);
+
   writeLine("\n--- Access Interfaces ---");
   writeLine("Checking local control plane and proxy endpoints...");
   const [healthResult, proxyModelsResult] = await Promise.all([
@@ -843,6 +853,7 @@ export async function renderDoctorDiagnosticsProgressively(options: DoctorRender
 
   return {
     access,
+    clawtipWallet,
     models,
     providers: options.providers,
     sellers: finalSellers,