Evan Reichard
5c5cdb3aec
- Extract validateAgent, toToolResult, runAgentWithRetries so index.ts is wiring only; orchestration, validation, and result shaping each own their concern. - Separate runner internals: createRunState, handleEvent (pure event reducer), spawnPi (process lifecycle), runOnce (single attempt). - Track attempt/maxAttempts on SubagentStatus; surface "try x/y" in the UI without overwriting the user-facing task with the retry preamble. - Replace pi's default system prompt (--system-prompt) instead of appending, so the subagent .md body is authoritative. - Document prompt-replacement and retry/cache semantics in AGENTS.md.
36 lines
1.5 KiB
Markdown
36 lines
1.5 KiB
Markdown
# Repo Guidelines
|
|
|
|
## Scope
|
|
|
|
This repo implements the `subagent` pi extension in `index.ts`.
|
|
|
|
## Key Behavior
|
|
|
|
- Parent-facing tool: `subagent`.
|
|
- Internal child-only tool: `subagent_finalize`.
|
|
- Never register `subagent_finalize` in the parent context; only when `PI_SUBAGENT_CHILD=1`.
|
|
- Subagent sessions are sticky and persisted at:
|
|
`~/.pi/subagent-sessions/<cwd-hash>/<agent>_<sessionId>.jsonl`.
|
|
- Omitting `sessionId` creates a new UUID-backed session.
|
|
- Passing `sessionId` resumes the same agent/cwd child session.
|
|
- A prompt's `.md` body **replaces** pi's default system prompt (passed via `--system-prompt`). It is the entire system prompt; do not write it as an appendage. Pi still tacks on AGENTS.md/skills/date/cwd.
|
|
- Retries reuse the same session and append a new user message nudging the child to finalize. The system prompt is stable across attempts (cache-friendly).
|
|
|
|
## Validation
|
|
|
|
- Child agents must finish by calling `subagent_finalize`.
|
|
- Valid success: `status=SUCCESS` with non-empty `result`.
|
|
- Valid error: `status=ERROR` with non-empty `error`; `result` is optional partial findings.
|
|
- If finalization is missing/invalid, retry by continuing the same sticky session, capped by `MAX_FINALIZE_RETRIES`.
|
|
|
|
## Commands
|
|
|
|
- Typecheck: `npm run typecheck`
|
|
- Lint: `npm run lint`
|
|
|
|
## Style
|
|
|
|
- Keep the extension simple; avoid debug metadata unless needed.
|
|
- Do not expose retry internals to the parent by default.
|
|
- Prefer precise tool/context isolation over prompt-only enforcement.
|