Skip to main content

Module goal_loop

Module goal_loop 

Source
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§

GoalBudget
The optional token/time bounds on a goal run. None fields mean unbounded for that resource; the continuation backstop (max_continuations) still applies unless configured to 0.
GoalProgress
Accumulated, durable progress for a goal run. Mirrors the fields wired by crates/state record_thread_goal_usage (tokens_used / time_used_seconds) plus a continuation counter the loop maintains.

Enums§

ContinuationDecision
The decision the loop makes after each worker turn.
ContinuationWaitOutcome
Outcome of waiting out the between-continuation quiet period.
GoalRunStatus
Terminal or active state of a persistent goal.
StopReason
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_achieved reviews naming the same normalized gap set a goal may accumulate before it pauses itself with GoalPauseReason::NoProgress.

Functions§

await_continuation_wait
Wait out the between-continuation quiet period, honoring cancellation. None resolves immediately so callers have a single dispatch gate: to Cancelled when the token is already cancelled, otherwise Elapsed. 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. None continues 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_continuation stops with StopReason::BudgetLimit. Budgets are telemetry-only unless [goal] enforce_token_budget opts 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.