Loop Budget
Why
Agents do not stop when they should. A repair loop retries the same failing edit forever; a polling loop mistakes activity for progress; a fan-out loop redispatches work that already finished. mini-swe-agent's answer is budgets declared up front - step_limit, cost_limit, wall_time_limit_seconds, max_consecutive_format_errors - with typed exits instead of exceptions, cost charged even on parse failure, and a trajectory saved every step. SWE-agent's ACI adds the guardrails: discard invalid edits and retry, keep only the first format-error message in the retry prompt, and narrate empty results instead of dropping them. This skill applies both to any loop an agent runs, so the loop ends with a verdict the caller can route on rather than a timeout or a hung process.
The loop ledger is the durable record underneath the verdict: append-only, written every step, and never compacted. A summary may compress the payload; it may never compress the fact that the step happened.
Contract
- Input: the loop's step verdicts ({action, args, result}), the budget declared for the loop, and a ledger path.
- Output: a
LoopBudgetVerdicttyped object - {exitStatus, submission, budgetSpent, nudges} - plus the append-only ledger file. - Scope: loop engineering only. This skill declares budgets, detects degeneration, and records steps; it does not decide what the steps do.
- Rule: budgets are declared UP FRONT, before the first iteration, and are never relaxed mid-loop.
- Rule: the loop verdict is the only exit - every termination path returns the typed object; loop-control failures never raise exceptions.
- Rule: polling actions with changing results are exempt from repeat detection, because the result hash is part of the step signature.
Provenance
| Question | Answer |
|---|---|
| What is the source of truth? | The budget declared before the loop started and the step verdicts it bounds |
| What is in scope? | Budget enforcement, degenerate-loop detection, ledger recording, and nudge escalation for one loop |
| What is explicitly out of scope? | The semantics of each step, artifact repair, and schema validation of the artifacts themselves |
| Who or what consumes this artifact afterward? | The calling loop (e.g. implement, review-fix-loop), routing on exitStatus |
| What evidence proves it is done? | A typed verdict with budgetSpent, a ledger with one hashed line per step, and a nudge for every escalation |
| What risk remains? | Budgets too loose to catch degeneration, or result signatures that hide a meaningful change |
Artifact
Emit LoopBudgetVerdict as both:
- JSON:
.agents/skills/platform/artifacts/loop-budget/{id}.json - Markdown view: same filename with
.mdextension
The companion evidence is the loop ledger (default .scratch/loop-ledger.jsonl): one JSON line per step with argsHash, resultSignature, and stepHash, plus a final summary line. Implement the loop with .agents/skills/platform/loop-runner.mjs (runLoop); the budget table, nudge taxonomy, and ledger format live in references/budgets.md.
Rules
- Rule: budgets are declared UP FRONT before the first iteration - stepLimit, costLimit, wallTimeLimitMs, maxConsecutiveFormatErrors, repeatThreshold, repeatWindow, pingPongWindow.
- Rule: budgets are checked before each step executes, never after - a loop at its step limit stops before spending another step.
- Rule: cost is charged even when a step throws; the failed step is written to the ledger with its error.
- Rule: the loop verdict is the only exit: {exitStatus, submission, budgetSpent, nudges}. Loop-control failures never throw.
- Rule: the ledger is append-only and never compacted - summarize the payload, never the fact that the step happened.
- Rule: a step repeating with identical args AND identical result is degeneration; the same action with a changed result is progress.
Workflow
- Declare the budget. Before the first iteration, fix stepLimit, costLimit, wallTimeLimitMs, and the degenerate-loop thresholds (maxConsecutiveFormatErrors, repeatThreshold, repeatWindow, pingPongWindow). Pick values from the table in
references/budgets.md. - Wire the ledger. Point
ledgerPathat.scratch/loop-ledger.jsonlor a session-scoped path. The runner appends one hashed JSON line per step in a finally block, so an interrupted run keeps its state. - Run the loop through
runLoop. Passstepsas an async iterator of {action, args, result} verdicts andonNudgeto receive structured escalations. The runner charges cost, detects exact repeats and A-B-A-B ping-pong, and enforces the budget before each step. - Route on the verdict.
completedhandssubmissionto the caller.limits-exceeded,repeated-action,ping-pong, andformat-errorseach mean the loop stopped for a declared reason - read the final nudge before deciding anything. - Record the artifact. Save the verdict as
LoopBudgetVerdictat.agents/skills/platform/artifacts/loop-budget/{id}.jsonand keep the ledger beside it as the execution evidence.
Guardrails
- Rule: never relax a declared budget mid-loop to keep a loop alive; declare a new budget for a new loop.
- Rule: never restart the same loop unchanged after
repeated-action,ping-pong, orformat-errors- change the approach or report the blocker. - Rule: never write to the ledger except by appending a step or summary line; compaction loses the fact that the step happened.
- Rule: never pass an artifact downstream that failed schema validation - reject it with {artifactType, schemaErrors[], attempt} and retry with only the first format-error message.
Completion criteria
- the budget was declared before the first iteration and enforced without mid-loop changes
- the loop ended with a typed verdict - no exception, no timeout
- the ledger holds one hashed line per step plus the summary, append-only
- every nudge emitted during the loop is recorded in the verdict's
nudgesand read before the next loop - the artifact is saved at
.agents/skills/platform/artifacts/loop-budget/{id}.jsonand the caller is identified
@include .agents/skills/platform/contract-base.xml