Michael Freno
087c64ff18
- Cap commit diffs in review/commit prompts at 50KB to prevent context window overflow on follow-up sessions - Skip skills catalog (noSkills) in commit/review follow-up sessions for leaner context - Wire Pi's SettingsManager into runAgentSession so Pi's built-in retry (exponential backoff, provider retry) applies to ralpi sessions — removes ralpi's duplicate manual retry loop - Remove maxRetries/retryDelayMs from ralpi config; rely on Pi's retry.* settings (with manual override support) - Remove retries field from progress.json and incrementRetry() from ProgressTracker - Add model failover to follow-up sessions (commit/review cycle through the model pool on connection errors) - Namespace reflection files by PRD key under .ralpi/reflections/<prdKey>/ so task sets don't overwrite each other - Skip loop-startup prompts for config fields explicitly set in YAML - Remove (default) annotations from loop options prompts - Default commitTimeoutMs/reviewTimeoutMs to 0 (inherit Pi defaults)
74 lines
3.2 KiB
Markdown
74 lines
3.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## What this is
|
|
|
|
A Pi coding agent extension that registers the `/ralpi` slash command. Not a standalone app — it runs inside Pi's extension host.
|
|
|
|
## Type checking
|
|
|
|
```
|
|
npm run typecheck # tsc --noEmit
|
|
```
|
|
|
|
No build step needed — Pi loads extensions via [jiti](https://github.com/unjs/jiti), which compiles TypeScript at runtime. `index.ts` is the entry point directly.
|
|
|
|
## Entry point
|
|
|
|
`index.ts` at repo root (not `src/`). Exports a default function receiving `ExtensionAPI`.
|
|
|
|
## External dependencies
|
|
|
|
The extension imports from Pi SDK packages (not in `package.json` — provided by the host):
|
|
|
|
- `@earendil-works/pi-coding-agent` — `ExtensionAPI`, `ExtensionContext`, `createAgentSession`, etc.
|
|
- `@earendil-works/pi-tui` — `Box`, `Text` for custom message renderer
|
|
|
|
The only real npm dependency is `yaml` (^2.4.0).
|
|
|
|
## Source structure
|
|
|
|
- `index.ts` — extension entry, command routing, UI registration, reload detection
|
|
- `src/` — all logic modules:
|
|
- `parser.ts` — task file parsing (Fio, checkbox, YAML formats)
|
|
- `dag.ts` — Kahn's algorithm dependency resolution, batch planning
|
|
- `executor.ts` — task execution, retry, parallel/sequential modes
|
|
- `progress.ts` — `.ralpi/progress.json` state management
|
|
- `prompts.ts` — prompt generation for spawned agent sessions
|
|
- `reflection.ts` — reflection extraction from agent output
|
|
- `utils.ts` — config loading, progress discovery, `runAgentSession()`
|
|
- `types.ts` — all interfaces and `DEFAULT_CONFIG`
|
|
- `widget-batcher.ts` — debounced widget updates for parallel tasks
|
|
- `constants.ts` — static constants
|
|
- `skills/ralpi-use.md` — Pi skill definition for task execution
|
|
- `prompts/task-manager.md` — Pi prompt for task planning
|
|
|
|
## Runtime state
|
|
|
|
All runtime state lives in `.ralpi/` in the **project directory** (not this extension directory):
|
|
|
|
- `.ralpi/progress.json` — execution progress, supports multiple PRDs
|
|
- `.ralpi/reflections/` — per-task reflection JSON files
|
|
- `.ralpi/prompts/` — generated prompts (timestamped, for debugging)
|
|
- `.ralpi/sessions/` — full session transcripts
|
|
|
|
## Task ID convention
|
|
|
|
Task IDs are zero-padded strings (`"01"`, `"02"`, etc.). The parser prepends `0` to parsed digits. Never use raw numeric IDs.
|
|
|
|
## Command routing
|
|
|
|
`/ralpi` with no args → plan. First token looks like a path (`@path`, `./path`, `.md`, etc.) → run. Otherwise dispatches to subcommand (`run`, `plan`, `resume`, `reset`).
|
|
|
|
## Config
|
|
|
|
Read from `.ralpi/config.yaml` in project directory (and global `~/.pi/ralpi/config.yaml`). Falls back to `DEFAULT_CONFIG` in `src/types.ts` when files are missing. Config is loaded at `projectDir` level, not extension level.
|
|
|
|
Key config fields in `execution`:
|
|
|
|
- `autoCommit` / `autoReview` — toggle follow-up commit and review agent sessions (also selectable at loop startup via `selectLoopOptions`)
|
|
- `models` — round-robin model list for parallel mode
|
|
- `implModel` / `commitModel` / `reviewModel` — `<provider>/<model>` strings resolved via `resolveModelSpec` in `utils.ts`
|
|
- `commitTimeoutMs` / `reviewTimeoutMs` — timeouts for follow-up sessions
|
|
- `loopTimeoutMs` — max total loop duration in ms (0 = no limit; checked between batches in `executePlanBatches`)
|
|
- `timeoutMs` — per-task execution timeout
|