Skip to content
ContractSpec
Start here

reference

Agent bounded epochs V1

field.key.label
docs.tech.agent.bounded-epoch-v1
field.version.label
field.type.label
field.title.label
Agent bounded epochs V1
field.tags.label
field.owners.label
field.stability.label
public

A long-running agent run is a finite sequence of bounded epochs. The policy fixes a per-epoch budget (tokens, wall time up to 900 s, tool calls; every ceiling is positive), a renewal policy (never, automatic or approval_required, with a finite maxRenewals), a no-progress threshold and a maxResumes bound on process restarts. An epoch ends when the work completes, a budget dimension is exhausted or the run is cancelled. At that boundary the runtime writes an epoch_ended checkpoint and records one decision: complete, renew (renewal number advances by one; approval_required needs an approval ref) or stop with a typed reason (budget_exhausted, renewal_limit_reached, renewal_not_approved, no_progress, effect_indeterminate, resume_limit_reached, cancelled). A run stops with no_progress after noProgressThreshold consecutive epochs without progress evidence. Every epoch also starts with an epoch_started checkpoint whose stateDigest binds the stored starting state, so a restarted process verifies that state, resumes the open epoch from it and replays recorded effects instead of running them again. An effect whose outcome was never recorded stops the run as effect_indeterminate, and an epoch that ends on its budget or a cancellation while an effect is still pending stops the same way instead of renewing, because a renewed epoch would run that work again. A resumed epoch keeps its original start, so its wall-time budget includes the time before the restart, and it keeps the token and tool-call spend persisted with the open epoch, with the number of steps that spend counts, so its counters continue instead of restarting at zero. It also keeps how many steps had reached a recorded effect, stored with the first effect record of each step. After a restart those admitted steps run again without a new budget check, even when the budget ran out in the meantime, so each one replays its recorded effects or stops the run at its pending one; it is never refused and run again in a later epoch. A step that only replays recorded effects is counted once. Later steps, including steps without recorded effects that run again, are checked against the restored counters. Only a step interrupted before it reported its usage goes uncounted; a record stored before in-epoch usage was persisted resumes its open epoch from zero. Restarts are also bounded by maxResumes across the run: the restart after the last allowed one closes the open epoch with resume_limit_reached, so a crash-looping run spends at most (maxRenewals + 1) epoch budgets plus the unreported spend of at most (maxResumes + 1) interrupted steps. The bound covers spend made through recorded effects: spend a step makes outside them is not recorded, so an admitted step repeats it, unchecked, when it runs again after a restart.