Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

.system/specs/PX-SPEC-IJGV4GGK-goal-gated-agent-loop/index.md

Raw
Rendered preview

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 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 <id|latest> 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.
---
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 `<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

```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 <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](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 <id|latest>` 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`.