AGENTS.md

1<!-- Embedded runner test performance notes for limiting full-runner coverage to integration behavior. -->
2 
3# Embedded Runner Test Performance
4 
5The embedded attempt runner is one of the most expensive agent test surfaces.
6Use full-runner tests only when the behavior truly requires the runner.
7 
8## Guardrails
9 
10- Prefer focused helper tests for prompt assembly, runtime-context construction,
11  cache metadata, token accounting, and maintenance decision logic.
12- Keep full `runEmbeddedAttempt` coverage for cross-component behavior that
13  cannot be proven through helpers, not for a single derived field.
14- When extracting a helper from runner logic, make production call that helper
15  directly, then test the helper. Avoid test-only copies of runner behavior.
16- Preserve context-engine coverage for `sessionKey`, `sessionFile`, token
17  budget, current token count, prompt cache, and routing fields when slimming
18  tests.
19- Treat a standalone full-runner test above a few seconds as suspect. First ask
20  whether the proof can move to a production helper plus one cheap integration
21  smoke.
22 
23## Verification
24 
25- For runner test slimming, run the touched helper test and the nearest
26  two-file runner/context-engine surface.
27- Record Vitest duration, wall time, and RSS when the change is performance
28  motivated.
29