YeonGyu-Kim
9f6d0d2281
- Bump root AGENTS.md header: 2026-05-14 → 2026-05-15, commit5ffbe0e24→53a740636, release v4.1.1 → v4.1.2 - Update file counts: 2034 (1337+697) → 2041 (1340+701), LOC ~292k → ~294k - Fix STRUCTURE: openclaw lives at src/openclaw/ (not src/features/); list more accurate feature modules in the parenthetical - Clarify interactive_bash gate: tmux binary on PATH via isInteractiveBashEnabled() (not 'tmux enabled') - Fix docs/reference/features.md hook counts: Tool Guard 14→16, Total base 52→54, total with team-mode 59→61 - Bump 'Generated' date on all 43 subdir AGENTS.md files to 2026-05-15 - Preserve promptAsync injection cautions verbatim (per request)
66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
# src/hooks/todo-continuation-enforcer/ — Boulder Continuation Mechanism
|
|
|
|
**Generated:** 2026-05-15
|
|
|
|
## OVERVIEW
|
|
|
|
14 files (~2061 LOC). The "boulder" — Continuation Tier hook that forces Sisyphus to keep rolling when incomplete todos remain. Fires on `session.idle`, injects continuation prompt after 2s countdown toast.
|
|
|
|
## HOW IT WORKS
|
|
|
|
```
|
|
session.idle
|
|
→ Is main session (not prometheus/compaction)? (DEFAULT_SKIP_AGENTS)
|
|
→ No abort detected recently? (ABORT_WINDOW_MS = 3s)
|
|
→ Todos still incomplete? (todo.ts)
|
|
→ No background tasks running?
|
|
→ Cooldown passed? (CONTINUATION_COOLDOWN_MS = 30s)
|
|
→ Failure count < max? (MAX_CONSECUTIVE_FAILURES = 5)
|
|
→ Start 2s countdown toast → inject CONTINUATION_PROMPT
|
|
```
|
|
|
|
## KEY FILES
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `handler.ts` | `createTodoContinuationHandler()` — event router, delegates to idle/non-idle handlers |
|
|
| `idle-event.ts` | `handleSessionIdle()` — main decision gate for session.idle |
|
|
| `non-idle-events.ts` | `handleNonIdleEvent()` — handles session.error (abort detection) |
|
|
| `session-state.ts` | `SessionStateStore` — per-session failure/abort/cooldown state |
|
|
| `todo.ts` | Check todo completion status via session store |
|
|
| `countdown.ts` | 2s countdown toast before injection |
|
|
| `abort-detection.ts` | Detect MessageAbortedError / AbortError |
|
|
| `continuation-injection.ts` | Build + inject CONTINUATION_PROMPT into session |
|
|
| `message-directory.ts` | Temp dir for message injection exchange |
|
|
| `constants.ts` | Timing constants, CONTINUATION_PROMPT, skip agents |
|
|
| `types.ts` | `SessionState`, handler argument types |
|
|
|
|
## CONSTANTS
|
|
|
|
```typescript
|
|
DEFAULT_SKIP_AGENTS = ["prometheus", "compaction", "plan"]
|
|
CONTINUATION_COOLDOWN_MS = 30_000 // 30s between injections
|
|
MAX_CONSECUTIVE_FAILURES = 5 // Then 5min pause (exponential backoff)
|
|
FAILURE_RESET_WINDOW_MS = 5 * 60_000 // 5min window for failure reset
|
|
COUNTDOWN_SECONDS = 2
|
|
ABORT_WINDOW_MS = 3000 // Grace after abort signal
|
|
```
|
|
|
|
## STATE PER SESSION
|
|
|
|
```typescript
|
|
interface SessionState {
|
|
failureCount: number // Consecutive failures
|
|
lastFailureAt?: number // Timestamp
|
|
abortDetectedAt?: number // Reset after ABORT_WINDOW_MS
|
|
cooldownUntil?: number // Next injection allowed after
|
|
countdownTimer?: Timer // Active countdown reference
|
|
}
|
|
```
|
|
|
|
## RELATIONSHIP TO ATLAS
|
|
|
|
`todoContinuationEnforcer` handles **main Sisyphus sessions** only.
|
|
`atlasHook` handles **boulder/ralph/subagent sessions** with a different decision gate.
|
|
Both fire on `session.idle` but check session type first.
|