# Reference

## Public exports

The default export is the Pi extension initializer. `src/index.ts` also exports `GoalManager` and all exports from `contract`, `judge`, `persistence`, `progress`, `scheduler`, `state`, and `verifier`.

Useful functions include `parseGoalCreation`, `validateGoalContract`, `parseVerificationCommand`, `tokenizeShellLike`, `evaluateCompletion`, `parseJudgeVerdict`, `runVerification`, `runVerificationStep`, `truncateVerifierOutput`, `verificationFailureVerdict`, `createGoalState`, `createRuntimeState`, `resetRunState`, `totalGoalTokens`, `calculateProgress`, and `toolSignature`.

## LLM tools

`goal_set` creates or replaces a persistent goal only for an explicit goal-setting request in the user's current message. Its parameters are `objective`, optional `criteria`, and optional `constraints`. Goals are not iteration- or token-limited. It does not expose verifier configuration. `goal_get`, `goal_complete`, and `goal_blocked` inspect, audit, and block active work respectively.

## Persistent state

`GoalState` has schema version `1` and includes:

| Field | Meaning |
| --- | --- |
| `goalId`, `revision` | UUID-like goal identity and contract/state revision. |
| `contract` | Objective, criteria, constraints, approved verifiers. |
| `status`, `statusReason` | Current lifecycle state and optional explanation. |
| `iterationCount` | Settled runs completed. |
| `maxNoProgressIterations`, `noProgressIterations` | Repeat-cycle threshold and current count. |
| progress fingerprints | Last combined evidence/response hashes and normalized response. |
| cumulative token fields | Total worker usage for observability; not a limit. |
| `judge` | `{mode:"same"}` or `{mode:"model",provider,model}`. |
| timestamps | Epoch milliseconds for creation and latest update. |
| `lastVerdict`, `lastVerification`, `blocker` | Latest completion evidence and debounced blocker information. |

`VerificationResult` includes the original command definition plus resolved cwd; exit code, stdout/stderr, kill/timeout/duration/pass status; and truncation metadata for both streams. `GoalVerdict` includes decision, reason, unmet criteria, optional next instruction, evaluation time, and optional model id.

Runtime state is intentionally non-persistent: continuation/evaluator controls, generation, shutdown flag, per-run tools/results/response/tokens, and blocker claim flags. State cloning uses `structuredClone` to avoid callers mutating the manager’s owned object.

## Custom entries and messages

| Identifier | Payload/use |
| --- | --- |
| `pi-let.goal.state.v1` | `GoalSnapshot`: schema version, event, state (or null), optional reason, timestamp. |
| `pi-let.goal.transition.v1` | Expandable display projection of a snapshot. |
| `pi-let.goal.continue.v1` | Hidden initial/continuation message, carrying goal identity/revision/generation details. |
| `pi-let.goal.report.v1` | JSON-mode status report event. |

Snapshot events are `created`, `updated`, `paused`, `resumed`, `cleared`, `restored_paused`, `iteration`, `verifying`, `verifier_rejected`, `judge_rejected`, `judge_approved`, `complete`, `blocked`, `archived`, and `evaluator_error`. Legacy `budget_limited` snapshots remain readable but are never produced for new work.

## User interface and output

In UI modes, pi-let keeps status key `pi-let.goal` and a widget showing the shortened objective plus pending-criterion count. Status shows evaluator activity, active turn count, and a shortened blocked reason where applicable. Continuation messages collapse to “Autonomous goal continuation”; transition entries can expand to reason and local timestamp.

In print mode, status and terminal messages are plain text and no dialog editor is called. In JSON mode, reports are JSON Lines:

```json
{"type":"pi-let.goal.report.v1","message":"..."}
```

A status report contains status, objective, iterations, total token usage, judge selection, criterion/verifier counts, reason, latest verdict and gaps, and latest verifier pass/fail outcomes. Terminal reports include remaining judge gaps and failed verifier exit evidence.