feat(agent): add remaining-spend helper and harden amount conversion

Author: Olasunkanmi975

services/agent/src/index.ts

@@ -5,6 +5,7 @@ export {
   assertAppraisalSpendAllowed,
   assertBidWithinMandate,
   bidFromAppraisal,
+  remainingAppraisalSpend,
   mandateDigest,
   usdcToStroops,
   stroopsToUsdc,

services/agent/src/mandate.test.ts

@@ -10,6 +10,8 @@ import {
   createSessionMandate,
   MandateCapError,
   MandateError,
+  remainingAppraisalSpend,
+  stroopsToUsdc,
   usdcToStroops,
   verifySessionMandate,
 } from "./mandate.js";
@@ -83,3 +85,39 @@ test("bidFromAppraisal clamps to mandate maxBid", () => {
   assert.equal(bidValue, usdcToStroops(40));
   assert.equal(escrow, usdcToStroops(40));
 });
+
+test("usdcToStroops converts and hardens input", () => {
+  assert.equal(usdcToStroops(1), 10_000_000n);
+  assert.equal(usdcToStroops(0.1), 1_000_000n);
+  assert.equal(usdcToStroops(0), 0n);
+  assert.throws(() => usdcToStroops(Number.NaN), MandateError);
+  assert.throws(() => usdcToStroops(Number.POSITIVE_INFINITY), MandateError);
+  assert.throws(() => usdcToStroops(-1), MandateError);
+});
+
+test("stroopsToUsdc converts and hardens input", () => {
+  assert.equal(stroopsToUsdc(10_000_000n), 1);
+  assert.equal(stroopsToUsdc(1_500_000n), 0.15);
+  assert.equal(stroopsToUsdc(0n), 0);
+  assert.throws(() => stroopsToUsdc(123 as unknown as bigint), MandateError);
+  assert.throws(() => stroopsToUsdc(-1n), MandateError);
+});
+
+test("remainingAppraisalSpend tracks remaining budget", () => {
+  const p = baseParams();
+  p.maxAppraisalSpendStroops = usdcToStroops(1);
+  const { mandate } = createSessionMandate(p);
+  assert.equal(remainingAppraisalSpend(mandate), usdcToStroops(1));
+  assert.equal(
+    remainingAppraisalSpend(mandate, usdcToStroops(0.4)),
+    usdcToStroops(0.6),
+  );
+  assert.throws(
+    () => remainingAppraisalSpend(mandate, usdcToStroops(1.5)),
+    MandateCapError,
+  );
+  assert.throws(
+    () => remainingAppraisalSpend(mandate, -1n as unknown as bigint),
+    MandateError,
+  );
+});

services/agent/src/mandate.ts

@@ -65,11 +65,31 @@ export function mandateDigest(payload: SessionMandatePayload): Buffer {
 }
 
 export function usdcToStroops(amount: number): bigint {
-  return BigInt(Math.round(amount * 1e7));
+  if (!Number.isFinite(amount)) {
+    throw new MandateError(`usdc amount must be a finite number, got ${amount}`);
+  }
+  if (amount < 0) {
+    throw new MandateError(`usdc amount must be non-negative, got ${amount}`);
+  }
+  const scaled = Math.round(amount * 1e7);
+  if (!Number.isSafeInteger(scaled)) {
+    throw new MandateError(`usdc amount ${amount} is out of stroop-safe range`);
+  }
+  return BigInt(scaled);
 }
 
 export function stroopsToUsdc(stroops: bigint): number {
-  return Number(stroops) / 1e7;
+  if (typeof stroops !== "bigint") {
+    throw new MandateError(`stroops must be a bigint, got ${typeof stroops}`);
+  }
+  if (stroops < 0n) {
+    throw new MandateError(`stroops must be non-negative, got ${stroops}`);
+  }
+  // Split whole/fraction to avoid `Number(bigint)` precision loss for large
+  // escrow/bid values that exceed Number's safe integer range.
+  const whole = Number(stroops / 10_000_000n);
+  const frac = Number(stroops % 10_000_000n) / 1e7;
+  return whole + frac;
 }
 
 export interface CreateMandateParams {
@@ -178,6 +198,26 @@ export function assertAppraisalSpendAllowed(
   }
 }
 
+/** Remaining x402 appraisal budget (stroops) before the mandate cap is hit. */
+export function remainingAppraisalSpend(
+  mandate: SessionMandate,
+  spentSoFarStroops: bigint = 0n,
+): bigint {
+  if (typeof spentSoFarStroops !== "bigint" || spentSoFarStroops < 0n) {
+    throw new MandateError(
+      `spentSoFarStroops must be a non-negative bigint, got ${String(spentSoFarStroops)}`,
+    );
+  }
+  const cap = BigInt(mandate.maxAppraisalSpendStroops);
+  const remaining = cap - spentSoFarStroops;
+  if (remaining < 0n) {
+    throw new MandateCapError(
+      `appraisal spend ${spentSoFarStroops} already exceeds mandate cap ${cap}`,
+    );
+  }
+  return remaining;
+}
+
 /** Refuse a bid/escrow pair that exceeds mandate caps (agent-side guard). */
 export function assertBidWithinMandate(
   mandate: SessionMandate,