Expand description
Goal loop orchestrator — the persistent-objective control layer (#3215, and its lineage #891 / #1976 / #2058 / #2029).
This is the Workflow goal layer: the decision core that turns a one-shot
/goal into a persistent work loop. Given the durable goal status, the
accumulated usage (from the per-goal accounting wired in crates/state
record_thread_goal_usage), and a budget, it decides whether to continue
(re-dispatch another worker turn toward the objective) or stop with a
terminal status. It is the orchestrator in the Workflow≈ultracode mapping —
the loop that fans work out to workers (worker_profile) and verifies before
committing.
Scope: decision logic + types. The engine (core/engine.rs) reads the
SharedGoalState snapshot after each turn and calls decide_continuation
to decide whether to re-dispatch. For operate-mode goals the terminal stops
are a verified completion, a blocked report, the stall pause that fires
when a critical verifier reports the same gap set
MAX_REPEATED_GAP_PASSES times running (enforced in
GoalState::record_not_achieved), and the opt-in continuation backstop
([goal] max_continuations); token/time accounting stays visible as
telemetry but does not gate continuation — spend is bounded by stalling,
not by a pass count, like grokbuild (DEFAULT_AGENT_BUDGET as call cap)
and kimicode swarm (turnBudget per-task, resumable after
budget-reached). Log when the backstop fires.
Structs§
- Goal
Budget - The optional token/time bounds on a goal run.
Nonefields mean unbounded for that resource; the continuation backstop (max_continuations) still applies unless configured to0. - Goal
Progress - Accumulated, durable progress for a goal run. Mirrors the fields wired by
crates/staterecord_thread_goal_usage(tokens_used / time_used_seconds) plus a continuation counter the loop maintains.
Enums§
- Continuation
Decision - The decision the loop makes after each worker turn.
- Continuation
Wait Outcome - Outcome of waiting out the between-continuation quiet period.
- Goal
RunStatus - Terminal or active state of a persistent goal.
- Stop
Reason - Why the loop stopped, for a terminal decision.
Constants§
- DEFAULT_
GOAL_ MAX_ STEPS - Compatibility representation of an uncapped goal turn (#6512).
- DEFAULT_
MAX_ GOAL_ CONTINUATIONS - Default automatic cross-turn continuation policy for one goal run (#5052).
- MAX_
GOAL_ CONTINUATION_ DELAY_ SECONDS - Upper bound for one between-turn quiet period. A day is long enough for coordinator cadences while preventing an accidental giant integer from becoming a practically uninterruptible-looking schedule receipt.
- MAX_
REPEATED_ GAP_ PASSES - How many consecutive critical
not_achievedreviews naming the same normalized gap set a goal may accumulate before it pauses itself withGoalPauseReason::NoProgress.
Functions§
- await_
continuation_ wait - Wait out the between-continuation quiet period, honoring cancellation.
Noneresolves immediately so callers have a single dispatch gate: toCancelledwhen the token is already cancelled, otherwiseElapsed. Cancellation is biased and always wins over a racing expiry — the same semantics as the interactive cadence (#5508), including a zero delay. Two dispatchers await this gate: the turn loop’s intra-turn passes (every session), and the runtime host’s cross-turn re-arm for host-managed engines (RuntimeThreadManager::spawn_goal_continuation), which never self-continue. - continuation_
wait - Compute the quiet-period wait for a configured between-continuation delay.
Nonecontinues immediately (unset or zero delay); a positive delay returns the capped wait shared by every dispatch path so no caller can construct an effectively uninterruptible schedule receipt. - decide_
continuation - Decide whether a persistent goal run should continue after a turn.
- is_
success - Whether a stop reason represents success (Completed) vs. an early/forced exit. Useful for the UI/status projection (#2666 token/time visibility).
- token_
budget_ exhausted - Whether the durable token usage has reached an enforced token budget —
the same condition on which
decide_continuationstops withStopReason::BudgetLimit. Budgets are telemetry-only unless[goal] enforce_token_budgetopts in, so without it this stays false and crossing a budget never closes the outbound gate. Preview and the live continuation loop share this predicate so they cannot disagree about spend.