AGENTS.md

1# pi-goal
2 
3Persistent per-thread goal tracking as a Pi extension, vendored from the standalone
4`code-yeongyu/pi-goal` repository into this monorepo as `@oh-my-opencode/pi-goal`
5(private workspace package, Adapter layer: Pi-harness-coupled).
6 
7Registers the Codex-style `create_goal` / `update_goal` / `get_goal` tools plus the
8`/goal` command, persists one goal per thread to a JSON file under the active session
9directory, renders a Codex-style TUI footer indicator, and re-engages the agent toward
10an active goal via hidden continuation prompts (`pi-goal-continuation` custom messages).
11 
12## Anatomy
13 
14| Path | Purpose |
15|------|---------|
16| `src/index.ts` | Extension entry: tools + `/goal` command + session/agent lifecycle + usage accounting |
17| `src/goal/store.ts` | File persistence: read/write/create/update/clear/accountGoalUsage + status transitions |
18| `src/goal/types.ts` | `Goal`, `GoalStatus` (`active\|paused\|blocked\|budgetLimited\|complete`), store/file/tool types |
19| `src/goal/prompt.ts` | Continuation + budget-limited hidden prompt builders |
20| `src/goal/continuation.ts` | Continuation gating predicates |
21| `src/goal/format.ts` | Tool/UI formatting + tool JSON response snapshots |
22| `src/goal/ui.ts` | Codex-style TUI footer replacement component |
23| `src/goal/command.ts` | `/goal` argument parsing (show/pause/resume/clear/setObjective) |
24| `src/goal/validation.ts` | Objective + token budget validation |
25| `src/goal/errors.ts` | Typed store errors |
26| `test/` | Vendored characterization suite (bun:test; assertions identical to upstream) |
27| `scripts/qa/drive.mjs` | Live QA driver: real pi CLI in RPC mode, isolated `PI_CODING_AGENT_DIR`, scripted mock provider, `--self-test` |
28| `scripts/qa/mock-provider/` | Self-contained scripted provider extension (no network, no keys) |
29 
30## Codex alignment
31 
32The goal tool contract is aligned with codex `codex-rs/ext/goal`:
33 
34- `update_goal` accepts `complete` and `blocked` (codex `spec.rs` enum); `blocked` is a real,
35  model-settable, non-terminal status (resumable via `/goal resume`).
36- `create_goal` replaces only a `complete` goal and otherwise fails with the codex
37  "unfinished goal" message.
38- Tool/parameter descriptions, the `update_goal` error text, and the completion budget report
39  match codex verbatim; `budgetLimited` is preserved when `paused` or `blocked` is requested.
40- The hidden continuation and budget-limit prompts use the codex `templates/goals/*.md`
41  content (`<objective>` tag; the continuation prompt carries the Continuation behavior /
42  Work from evidence / Progress visibility / Fidelity / Completion audit / Blocked audit
43  sections). The budget-limit prompt is queued at most once per goal id.
44- Continuation is not queued after a turn that did not end cleanly (last assistant
45  `stopReason` is `error`, or the last tool result was aborted), mirroring codex's
46  turn-error loop prevention (codex sets the goal `blocked`; pi's harness has no turn-error
47  signal, so it gates the auto-continuation instead).
48- Deliberate deviation: pi omits `usage_limited` (codex sets it from a system
49  `UsageLimitExceeded` turn error, not the model; the Pi harness exposes no such signal).
50 
51## Conventions
52 
53- Vendored source: keep diffs against upstream intentional and reviewable. Tests were
54  converted vitest -> bun:test with byte-identical assertions; the fake clock is anchored
55  at a non-zero epoch because Bun's `setSystemTime(new Date(0))` acts as a reset.
56- Peer deps (`@mariozechner/pi-*`, `typebox`) resolve from the host Pi runtime; pinned
57  devDependencies exist only for typecheck + tests + live QA.
58- This package is not wired into any OpenCode/Codex/omo-senpi component. It ships as a
59  standalone Pi package surface (`pi.extensions` manifest field).
60 
61## QA
62 
63```sh
64bun test packages/pi-goal                      # unit/characterization gate
65tsgo --noEmit -p packages/pi-goal/tsconfig.json
66node packages/pi-goal/scripts/qa/drive.mjs --self-test
67node packages/pi-goal/scripts/qa/drive.mjs     # live pi-harness proof (RPC mode, sandboxed)
68```
69 
70The live driver is the real-harness gate: unit tests alone never prove the extension
71works under pi. Evidence goes to `.omo/evidence/<date>-<slug>/`.
72