fix(credits): close the five accounting holes from review

- Scope the balance's spend aggregation to provider "nodetool": BYOK
  predictions (fal_ai, anthropic, ...) no longer drain credits, and
  historical BYOK spend no longer zeroes new balances. Regression test
  covers mixed managed/BYOK rows.
- Gate the no-payment top-up behind NODETOOL_ENABLE_TEST_TOPUP (off by
  default): the mutation throws FORBIDDEN otherwise, status reports
  testTopupEnabled, and the UI hides the button.
- Direct generate_media now admits against a unit-price estimate,
  reserves it for the duration of the call, and records a prediction row
  (max of delegate-tracked cost and the unit estimate) so the balance
  decrements; transcribe_audio records delegate-tracked cost likewise.
- Workflow runs reserve their nodetool estimate when admitted and
  release at the terminal state or cancel-while-queued, so concurrent or
  queued submissions can't multiply a small balance (process-local, TTL-
  bounded; a multi-instance deployment moves this into the DB like
  application-budgets).
- NodetoolProvider builds a fresh delegate per call instead of sharing a
  cached instance, so absorbing cost off the delegate's cumulative
  counter can't double-count overlapping calls.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011GwuPTt5T1sLkmpwWUt2N2

Author: claude

packages/models/src/credits.ts

@@ -12,7 +12,8 @@
  * would write `topup` rows and flip `plan_id`; until then plan switches are
  * instant and top-ups are stubbed.
  */
-import { eq, sql } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
+import { NODETOOL_PROVIDER_ID } from "@nodetool-ai/protocol";
 
 import { getDb } from "./db.js";
 import { creditLedger, userSubscriptions } from "./schema/credits.js";
@@ -222,10 +223,18 @@ export async function creditStatus(userId: string): Promise<CreditStatus> {
     .where(eq(creditLedger.user_id, userId));
   const grantedCredits = Number(grantRows[0]?.total ?? 0);
 
+  // Only the managed provider's spend counts against credits — BYOK
+  // predictions (fal_ai, anthropic, …) ride the user's own keys and must
+  // never drain the balance.
   const spendRows = await db
     .select({ total: sql<number>`COALESCE(SUM(${predictions.cost}), 0)` })
     .from(predictions)
-    .where(eq(predictions.user_id, userId));
+    .where(
+      and(
+        eq(predictions.user_id, userId),
+        eq(predictions.provider, NODETOOL_PROVIDER_ID)
+      )
+    );
   const spentUsd = Number(spendRows[0]?.total ?? 0);
   const spentCredits = Math.ceil(spentUsd / USD_PER_CREDIT);
 

packages/models/tests/credits.test.ts

@@ -18,12 +18,12 @@ const USER = "u1";
 const FREE = CREDIT_PLANS.find((p) => p.id === "free")!;
 const CREATOR = CREDIT_PLANS.find((p) => p.id === "creator")!;
 
-const spend = (cost: number) =>
+const spend = (cost: number, provider = "nodetool") =>
   Prediction.create<Prediction>({
     user_id: USER,
     node_id: "n",
     node_type: "test",
-    provider: "test",
+    provider,
     model: "test",
     cost
   });
@@ -99,6 +99,19 @@ describe("credits", () => {
     }
   });
 
+  it("only managed-provider spend counts — BYOK predictions never drain credits", async () => {
+    await creditStatus(USER);
+    await spend(0.5, "fal_ai");
+    await spend(1.25, "anthropic");
+    const untouched = await creditStatus(USER);
+    expect(untouched.spentCredits).toBe(0);
+    expect(untouched.balanceCredits).toBe(FREE.monthlyCredits);
+
+    await spend(0.02, "nodetool");
+    const managed = await creditStatus(USER);
+    expect(managed.spentCredits).toBe(2);
+  });
+
   it("credits are per user", async () => {
     await creditStatus(USER);
     await creditStatus("u2");

packages/protocol/src/api-schemas/credits.ts

@@ -25,6 +25,8 @@ export const creditStatusOutput = z.object({
    * are never gated — both models coexist on one server.
    */
   meteredProvider: z.string(),
+  /** True only on dev servers that opt into the no-payment test top-up. */
+  testTopupEnabled: z.boolean(),
   plans: z.array(creditPlan)
 });
 export type CreditStatusOutput = z.infer<typeof creditStatusOutput>;

packages/runtime/src/providers/nodetool-provider.ts

@@ -39,7 +39,6 @@ const PLATFORM_KEYS: Record<string, string> = {
 
 export class NodetoolProvider extends BaseProvider {
   private secrets: Record<string, unknown>;
-  private inner = new Map<string, BaseProvider>();
   private _absorbedCost = 0;
 
   static override requiredSecrets(): string[] {
@@ -61,7 +60,14 @@ export class NodetoolProvider extends BaseProvider {
     return this.platformKey(delegateProvider) != null;
   }
 
-  /** The delegate serving a nodetool model id, constructed on platform keys. */
+  /**
+   * The delegate serving a nodetool model id, constructed on platform keys.
+   * A fresh instance per call on purpose: cost is read off the delegate's
+   * cumulative counter after the call, and a shared delegate serving
+   * overlapping calls would double-count one call's cost into another's
+   * absorption window. Construction is cheap — both delegates build their
+   * network clients lazily.
+   */
   private delegateFor(modelId: string): {
     provider: BaseProvider;
     model: string;
@@ -77,15 +83,11 @@ export class NodetoolProvider extends BaseProvider {
           `(missing ${PLATFORM_KEYS[def.delegate.provider]}).`
       );
     }
-    let instance = this.inner.get(def.delegate.provider);
-    if (!instance) {
-      instance =
-        def.delegate.provider === "fal_ai"
-          ? new FalProvider({ FAL_API_KEY: key })
-          : new AnthropicProvider({ ANTHROPIC_API_KEY: key });
-      this.inner.set(def.delegate.provider, instance);
-    }
-    return { provider: instance, model: def.delegate.model };
+    const provider =
+      def.delegate.provider === "fal_ai"
+        ? new FalProvider({ FAL_API_KEY: key })
+        : new AnthropicProvider({ ANTHROPIC_API_KEY: key });
+    return { provider, model: def.delegate.model };
   }
 
   /** Run a delegated call and absorb the delegate's cost delta as our own. */
@@ -111,7 +113,6 @@ export class NodetoolProvider extends BaseProvider {
 
   override resetCost(): void {
     this._absorbedCost = 0;
-    for (const inner of this.inner.values()) inner.resetCost();
   }
 
   protected override declaredCapabilities(): ProviderCapability[] {

packages/websocket/src/credit-gate.ts

@@ -15,17 +15,75 @@ export type CreditGateResult =
   | { allowed: true }
   | { allowed: false; reason: string };
 
+/**
+ * In-flight reservations: spend admitted but not yet in the prediction
+ * ledger. Without them, N concurrent submissions all pass against the same
+ * balance and a small balance authorizes N× its worth of platform spend.
+ * A reservation is taken when a run is admitted and released at its terminal
+ * state (or cancel-while-queued); the TTL bounds leaks from paths that never
+ * reach either (process-local state — a multi-instance deployment needs the
+ * reservation moved into the database, as application-budgets does).
+ */
+interface SpendReservation {
+  usd: number;
+  at: number;
+}
+
+const RESERVATION_TTL_MS = 2 * 60 * 60 * 1000;
+const reservations = new Map<string, Map<string, SpendReservation>>();
+
+export function reserveSpend(
+  userId: string,
+  key: string,
+  estimatedUsd: number
+): void {
+  let byKey = reservations.get(userId);
+  if (!byKey) {
+    byKey = new Map();
+    reservations.set(userId, byKey);
+  }
+  byKey.set(key, { usd: Math.max(0, estimatedUsd), at: Date.now() });
+}
+
+/** Releasing an unknown key is a no-op, so terminal paths can call it blindly. */
+export function releaseSpend(userId: string, key: string): void {
+  const byKey = reservations.get(userId);
+  if (!byKey) return;
+  byKey.delete(key);
+  if (byKey.size === 0) reservations.delete(userId);
+}
+
+export function reservedSpendUsd(userId: string): number {
+  const byKey = reservations.get(userId);
+  if (!byKey) return 0;
+  const cutoff = Date.now() - RESERVATION_TTL_MS;
+  let total = 0;
+  for (const [key, reservation] of byKey) {
+    if (reservation.at < cutoff) {
+      byKey.delete(key);
+      continue;
+    }
+    total += reservation.usd;
+  }
+  if (byKey.size === 0) reservations.delete(userId);
+  return total;
+}
+
 /**
  * Decide whether `userId` may spend an estimated `estimatedUsd` through the
- * managed provider. Estimates are floors (unpriceable work estimates 0), so
- * an empty balance blocks even a 0-estimate call.
+ * managed provider, counting spend already admitted but not yet settled.
+ * Estimates are floors (unpriceable work estimates 0), so an empty balance
+ * blocks even a 0-estimate call.
  */
 export async function admitSpend(
   userId: string | null | undefined,
   estimatedUsd: number
 ): Promise<CreditGateResult> {
   try {
-    const decision = await checkCredits(userId ?? "1", estimatedUsd);
+    const decision = await checkCredits(
+      userId ?? "1",
+      estimatedUsd + reservedSpendUsd(userId ?? "1")
+    );
     return decision.allowed
       ? { allowed: true }
       : { allowed: false, reason: decision.reason };

packages/websocket/src/trpc/routers/credits.ts

@@ -15,11 +15,22 @@ import {
 } from "@nodetool-ai/protocol/api-schemas/credits.js";
 import { NODETOOL_PROVIDER_ID } from "@nodetool-ai/protocol";
 
+/**
+ * Whether the unauthenticated-by-payment test top-up is allowed. Off unless
+ * the operator explicitly opts a development server in: minted credits unlock
+ * spend on platform-owned keys, so an open mint endpoint is an open wallet.
+ */
+const testTopupEnabled = (): boolean => {
+  const value = process.env.NODETOOL_ENABLE_TEST_TOPUP?.toLowerCase();
+  return value === "1" || value === "true";
+};
+
 const statusFor = async (userId: string) => {
   const status = await creditStatus(userId);
   return {
     ...status,
     meteredProvider: NODETOOL_PROVIDER_ID,
+    testTopupEnabled: testTopupEnabled(),
     plans: [...CREDIT_PLANS]
   };
 };
@@ -49,14 +60,23 @@ export const creditsRouter = router({
     }),
 
   /**
-   * Prototype top-up: adds credits with no payment behind it. A payment
+   * Development-only top-up: adds credits with no payment behind it, and is
+   * refused unless the operator sets NODETOOL_ENABLE_TEST_TOPUP. A payment
    * provider integration replaces this mutation with a checkout session and
    * writes the ledger row from the webhook instead.
    */
   topup: protectedProcedure
     .input(topupInput)
     .output(creditStatusOutput)
     .mutation(async ({ ctx, input }) => {
+      if (!testTopupEnabled()) {
+        throw new TRPCError({
+          code: "FORBIDDEN",
+          message:
+            "Top-ups are disabled on this server: no payment provider is " +
+            "configured and NODETOOL_ENABLE_TEST_TOPUP is not set."
+        });
+      }
       await grantCredits(
         ctx.userId,
         input.credits,