auramaxx 1.0.0-alpha.4

package/server/lib/dex/types.ts

@@ -0,0 +1,59 @@
+import { ethers } from 'ethers';
+
+// V4 PoolKey type (Uniswap V4 specific, but may be reused)
+export interface PoolKey {
+  currency0: string;
+  currency1: string;
+  fee: number;
+  tickSpacing: number;
+  hooks: string;
+}
+
+// Pool detection result
+export interface PoolInfo {
+  version: string;       // e.g., "v2", "v3", "v4", "stable", "volatile"
+  fee?: number;          // Fee tier if applicable
+  poolKey?: PoolKey;     // V4 pool key if applicable
+  poolAddress?: string;  // Pool/pair address if known
+}
+
+// Swap parameters (DEX-agnostic)
+export interface SwapParams {
+  token: string;
+  direction: 'buy' | 'sell';
+  amount: string;        // In wei (EVM) or lamports (Solana)
+  minOut: string;
+  from: string;          // Sender wallet address
+  chainId: number;       // EVM chain ID
+  destinationChainId?: number; // Cross-chain destination (defaults to chainId)
+  version?: string;      // Pool version override
+  fee?: number;          // Fee tier override
+  poolKey?: PoolKey;     // V4 pool key override
+}
+
+// Transaction data result
+export interface SwapTxData {
+  to: string;
+  data: string;
+  value: string;         // In wei
+}
+
+// DEX Adapter interface
+export interface DexAdapter {
+  name: string;
+
+  // Supported on this chain?
+  supportsChain(chainId: number): boolean;
+
+  // Detect if a pool exists for this token
+  detectPool(
+    token: string,
+    provider: ethers.Provider
+  ): Promise<PoolInfo | null>;
+
+  // Build swap transaction
+  buildSwapTx(params: SwapParams): Promise<SwapTxData>;
+
+  // Get the router/helper contract address
+  getRouterAddress(): string;
+}

package/server/lib/dex/uniswap.ts

@@ -0,0 +1,370 @@
+import { ethers } from 'ethers';
+import { DexAdapter, PoolInfo, SwapParams, SwapTxData, PoolKey } from './types';
+import SwapHelperABI from '../../abi/SwapHelper.json';
+
+// Constants
+export const SWAP_HELPER = '0xD28f98c89d6F88762377b400936b434731c8a61F'; // SwapHelperV2 (Universal Router)
+export const WETH = '0x4200000000000000000000000000000000000006';
+
+// Uniswap Factory addresses on Base
+const V3_FACTORY = '0x33128a8fC17869897dcE68Ed026d694621f6FDfD';
+const V2_FACTORY = '0x8909Dc15e40173Ff4699343b6eB8132c65e18eC6';
+
+// V4 PoolManager address fallback (query from SwapHelper.POOL_MANAGER() at runtime)
+const V4_POOL_MANAGER_FALLBACK = '0x6Ab04E3376fB1d12cC0b27E6F2E7485CC8bFCb53';
+
+// Initialize event topic for V4 PoolManager
+const INITIALIZE_EVENT_TOPIC = '0x803151a295203f64f7e2ca2db584660e99eaf67eca6f05af1bf0707e7d38f2cf';
+
+// V3 fee tiers to check (ordered by likelihood)
+const V3_FEE_TIERS = [3000, 10000, 500] as const;
+
+// Known V4 hooks (Base mainnet)
+export const V4_HOOKS: Record<string, string> = {
+  clanker: '0x1F98400000000000000000000000000000000004',
+  'clanker-dynamic-fee-v2': '0xd60D6B218116cFd801E28F78d011a203D2b068Cc',
+  'clanker-static-fee-v2': '0xb429d62f8f3bFFb98CdB9569533eA23bF0Ba28CC',
+  'clanker-4.0-a': '0x34a45c6B61876d739400Bd71228CbcbD4F53E8cC',
+  'clanker-4.0-b': '0xDd5EeaFf7BD481AD55Db083062b13a3cdf0A68CC',
+  zora: '0xe2B4100DE1CD284Bd364f738d1354715515C90C0',
+  // doppler: per-token hooks, must provide poolKey manually
+};
+
+// Minimal V3 Factory ABI
+const V3_FACTORY_ABI = [
+  'function getPool(address tokenA, address tokenB, uint24 fee) view returns (address pool)'
+];
+
+// Minimal V2 Factory ABI
+const V2_FACTORY_ABI = [
+  'function getPair(address tokenA, address tokenB) view returns (address pair)'
+];
+
+// DYNAMIC_FEE_FLAG from Uniswap V4 LPFeeLibrary
+const DYNAMIC_FEE_FLAG = 0x800000;
+
+// Standard V4 pool params for known hooks
+const V4_POOL_PARAMS: Record<string, { fee: number; tickSpacing: number }> = {
+  clanker: { fee: 10000, tickSpacing: 200 },  // 1% (legacy)
+  'clanker-dynamic-fee-v2': { fee: DYNAMIC_FEE_FLAG, tickSpacing: 200 },  // v4.1.0
+  'clanker-static-fee-v2': { fee: DYNAMIC_FEE_FLAG, tickSpacing: 200 },   // v4.1.0
+  'clanker-4.0-a': { fee: DYNAMIC_FEE_FLAG, tickSpacing: 200 },  // v4.0.0 dynamic
+  'clanker-4.0-b': { fee: DYNAMIC_FEE_FLAG, tickSpacing: 200 },  // v4.0.0 static
+  zora: { fee: 10000, tickSpacing: 200 },     // 1%
+};
+
+// Common no-hook pool params to try (ordered by likelihood)
+const V4_NO_HOOK_PARAMS = [
+  { fee: 3000, tickSpacing: 60 },    // 0.3%
+  { fee: 10000, tickSpacing: 200 },  // 1%
+  { fee: 500, tickSpacing: 10 },     // 0.05%
+];
+
+/**
+ * Get list of known V4 hook names
+ */
+export function getKnownV4Hooks(): string[] {
+  return Object.keys(V4_HOOKS);
+}
+
+/**
+ * Get the PoolManager address from SwapHelper contract
+ */
+async function getPoolManagerAddress(provider: ethers.Provider): Promise<string> {
+  const swapHelper = new ethers.Contract(
+    SWAP_HELPER,
+    ['function POOL_MANAGER() view returns (address)'],
+    provider
+  );
+  try {
+    return await swapHelper.POOL_MANAGER();
+  } catch {
+    return V4_POOL_MANAGER_FALLBACK;
+  }
+}
+
+/**
+ * Build a PoolKey for known V4 hooks or no-hook pools
+ *
+ * @param token - Token address
+ * @param hookName - Hook name ('clanker', 'zora', etc.) or 'none' for no-hook pools
+ * @returns PoolKey or null if hook not found
+ */
+export function getV4PoolKey(token: string, hookName?: string): PoolKey | null {
+  if (!hookName) return null;
+
+  const name = hookName.toLowerCase();
+
+  // Handle 'none' - return first no-hook params (caller can iterate if needed)
+  if (name === 'none') {
+    const params = V4_NO_HOOK_PARAMS[0];
+    const [currency0, currency1] = token.toLowerCase() < WETH.toLowerCase()
+      ? [token, WETH]
+      : [WETH, token];
+
+    return {
+      currency0,
+      currency1,
+      fee: params.fee,
+      tickSpacing: params.tickSpacing,
+      hooks: ethers.ZeroAddress
+    };
+  }
+
+  const hookAddress = V4_HOOKS[name];
+  const params = V4_POOL_PARAMS[name];
+
+  if (!hookAddress || !params) return null;
+
+  const [currency0, currency1] = token.toLowerCase() < WETH.toLowerCase()
+    ? [token, WETH]
+    : [WETH, token];
+
+  return {
+    currency0,
+    currency1,
+    fee: params.fee,
+    tickSpacing: params.tickSpacing,
+    hooks: hookAddress
+  };
+}
+
+/**
+ * Get all possible no-hook PoolKeys for a token
+ */
+export function getV4NoHookPoolKeys(token: string): PoolKey[] {
+  const [currency0, currency1] = token.toLowerCase() < WETH.toLowerCase()
+    ? [token, WETH]
+    : [WETH, token];
+
+  return V4_NO_HOOK_PARAMS.map(params => ({
+    currency0,
+    currency1,
+    fee: params.fee,
+    tickSpacing: params.tickSpacing,
+    hooks: ethers.ZeroAddress
+  }));
+}
+
+/**
+ * Detect V4 pool by querying PoolManager Initialize events
+ *
+ * @param token - Token address to search for
+ * @param provider - Ethers provider
+ * @returns PoolKey if found, null otherwise
+ */
+export async function detectV4PoolFromEvents(
+  token: string,
+  provider: ethers.Provider
+): Promise<PoolKey | null> {
+  try {
+    const poolManager = await getPoolManagerAddress(provider);
+    const tokenPadded = ethers.zeroPadValue(token.toLowerCase(), 32);
+
+    // Query with token as currency0
+    const logs0 = await provider.getLogs({
+      address: poolManager,
+      topics: [
+        INITIALIZE_EVENT_TOPIC,
+        null, // poolId - any
+        tokenPadded, // currency0
+        null  // currency1 - any
+      ],
+      fromBlock: 0
+    });
+
+    // Query with token as currency1
+    const logs1 = await provider.getLogs({
+      address: poolManager,
+      topics: [
+        INITIALIZE_EVENT_TOPIC,
+        null,
+        null,
+        tokenPadded // currency1
+      ],
+      fromBlock: 0
+    });
+
+    const allLogs = [...logs0, ...logs1];
+    if (allLogs.length === 0) return null;
+
+    // Parse the first matching event
+    const log = allLogs[0];
+
+    // Extract currency0 and currency1 from indexed topics
+    const currency0 = ethers.getAddress('0x' + log.topics[2].slice(26));
+    const currency1 = ethers.getAddress('0x' + log.topics[3].slice(26));
+
+    // Decode the data field: fee (uint24), tickSpacing (int24), hooks (address), sqrtPriceX96 (uint160), tick (int24)
+    const decoded = ethers.AbiCoder.defaultAbiCoder().decode(
+      ['uint24', 'int24', 'address', 'uint160', 'int24'],
+      log.data
+    );
+    const [fee, tickSpacing, hooks] = decoded;
+
+    return {
+      currency0,
+      currency1,
+      fee: Number(fee),
+      tickSpacing: Number(tickSpacing),
+      hooks
+    };
+  } catch {
+    // RPC errors, parsing errors, etc. - return null
+    return null;
+  }
+}
+
+/**
+ * Uniswap adapter for V2/V3/V4 swaps via SwapHelper contract
+ */
+export const uniswapAdapter: DexAdapter = {
+  name: 'uniswap',
+
+  supportsChain(chainId: number): boolean {
+    // SwapHelper is deployed on Base
+    return chainId === 8453;
+  },
+
+  async detectPool(
+    token: string,
+    provider: ethers.Provider
+  ): Promise<PoolInfo | null> {
+    // Priority: V4 with known hooks -> V3 -> V2 -> other V4 pools
+
+    // 1. Try V4 with known hooks first
+    const v4PoolKey = await detectV4PoolFromEvents(token, provider);
+    if (v4PoolKey) {
+      // Check if this pool uses a known hook
+      const knownHookAddresses = Object.values(V4_HOOKS).map(h => h.toLowerCase());
+      const hasKnownHook = v4PoolKey.hooks !== ethers.ZeroAddress &&
+        knownHookAddresses.includes(v4PoolKey.hooks.toLowerCase());
+
+      if (hasKnownHook) {
+        return { version: 'v4', poolKey: v4PoolKey };
+      }
+    }
+
+    // 2. Check V3 pools
+    const v3Factory = new ethers.Contract(V3_FACTORY, V3_FACTORY_ABI, provider);
+    for (const fee of V3_FEE_TIERS) {
+      try {
+        const pool = await v3Factory.getPool(WETH, token, fee);
+        if (pool && pool !== ethers.ZeroAddress) {
+          return { version: 'v3', fee, poolAddress: pool };
+        }
+      } catch {
+        // Pool doesn't exist for this fee tier
+      }
+    }
+
+    // 3. Check V2 pair
+    const v2Factory = new ethers.Contract(V2_FACTORY, V2_FACTORY_ABI, provider);
+    try {
+      const pair = await v2Factory.getPair(WETH, token);
+      if (pair && pair !== ethers.ZeroAddress) {
+        return { version: 'v2', poolAddress: pair };
+      }
+    } catch {
+      // No V2 pair
+    }
+
+    // 4. Return other V4 pool (unknown hooks or no hooks) as fallback
+    if (v4PoolKey) {
+      return { version: 'v4', poolKey: v4PoolKey };
+    }
+
+    return null;
+  },
+
+  buildSwapTx(params: SwapParams): SwapTxData {
+    const { token, direction, amount, minOut, version, fee, poolKey } = params;
+
+    const swapHelper = new ethers.Interface(SwapHelperABI);
+
+    if (direction === 'buy') {
+      return buildBuyTx(swapHelper, token, amount, minOut, version || 'v3', fee, poolKey);
+    } else {
+      return buildSellTx(swapHelper, token, amount, minOut, version || 'v3', fee, poolKey);
+    }
+  },
+
+  getRouterAddress(): string {
+    return SWAP_HELPER;
+  }
+};
+
+function buildBuyTx(
+  iface: ethers.Interface,
+  token: string,
+  amount: string,
+  minOut: string,
+  version: string,
+  poolFee?: number,
+  poolKey?: PoolKey
+): SwapTxData {
+  const valueWei = BigInt(amount);
+  const minOutBn = BigInt(minOut);
+
+  let data: string;
+
+  if (version === 'v2') {
+    data = iface.encodeFunctionData('snipeV2', [token, minOutBn]);
+  } else if (version === 'v3') {
+    const fee = poolFee || 3000;
+    data = iface.encodeFunctionData('snipeV3', [token, fee, minOutBn]);
+  } else if (version === 'v4') {
+    if (!poolKey) throw new Error('V4 pool key required');
+    data = iface.encodeFunctionData('snipeV4', [
+      [poolKey.currency0, poolKey.currency1, poolKey.fee, poolKey.tickSpacing, poolKey.hooks],
+      minOutBn
+    ]);
+  } else {
+    throw new Error(`Invalid Uniswap version: ${version}`);
+  }
+
+  return {
+    to: SWAP_HELPER,
+    data,
+    value: valueWei.toString()
+  };
+}
+
+function buildSellTx(
+  iface: ethers.Interface,
+  token: string,
+  amount: string,
+  minOut: string,
+  version: string,
+  poolFee?: number,
+  poolKey?: PoolKey
+): SwapTxData {
+  const amountIn = BigInt(amount);
+  const minOutBn = BigInt(minOut);
+
+  let data: string;
+
+  if (version === 'v2') {
+    data = iface.encodeFunctionData('sellV2', [token, amountIn, minOutBn]);
+  } else if (version === 'v3') {
+    const fee = poolFee || 3000;
+    data = iface.encodeFunctionData('sellV3', [token, fee, amountIn, minOutBn]);
+  } else if (version === 'v4') {
+    if (!poolKey) throw new Error('V4 pool key required');
+    data = iface.encodeFunctionData('sellV4', [
+      [poolKey.currency0, poolKey.currency1, poolKey.fee, poolKey.tickSpacing, poolKey.hooks],
+      amountIn,
+      minOutBn
+    ]);
+  } else {
+    throw new Error(`Invalid Uniswap version: ${version}`);
+  }
+
+  return {
+    to: SWAP_HELPER,
+    data,
+    value: '0'
+  };
+}
+
+export default uniswapAdapter;

package/server/lib/e2e-agent/artifacts.ts

@@ -0,0 +1,36 @@
+import fs from 'fs';
+import path from 'path';
+import { RunFingerprint } from './contracts';
+
+export interface SummaryArtifact {
+  runId: string;
+  status: 'passed' | 'failed';
+  scenarioId: string;
+  runFingerprint: RunFingerprint;
+}
+
+export interface ReplayManifest {
+  runId: string;
+  scenarioId: string;
+  runFingerprint: RunFingerprint;
+  replayCommand: string;
+}
+
+export function writeArtifacts(baseDir: string, summary: SummaryArtifact): { summaryPath: string; manifestPath: string } {
+  fs.mkdirSync(baseDir, { recursive: true });
+
+  const summaryPath = path.join(baseDir, 'summary.json');
+  fs.writeFileSync(summaryPath, JSON.stringify(summary, null, 2));
+
+  const manifest: ReplayManifest = {
+    runId: summary.runId,
+    scenarioId: summary.scenarioId,
+    runFingerprint: summary.runFingerprint,
+    replayCommand: `npx tsx server/tests/e2e-agent/runner.ts replay --run ${summary.runId}`,
+  };
+
+  const manifestPath = path.join(baseDir, 'replay.manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+  return { summaryPath, manifestPath };
+}

package/server/lib/e2e-agent/contracts.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+
+export const E2E_AGENT_ERROR_CODES = {
+  schemaAssertion: 'E_SCHEMA_ASSERTION',
+  egressPolicy: 'E_EGRESS_POLICY',
+  clockDrift: 'E_CLOCK_DRIFT',
+  budgetDuration: 'E_BUDGET_DURATION',
+  budgetSteps: 'E_BUDGET_STEPS',
+  budgetToolCalls: 'E_BUDGET_TOOL_CALLS',
+  budgetTokens: 'E_BUDGET_TOKENS',
+} as const;
+
+const assertionBaseSchema = z.object({
+  id: z.string().min(1),
+  type: z.enum(['ui', 'api', 'db']),
+  op: z.enum(['equals', 'contains', 'exists', 'not_exists', 'gt', 'gte', 'lt', 'lte']),
+});
+
+const uiAssertionSchema = assertionBaseSchema.extend({
+  type: z.literal('ui'),
+  selector: z.string().min(1),
+  expected: z.union([z.string(), z.number(), z.boolean()]).optional(),
+});
+
+const apiAssertionSchema = assertionBaseSchema.extend({
+  type: z.literal('api'),
+  endpoint: z.string().min(1),
+  path: z.string().min(1),
+  expected: z.union([z.string(), z.number(), z.boolean()]).optional(),
+});
+
+const dbAssertionSchema = assertionBaseSchema.extend({
+  type: z.literal('db'),
+  query: z.string().min(1),
+  expected: z.union([z.string(), z.number(), z.boolean()]).optional(),
+});
+
+export const assertionSchema = z.discriminatedUnion('type', [
+  uiAssertionSchema,
+  apiAssertionSchema,
+  dbAssertionSchema,
+]);
+
+export const budgetSchema = z.object({
+  maxDurationSec: z.number().int().positive(),
+  maxSteps: z.number().int().positive(),
+  maxToolCalls: z.number().int().positive(),
+  maxTokens: z.number().int().positive(),
+});
+
+export const scenarioSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  mode: z.enum(['agent-hybrid', 'scripted']),
+  clock: z.object({
+    baseTimeIso: z.string().datetime(),
+  }),
+  budget: budgetSchema.partial().optional(),
+  assertions: z.array(assertionSchema).min(1),
+});
+
+export type Assertion = z.infer<typeof assertionSchema>;
+export type Budget = z.infer<typeof budgetSchema>;
+export type Scenario = z.infer<typeof scenarioSchema>;
+
+export type Lane = 'pr-smoke' | 'nightly';
+
+export interface LaneBudgetCaps {
+  maxDurationSec: number;
+  maxSteps: number;
+  maxToolCalls: number;
+  maxTokens: number;
+}
+
+export const REPO_DEFAULT_BUDGET: Budget = {
+  maxDurationSec: 90,
+  maxSteps: 15,
+  maxToolCalls: 12,
+  maxTokens: 12000,
+};
+
+export const LANE_BUDGET_CAPS: Record<Lane, LaneBudgetCaps> = {
+  'pr-smoke': {
+    maxDurationSec: 120,
+    maxSteps: 20,
+    maxToolCalls: 16,
+    maxTokens: 16000,
+  },
+  nightly: {
+    maxDurationSec: 240,
+    maxSteps: 40,
+    maxToolCalls: 30,
+    maxTokens: 40000,
+  },
+};
+
+export interface ClockProbe {
+  runnerMs: number;
+  serverMs: number;
+  browserMs: number;
+  fixtureMs: number;
+}
+
+export interface RunFingerprint {
+  scenarioId: string;
+  lane: Lane;
+  mode: Scenario['mode'];
+  clockBaseTimeIso: string;
+  schemaVersion: string;
+  runnerVersion: string;
+  gitCommit: string;
+}

package/server/lib/e2e-agent/validation.ts

@@ -0,0 +1,135 @@
+import { parse as parseYaml } from 'yaml';
+import {
+  Budget,
+  ClockProbe,
+  E2E_AGENT_ERROR_CODES,
+  LANE_BUDGET_CAPS,
+  Lane,
+  REPO_DEFAULT_BUDGET,
+  Scenario,
+  scenarioSchema,
+} from './contracts';
+
+export class E2EAgentValidationError extends Error {
+  constructor(public readonly code: string, message: string) {
+    super(message);
+    this.name = 'E2EAgentValidationError';
+  }
+}
+
+export function parseScenarioDocument(input: string): unknown {
+  try {
+    return JSON.parse(input);
+  } catch {
+    return parseYaml(input);
+  }
+}
+
+export function validateScenario(raw: unknown): Scenario {
+  const parsed = scenarioSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.schemaAssertion,
+      parsed.error.issues.map((issue) => issue.message).join('; ')
+    );
+  }
+
+  return parsed.data;
+}
+
+export function applyBudgetPolicy(scenarioBudget: Partial<Budget> | undefined, lane: Lane): Budget {
+  const merged: Budget = {
+    ...REPO_DEFAULT_BUDGET,
+    ...(scenarioBudget ?? {}),
+  };
+
+  const laneCaps = LANE_BUDGET_CAPS[lane];
+
+  if (merged.maxDurationSec > laneCaps.maxDurationSec) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetDuration,
+      `maxDurationSec (${merged.maxDurationSec}) exceeds lane cap (${laneCaps.maxDurationSec})`
+    );
+  }
+
+  if (merged.maxSteps > laneCaps.maxSteps) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetSteps,
+      `maxSteps (${merged.maxSteps}) exceeds lane cap (${laneCaps.maxSteps})`
+    );
+  }
+
+  if (merged.maxToolCalls > laneCaps.maxToolCalls) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetToolCalls,
+      `maxToolCalls (${merged.maxToolCalls}) exceeds lane cap (${laneCaps.maxToolCalls})`
+    );
+  }
+
+  if (merged.maxTokens > laneCaps.maxTokens) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetTokens,
+      `maxTokens (${merged.maxTokens}) exceeds lane cap (${laneCaps.maxTokens})`
+    );
+  }
+
+  return merged;
+}
+
+export function enforceClockDrift(probe: ClockProbe): void {
+  const values = [probe.runnerMs, probe.serverMs, probe.browserMs, probe.fixtureMs];
+  const drift = Math.max(...values) - Math.min(...values);
+
+  if (drift > 50) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.clockDrift,
+      `Clock drift ${drift}ms exceeded tolerance`
+    );
+  }
+}
+
+export function enforceEgressPolicy(hostname: string, allowedHosts: readonly string[]): void {
+  if (!allowedHosts.includes(hostname)) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.egressPolicy,
+      `Blocked outbound host: ${hostname}`
+    );
+  }
+}
+
+export interface RuntimeUsage {
+  durationSec: number;
+  steps: number;
+  toolCalls: number;
+  tokens: number;
+}
+
+export function enforceRuntimeBudget(usage: RuntimeUsage, budget: Budget): void {
+  if (usage.durationSec > budget.maxDurationSec) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetDuration,
+      `durationSec ${usage.durationSec} exceeded ${budget.maxDurationSec}`
+    );
+  }
+
+  if (usage.steps > budget.maxSteps) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetSteps,
+      `steps ${usage.steps} exceeded ${budget.maxSteps}`
+    );
+  }
+
+  if (usage.toolCalls > budget.maxToolCalls) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetToolCalls,
+      `toolCalls ${usage.toolCalls} exceeded ${budget.maxToolCalls}`
+    );
+  }
+
+  if (usage.tokens > budget.maxTokens) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetTokens,
+      `tokens ${usage.tokens} exceeded ${budget.maxTokens}`
+    );
+  }
+}