id: PX-SPEC-IJGV4GGK type: spec title: Goal-Gated Agent Loop
Goal-Gated Agent Loop
Extension loop runs an agent in an autonomous goal–gate loop inside any project.
Intent: port onyx's research loop — goal, gate, looping, site — as a generalized, higher-quality Pi extension; onyx itself stays untouched.
Scope
In: multi-gate evaluation, budgeted looping, guided goal/gate brainstorm, project-local persisted state, resume, local observation site, command surface with completions. Out: onyx changes, device orchestration, domain evidence tables, prompt generation inside gates, remote or shared dashboards.
Run model
A run binds a goal, an ordered gate list, a working directory, and budgets.
gate = { name?, command, args?, env?, cwd? }
budgets = { minutes, turns, attempts } // each null = uncapped
A gate is a raw executable with arguments and environment; no interpreter is baked in. Success means exit code 0 for every gate. One attempt is one ordered pass over the gate list, stopping at the first failure. Gate output is untrusted diagnostic data; only the configured exit codes complete a run, and the loop prompt forbids redefining gates or verification machinery to manufacture a pass.
Lifecycle
stateDiagram-v2
[*] --> Idle
Idle --> Guided: /loop guide
Guided --> Active: loop_begin armed start
Idle --> Active: /loop start baseline gates
Active --> Active: gate fail, inject prompt
Active --> Succeeded: all gates exit 0
Active --> Paused: escape, budget exhausted, abort, /loop pause
Paused --> Active: /loop resume
Active --> Stopped: /loop stop
Paused --> Stopped: /loop stop
Succeeded --> [*]
Stopped --> [*]
A run never auto-resumes across session switch, fork, tree change, shutdown, or process restart; only explicit /loop resume re-arms it.
On resume, consumed turns and attempts persist against their budgets while the time budget restarts.
Loop cycle
sequenceDiagram
participant A as Agent
participant L as loop
participant G as Gates
A->>L: agent settles (agent_end)
L->>G: run gates in order
alt all exit 0
L-->>A: run succeeded, stop
else any gate fails
L->>A: inject goal + failing gate + budgets (before_settle)
A->>A: next turn continues
end
turn_start counts turns and enforces the turn budget.
An idle active run is kicked by a 2-second watchdog.
Escape during baseline pauses the run; stop/pause as user input also pause.
An aborted agent turn pauses the active run.
State
erDiagram
RUN ||--|{ GATE_ATTEMPT : evaluates
RUN ||--o{ EVENT : audits
RUN {
string goal
string gates
string cwd
string budgets
string status
}
GATE_ATTEMPT {
int attempt_no
int gate_index
int exit_code
string stdout
string stderr
}
State is project-local SQLite, default <cwd>/.pi/loop/state.db, overridable by the loop.statePath setting through the generated settings helper.
Tables: runs, gate_attempts, events.
Audit keeps control events over telemetry: when the pending event queue overflows, turn/continue records are dropped first and a gap marker is recorded.
Whether the state file is committed is the project maintainers' decision; guided mode and the README advise on the trade-off.
Guided mode
flowchart LR
guide["/loop guide"] --> arm["arm guided session"]
arm --> inject["brainstorm prompt injected"]
inject --> interview["agent interviews user, derives goal + gates from project context"]
interview --> begin["agent calls loop_begin"]
begin --> active["run starts, baseline gates run"]
/loop guide [minutes turns attempts] arms a guided session and injects a brainstorm prompt.
The agent derives goal and gates from project context (instructions, task runner surface, repository shape) in the project's own style.
The loop_begin tool starts the run and is callable only while a guided session is armed; any other start path rejects it.
Guided mode may advise on gitignoring the state file when it detects the default path inside an unignored repository location.
Commands
/loop start|guide|resume|pause|stop|status|view|list with getArgumentCompletions offering subcommands, none, and run ids.
/loop start [minutes turns attempts] collects the goal and gates JSON via editors and runs the baseline gate pass.
/loop resume <id|latest> re-arms a persisted run.
/loop view serves the site URL.
Site
A token-protected local HTTP server with SSE push, nugu light/dark palettes, desktop browser target. The accepted target design: stacked narrative — run card with status eyebrow and budget badges, gate strip with per-gate results and an output drawer on the failing gate, attempt/turn timeline, event feed, collapsible run history, and terminal-state banners for succeeded and paused runs.
- Dashboard layout — stacked narrative with gate output drawer (accepted review)
- Dashboard states — succeeded and paused banners with resume affordance (accepted review)
Quality bar over onyx
Tool calls and results render through the repository's renderer conventions; the status line reflects the active run. The injected prompt keeps a stable prefix and bounded, refreshed gate output so context does not accumulate across attempts. Debug logging follows the generated schema-bound debug contract; settings follow the generated settings contract. The extension declares its own Mise tasks, stays sibling-isolated, and writes no diagnostics to machine-readable stdout.
Acceptance criteria
-
/loop startruns the baseline gate pass and enters the loop with uncapped or explicit budgets. - A run succeeds only when every configured gate exits 0 in one ordered pass; no tool output or model claim can complete it.
- One attempt equals one full gate-list pass stopping at the first failure; the next prompt names the failing gate with bounded output.
- Escape, user pause/stop, abort, and session switch/fork/shutdown pause or stop the active run; no path auto-resumes it.
- Minutes, turns, and attempts budgets each interrupt the run when exhausted;
nonemeans uncapped. - State persists in project-local SQLite at the default path or
loop.statePath; runs, attempts, and events survive restart. -
/loop resume <id|latest>re-arms a run with consumed turn/attempt budgets preserved and the time budget restarted. -
/loop guidearms a guided session;loop_beginstarts a run only while armed and is rejected otherwise. - Command completions offer subcommands,
none, and persisted run ids. - The site renders the accepted stacked design with live SSE updates: run card, gates with output drawer, timeline, events, history, and state banners behind a token.
- The loop prompt is anti-cheat hardened, cache-stable in prefix, and bounded in gate output.
- The extension passes its own
lint,test, andchecktasks and root//:check.