YeonGyu-Kim
1e7a7600a2
Refresh all AGENTS.md files to reflect codebase state at5ffbe0e24(wascd31d2a1a, 197 commits behind). Key drift corrections across 45 modified + 1 new file: Root AGENTS.md: - TS file counts: 1967 -> 2034 in src/ (1337 source + 697 test) - LOC: 278k -> 292k - Barrel index.ts: 120 -> 122 - Hook tier composition: 52/59 -> 54/61 (base/with team-mode) - Tool Guard hooks: 14 -> 16 (add fsync-skip-warning, bash-file-read-guard) - Add boulder feature, agent-ordering schema, .agents/ directory, v4.1.1 release tag - Add generated/ directory entry src/AGENTS.md: - Subsystem inventory: agents 96->102, hooks 570->581, tools 306->314, features 389->400, shared 258->278, cli 150->158, plugin 55->56 - LOC totals refreshed for every subsystem - Schema files: 32 -> 30 src/hooks/AGENTS.md: - Tier 2 (Tool Guard): 14 -> 16 hooks, add fsyncSkipWarning row - Total: 52 base / 59 team-mode -> 54 base / 61 team-mode - zauc-mocks count: 7 -> 5 src/features/AGENTS.md: - background-agent: 47 -> 57 files, mention archive fallback - opencode-skill-loader: 33 -> 30 - tmux-subagent: 34 -> 32 src/plugin/AGENTS.md: - Tool Guard composer count: 14 -> 16 - Aggregator total: 43 -> 45 src/cli/AGENTS.md: - Add new boulder subcommand (BoulderState inspector) - Command count: 6 -> 7 NEW: src/features/boulder-state/AGENTS.md - Document the new Boulder work tracking feature - Schema v2 with BoulderState/BoulderWorkState/TaskSessionState - Lifecycle, storage, integration points with atlas/ralph-loop hooks All other AGENTS.md files: Generated date 2026-05-08 -> 2026-05-14.
63 lines
2.3 KiB
Markdown
63 lines
2.3 KiB
Markdown
# src/hooks/ralph-loop/ — Self-Referential Dev Loop
|
|
|
|
**Generated:** 2026-05-14
|
|
|
|
## OVERVIEW
|
|
|
|
14 files (~1687 LOC). The `ralphLoop` Session Tier hook — powers the `/ralph-loop` command. Iterates a development loop until the agent emits `<promise>DONE</promise>` or max iterations reached.
|
|
|
|
## LOOP LIFECYCLE
|
|
|
|
```
|
|
/ralph-loop → startLoop(sessionID, prompt, options)
|
|
→ loopState.startLoop() → persists state to .sisyphus/ralph-loop.local.md
|
|
→ session.idle events → createRalphLoopEventHandler()
|
|
→ completionPromiseDetector: scan output for <promise>DONE</promise>
|
|
→ if not done: inject continuation prompt → loop
|
|
→ if done or maxIterations: cancelLoop()
|
|
```
|
|
|
|
## KEY FILES
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `ralph-loop-hook.ts` | `createRalphLoopHook()` — composes controller + recovery + event handler |
|
|
| `ralph-loop-event-handler.ts` | `createRalphLoopEventHandler()` — handles session.idle, drives loop |
|
|
| `loop-state-controller.ts` | State CRUD: startLoop, cancelLoop, getState, persist to disk |
|
|
| `loop-session-recovery.ts` | Recover from crashed/interrupted loop sessions |
|
|
| `completion-promise-detector.ts` | Scan session transcript for `<promise>DONE</promise>` |
|
|
| `continuation-prompt-builder.ts` | Build continuation message for next iteration |
|
|
| `continuation-prompt-injector.ts` | Inject built prompt into active session |
|
|
| `storage.ts` | Read/write `.sisyphus/ralph-loop.local.md` state file |
|
|
| `message-storage-directory.ts` | Temp dir for prompt injection |
|
|
| `with-timeout.ts` | API call wrapper with timeout (default 5000ms) |
|
|
| `types.ts` | `RalphLoopState`, `RalphLoopOptions`, loop iteration types |
|
|
|
|
## STATE FILE
|
|
|
|
```
|
|
.sisyphus/ralph-loop.local.md (gitignored)
|
|
→ sessionID, prompt, iteration count, maxIterations, completionPromise, ultrawork flag
|
|
```
|
|
|
|
## OPTIONS
|
|
|
|
```typescript
|
|
startLoop(sessionID, prompt, {
|
|
maxIterations?: number // Default from config (default: 100)
|
|
completionPromise?: string // Custom "done" signal (default: "<promise>DONE</promise>")
|
|
ultrawork?: boolean // Enable ultrawork mode for iterations
|
|
})
|
|
```
|
|
|
|
## EXPORTED INTERFACE
|
|
|
|
```typescript
|
|
interface RalphLoopHook {
|
|
event: (input) => Promise<void> // session.idle handler
|
|
startLoop: (sessionID, prompt, options?) => boolean
|
|
cancelLoop: (sessionID) => boolean
|
|
getState: () => RalphLoopState | null
|
|
}
|
|
```
|