Benchmark suite for measuring and tracking the performance of critical paths in AgentLoop.

# Run all benchmarks
npm run bench

# Run with Node.js CPU profiling (generates isolate-*.log)
npm run bench:profile

# Process the .log file into a human-readable flame graph
node --prof-process isolate-*.log > profile.txt

Profiling on Windows: node --prof writes an isolate-<pid>-<seq>-v8.log file in the current working directory. Process it with node --prof-process. For a visual flame graph, install clinic: npx clinic flame -- node --require tsx/cjs benchmarks/run-all.ts

The runner exits with code 1 if any benchmark violates its threshold.

Results measured on a mid-range developer laptop (Intel Core i7-1185G7, 32 GB RAM, NVMe SSD, Node.js 20.x, Windows 11). Your numbers will vary.

Notes: ToolRegistry uses a Map<string, RegistryEntry> internally. Map.get() is O(1) and sub-microsecond for 100 entries. No optimization needed; the implementation is already optimal.

trimMessages first called countTokens(messages) which encoded every message once, then in the drop loop called messageTokens(middle[i]) again for each dropped message — up to 2 × N tokenizer calls in the worst case.

Token counts are now computed in one single pass (messages.map(messageTokens)) and the pre-computed array is reused in the drop loop, cutting tokenizer calls roughly in half.

// Before (redundant encode calls in the while loop):
while (i < middle.length && total > maxTokens) {
  total -= messageTokens(middle[i]);   // enc.encode() called again here
  i++;
}

// After (pre-computed counts reused):
const tokenCounts = messages.map(messageTokens);   // single pass
const middleCounts = tokenCounts.slice(1, -1);
while (i < middle.length && total > maxTokens) {
  total -= middleCounts[i];            // no extra encode call
  i++;
}

Uses the built-in fs-based fallback (ripgrep is preferred in production but not required for the benchmark). Performance is I/O-bound.

No hard threshold for this benchmark; it documents search time at scale.
Optimization recommendation: The searchWithFs function reads files sequentially. Parallelising reads with a bounded Promise.all pool (e.g. 8 concurrent) could reduce wall-clock time by 4–8× on multi-core machines with fast storage.

Reads package.json, lock files, .git/HEAD, and checks for the existence of several well-known files.

Notes: Each analyzeWorkspace call makes 5–8 fs.access / fs.readFile calls. No significant optimization headroom beyond OS-level file caching.

If a GitHub Actions workflow exists in .github/workflows/, add a benchmark step:

- name: Run performance benchmarks
  run: npm run bench

This catches regressions automatically on every PR. If no CI workflow currently exists, run npm run bench manually before merging performance-sensitive changes and record the output herein.

Current CI status: No GitHub Actions workflow file was present at the time benchmarks were added. Add a workflow (e.g. .github/workflows/ci.yml) and include the step above to enable automated regression detection.

1. Create benchmarks/<name>.bench.ts exporting:

   export interface BenchmarkResult {
     name: string; durationMs: number; iterations: number; opsPerSec: number;
   }
   export async function run(): Promise<BenchmarkResult> { ... }

2. Add an entry to the BENCHMARKS array in run-all.ts.
3. Document baseline numbers in this file.