--- 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. ```text 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 ```mermaid 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 ```mermaid 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 ```mermaid 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 `/.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 ```mermaid 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 ` 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](assets/dashboard-layout.html) — stacked narrative with gate output drawer (accepted review) - [Dashboard states](assets/dashboard-states.html) — 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 start` runs 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; `none` means uncapped. - [ ] State persists in project-local SQLite at the default path or `loop.statePath`; runs, attempts, and events survive restart. - [ ] `/loop resume ` re-arms a run with consumed turn/attempt budgets preserved and the time budget restarted. - [ ] `/loop guide` arms a guided session; `loop_begin` starts 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`, and `check` tasks and root `//:check`.