AGENTS.md@packages/pi-goal git:20260706.b034cb5A

Immutable. This exact content is served forever at /api/v1/blob/98063776b029739c.

# pi-goal

Persistent per-thread goal tracking as a Pi extension, vendored from the standalone
`code-yeongyu/pi-goal` repository into this monorepo as `@oh-my-opencode/pi-goal`
(private workspace package, Adapter layer: Pi-harness-coupled).

Registers the Codex-style `create_goal` / `update_goal` / `get_goal` tools plus the
`/goal` command, persists one goal per thread to a JSON file under the active session
directory, renders a Codex-style TUI footer indicator, and re-engages the agent toward
an active goal via hidden continuation prompts (`pi-goal-continuation` custom messages).

## Anatomy

| Path | Purpose |
|------|---------|
| `src/index.ts` | Extension entry: tools + `/goal` command + session/agent lifecycle + usage accounting |
| `src/goal/store.ts` | File persistence: read/write/create/update/clear/accountGoalUsage + status transitions |
| `src/goal/types.ts` | `Goal`, `GoalStatus` (`active\|paused\|budgetLimited\|complete`), store/file/tool types |
| `src/goal/prompt.ts` | Continuation + budget-limited hidden prompt builders |
| `src/goal/continuation.ts` | Continuation gating predicates |
| `src/goal/format.ts` | Tool/UI formatting + tool JSON response snapshots |
| `src/goal/ui.ts` | Codex-style TUI footer replacement component |
| `src/goal/command.ts` | `/goal` argument parsing (show/pause/resume/clear/setObjective) |
| `src/goal/validation.ts` | Objective + token budget validation |
| `src/goal/errors.ts` | Typed store errors |
| `test/` | Vendored characterization suite (bun:test; assertions identical to upstream) |
| `scripts/qa/drive.mjs` | Live QA driver: real pi CLI in RPC mode, isolated `PI_CODING_AGENT_DIR`, scripted mock provider, `--self-test` |
| `scripts/qa/mock-provider/` | Self-contained scripted provider extension (no network, no keys) |

## Conventions

- Vendored source: keep diffs against upstream intentional and reviewable. Tests were
  converted vitest -> bun:test with byte-identical assertions; the fake clock is anchored
  at a non-zero epoch because Bun's `setSystemTime(new Date(0))` acts as a reset.
- Peer deps (`@mariozechner/pi-*`, `typebox`) resolve from the host Pi runtime; pinned
  devDependencies exist only for typecheck + tests + live QA.
- This package is not wired into any OpenCode/Codex/omo-senpi component. It ships as a
  standalone Pi package surface (`pi.extensions` manifest field).

## QA

```sh
bun test packages/pi-goal                      # unit/characterization gate
tsgo --noEmit -p packages/pi-goal/tsconfig.json
node packages/pi-goal/scripts/qa/drive.mjs --self-test
node packages/pi-goal/scripts/qa/drive.mjs     # live pi-harness proof (RPC mode, sandboxed)
```

The live driver is the real-harness gate: unit tests alone never prove the extension
works under pi. Evidence goes to `.omo/evidence/<date>-<slug>/`.