@fractaal/pi-goal-x 0.20.1 → 0.28.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +38 -293
- package/dist/goal-auditor.d.ts +7 -61
- package/dist/goal-auditor.js +98 -300
- package/dist/goal-auditor.js.map +1 -1
- package/dist/goal-contract.d.ts +205 -0
- package/dist/goal-contract.js +135 -0
- package/dist/goal-contract.js.map +1 -0
- package/dist/goal-transcript-events.d.ts +54 -0
- package/dist/goal-transcript-events.js +177 -0
- package/dist/goal-transcript-events.js.map +1 -0
- package/dist/goal-widget.d.ts +13 -0
- package/dist/goal-widget.js +45 -0
- package/dist/goal-widget.js.map +1 -0
- package/dist/goal.d.ts +8 -49
- package/dist/goal.js +581 -3648
- package/dist/goal.js.map +1 -1
- package/dist/legacy-migration.d.ts +61 -0
- package/dist/legacy-migration.js +306 -0
- package/dist/legacy-migration.js.map +1 -0
- package/docs/architecture.md +14 -232
- package/extensions/goal-auditor.ts +108 -363
- package/extensions/goal-contract.ts +149 -0
- package/extensions/goal-transcript-events.ts +194 -0
- package/extensions/goal-widget.ts +50 -0
- package/extensions/goal.ts +602 -3920
- package/extensions/legacy-migration.ts +340 -0
- package/package.json +46 -21
- package/dist/goal-compaction.d.ts +0 -10
- package/dist/goal-compaction.js +0 -104
- package/dist/goal-compaction.js.map +0 -1
- package/dist/goal-core.d.ts +0 -19
- package/dist/goal-core.js +0 -66
- package/dist/goal-core.js.map +0 -1
- package/dist/goal-draft.d.ts +0 -71
- package/dist/goal-draft.js +0 -201
- package/dist/goal-draft.js.map +0 -1
- package/dist/goal-ledger.d.ts +0 -139
- package/dist/goal-ledger.js +0 -306
- package/dist/goal-ledger.js.map +0 -1
- package/dist/goal-policy.d.ts +0 -127
- package/dist/goal-policy.js +0 -359
- package/dist/goal-policy.js.map +0 -1
- package/dist/goal-pool.d.ts +0 -17
- package/dist/goal-pool.js +0 -85
- package/dist/goal-pool.js.map +0 -1
- package/dist/goal-questionnaire.d.ts +0 -56
- package/dist/goal-questionnaire.js +0 -733
- package/dist/goal-questionnaire.js.map +0 -1
- package/dist/goal-record.d.ts +0 -94
- package/dist/goal-record.js +0 -155
- package/dist/goal-record.js.map +0 -1
- package/dist/goal-settings.d.ts +0 -56
- package/dist/goal-settings.js +0 -184
- package/dist/goal-settings.js.map +0 -1
- package/dist/goal-tool-names.d.ts +0 -20
- package/dist/goal-tool-names.js +0 -69
- package/dist/goal-tool-names.js.map +0 -1
- package/dist/prompts/goal-prompts.d.ts +0 -17
- package/dist/prompts/goal-prompts.js +0 -304
- package/dist/prompts/goal-prompts.js.map +0 -1
- package/dist/storage/goal-files.d.ts +0 -40
- package/dist/storage/goal-files.js +0 -320
- package/dist/storage/goal-files.js.map +0 -1
- package/dist/widgets/goal-escape-dialog.d.ts +0 -15
- package/dist/widgets/goal-escape-dialog.js +0 -118
- package/dist/widgets/goal-escape-dialog.js.map +0 -1
- package/dist/widgets/goal-notifications.d.ts +0 -5
- package/dist/widgets/goal-notifications.js +0 -9
- package/dist/widgets/goal-notifications.js.map +0 -1
- package/dist/widgets/goal-widget.d.ts +0 -58
- package/dist/widgets/goal-widget.js +0 -282
- package/dist/widgets/goal-widget.js.map +0 -1
- package/dist/widgets/task-list-overlay.d.ts +0 -8
- package/dist/widgets/task-list-overlay.js +0 -321
- package/dist/widgets/task-list-overlay.js.map +0 -1
- package/docs/agent-flow-design.md +0 -432
- package/docs/agentic-runtime-prd.md +0 -764
- package/docs/goal-ts-refactor-test-strategy.md +0 -82
- package/docs/pi-autoresearch-survey.md +0 -45
- package/extensions/goal-compaction.ts +0 -133
- package/extensions/goal-core.ts +0 -77
- package/extensions/goal-draft.ts +0 -263
- package/extensions/goal-ledger.ts +0 -354
- package/extensions/goal-policy.ts +0 -389
- package/extensions/goal-pool.ts +0 -98
- package/extensions/goal-questionnaire.ts +0 -779
- package/extensions/goal-record.ts +0 -256
- package/extensions/goal-settings.ts +0 -181
- package/extensions/goal-tool-names.ts +0 -76
- package/extensions/prompts/goal-prompts.ts +0 -308
- package/extensions/storage/goal-files.ts +0 -352
- package/extensions/widgets/goal-escape-dialog.ts +0 -146
- package/extensions/widgets/goal-notifications.ts +0 -9
- package/extensions/widgets/goal-widget.ts +0 -378
- package/extensions/widgets/task-list-overlay.ts +0 -389
package/README.md
CHANGED
|
@@ -1,318 +1,63 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Portable Goals and Todos for Pi
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This repository contains two independent Pi extensions:
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
- **`@fractaal/pi-goal-x`** — one branch-local Goal with confirmed proposal/tweak, autonomous continuation, pause/resume, abandonment, independent completion audit, final prose settlement, replay, a native widget, and structured events.
|
|
6
|
+
- **`@fractaal/pi-todo`** in [`packages/todo`](packages/todo) — one revisioned branch-local working plan with omission protection, dependency validation, context salience, replay, a native widget, and structured state.
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
They have no runtime dependency on each other and do not import Symphony, Aria, ALR, IPC, RTDB, Gateway, React, or product-specific types.
|
|
8
9
|
|
|
9
|
-
|
|
10
|
-
- **Simple goal creation** — Use `/goals` to discuss and confirm a draft. Use `/goals-set` to skip discussion and start immediately.
|
|
11
|
-
- **Full lifecycle** — Pause blocked goals, resume when unblocked, abort obsolete work, complete when done. Auto-continue keeps the agent working across turns until completion, interruption, or the empty-turn guard.
|
|
12
|
-
- **Session-scoped goals** — Each Pi session keeps its own open goals under `.pi/goals/sessions/<session-id>/`. Switch that session's focus with `/goal-focus`.
|
|
13
|
-
- **Above-editor status widget** — See the current goal, status, file path, and progress at a glance while the agent works.
|
|
14
|
-
- **Structured task lists with subtasks** — Break goals into trackable tasks. Agents can mark individual tasks or subtasks complete without stopping the turn. Subtask IDs are validated for uniqueness and depth.
|
|
15
|
-
- **Verification contracts** — Attach plain-text requirements to a goal or task (e.g. "Run npm test, zero failures"). The agent must provide matching evidence before `complete_goal` or `complete_task` will succeed.
|
|
16
|
-
- **Independent completion auditor** — When a goal is marked complete, a separate pi agent inspects the workspace, verifies every success criterion, and approves or rejects before the goal is archived. You can press Escape during an audit to abort it. Configure the auditor model via `/goal-settings`.
|
|
17
|
-
- **Schema-gated tools** — Agents see only the tools relevant to the current lifecycle phase: drafting, active, paused, or tweaking. Lifecycle tools like `pause_goal`, `complete_task`, and `abort_goal` appear and disappear automatically.
|
|
18
|
-
- **Immutable objective** — The agent cannot silently change your goal. Objective updates require a `/goal-tweak` drafting flow with explicit user confirmation.
|
|
19
|
-
- **Built-in questionnaire tools** — During drafting, agents can ask structured questions through `goal_question` and `goal_questionnaire` without depending on external packages.
|
|
20
|
-
- **Disk-backed state** — Active and archived goals persist under the current session's `.pi/goals/sessions/<session-id>/` directory. Legacy cwd-scoped `.pi/goals/active_goal_*.md` files remain readable and are migrated when an old session resumes.
|
|
21
|
-
- **Configurable settings** — Tune the auditor model, disable the task system or contracts, and set subtask depth through `/goal-settings` or `.pi/pi-goal-x-settings.json`.
|
|
10
|
+
## Goal
|
|
22
11
|
|
|
23
|
-
|
|
12
|
+
Model tools:
|
|
24
13
|
|
|
25
|
-
|
|
14
|
+
- `propose_goal({ objective })`
|
|
15
|
+
- `tweak_goal({ objective })`
|
|
16
|
+
- `pause_goal({ reason, suggestedAction? })`
|
|
17
|
+
- `resume_goal()`
|
|
18
|
+
- `abandon_goal({ reason })`
|
|
19
|
+
- `complete_goal({ summary })`
|
|
26
20
|
|
|
27
|
-
|
|
21
|
+
Events:
|
|
28
22
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
From a local checkout:
|
|
34
|
-
|
|
35
|
-
```bash
|
|
36
|
-
pi install .
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
Try once without installing:
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
pi -e .
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
## Quick start
|
|
46
|
-
|
|
47
|
-
### Regular goal
|
|
48
|
-
|
|
49
|
-
```text
|
|
50
|
-
/goals add structured logging to the auth module
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
Flow:
|
|
54
|
-
|
|
55
|
-
1. The agent clarifies, researches, or grills only when the goal contract needs it.
|
|
56
|
-
2. The agent calls `propose_goal_draft` with a concrete objective once the contract is clear.
|
|
57
|
-
3. pi shows a full plain-text confirmation report.
|
|
58
|
-
4. If confirmed, the full finalized goal is printed into the conversation and written under `.pi/goals/sessions/<session-id>/`.
|
|
59
|
-
5. The new goal becomes this session's focus. Existing open goals in the same session remain selectable later with `/goal-focus`.
|
|
60
|
-
6. The agent works only on the focused goal until it calls `complete_goal`, pauses, aborts, produces an empty/non-progress turn, or the user interrupts.
|
|
61
|
-
|
|
62
|
-
### Sisyphus goal
|
|
63
|
-
|
|
64
|
-
```text
|
|
65
|
-
/sisyphus Refactor the auth flow: 1) extract token validation. 2) wire it into login. 3) update tests.
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
Sisyphus mode is for patient ordered execution. It uses the same lifecycle and tools as a regular goal; the difference is the prompt style and completion standard: preserve the user's order, do not rush, do not invent preflight/reconnaissance steps, and stop to ask when blocked.
|
|
69
|
-
|
|
70
|
-
If the objective is already final and should start immediately, use:
|
|
23
|
+
- `pi-goal:state` — complete `GoalState` snapshot
|
|
24
|
+
- `pi-goal:proposal` — complete current proposal snapshot
|
|
25
|
+
- `pi-goal:transcript-event` — bounded lifecycle receipt
|
|
26
|
+
- `pi-goal:request-state` — asks the producer to replay current state and proposal
|
|
71
27
|
|
|
72
|
-
|
|
73
|
-
/goals-set add structured logging to the auth module
|
|
74
|
-
/sisyphus-set Refactor auth flow exactly as ordered: 1) extract token validation. 2) wire it into login. 3) update tests.
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
## User commands
|
|
78
|
-
|
|
79
|
-
```text
|
|
80
|
-
/goals <topic> Discuss/research/grill a regular goal, then confirm a draft
|
|
81
|
-
/sisyphus <topic> Discuss/grill a Sisyphus-style goal, then confirm a draft
|
|
82
|
-
/goals-set <objective> Immediately create and start a regular goal
|
|
83
|
-
/sisyphus-set <objective> Immediately create and start a Sisyphus-style goal
|
|
84
|
-
/goal-status Show focused goal state
|
|
85
|
-
/goal-list List open goals for this Pi session
|
|
86
|
-
/goal-focus Choose this session's focused goal
|
|
87
|
-
/goal-tweak <change> Draft a revision to the focused active/paused goal
|
|
88
|
-
/goal-pause Pause the focused active goal
|
|
89
|
-
/goal-resume Resume a paused goal
|
|
90
|
-
/goal-settings Configure pi-goal settings, including auditor model settings
|
|
91
|
-
/goal-abort Abort/archive the focused goal or cancel drafting
|
|
92
|
-
/goal-clear Archive the focused goal or cancel drafting
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
Pressing `Esc` or aborting an active run pauses the goal so it does not remain falsely active.
|
|
96
|
-
|
|
97
|
-
## Multiple open goals and focus
|
|
98
|
-
|
|
99
|
-
`pi-goal` separates durable goals from session focus:
|
|
100
|
-
|
|
101
|
-
- **Goal pool**: every open goal for the current Pi session is an `active_goal_*.md` file under `.pi/goals/sessions/<session-id>/`. Legacy cwd-scoped `.pi/goals/active_goal_*.md` files are read only for compatibility/migration.
|
|
102
|
-
- **Focused goal**: the current pi session has one focused goal id stored in a `pi-goal-focus` custom session entry.
|
|
103
|
-
- **No focus in markdown**: goal files describe the goal itself; they do not record which session is focused on them.
|
|
104
|
-
- **Branch-local focus**: because focus is reconstructed from the current session branch, `/tree` navigation can restore a different focus for a different branch.
|
|
105
|
-
- **One continuation chain**: auto-continue only schedules work for the focused goal in the current session.
|
|
106
|
-
|
|
107
|
-
Creating a goal with `/goals`, `/sisyphus`, `/goals-set`, or `/sisyphus-set` no longer clears other open goals in the same session. It creates a new session-scoped active goal file and focuses it. Use `/goal-list` to inspect this session's open goals and `/goal-focus` to switch the session focus. If the latest focus entry explicitly clears focus, or points at a missing/stale goal, a remaining single open goal is not auto-focused; single-open auto-focus only happens when no focus entry exists at all. If multiple open goals exist and the session has no valid focus, `/goal-resume`, `/goal-clear`, `/goal-abort`, `/goal-pause`, and `/goal-tweak` ask the user to choose a goal instead of acting on all of them.
|
|
108
|
-
|
|
109
|
-
## Agent tools
|
|
110
|
-
|
|
111
|
-
The extension exposes tools only when they make sense for the current lifecycle phase.
|
|
28
|
+
Goal state lives only in Pi session custom entries. It is replayed on session start, tree navigation, and compaction. Pi core owns provider retry and compaction recovery. The completion auditor receives an OS-sandboxed read-only shell when Bubblewrap is available; on platforms without that boundary, it receives only Pi's read/grep/find/ls tools.
|
|
112
29
|
|
|
113
|
-
|
|
114
|
-
|---|---|---|
|
|
115
|
-
| `goal_question` | drafting / tweak drafting | Ask one focused user question |
|
|
116
|
-
| `goal_questionnaire` | drafting / tweak drafting | Ask multiple structured questions |
|
|
117
|
-
| `get_goal` | always | Read the focused goal state; mentions other open goals when present |
|
|
118
|
-
| `propose_goal_draft` | drafting only (goal creation) | Submit a concrete draft for user confirmation |
|
|
119
|
-
| `propose_goal_tweak` | tweak drafting only | Submit a revision to an existing goal (shows Confirm / Continue Chatting dialog) |
|
|
120
|
-
| `complete_goal` | focused active or paused goal | Mark the focused goal complete — supply a `verificationSummary` covering all contract items. When the auditor is disabled, supply `confirmBypassAuditor: true` after user confirmation to bypass the audit |
|
|
121
|
-
| `pause_goal` | focused active goal | Pause the focused goal because of a real blocker |
|
|
122
|
-
| `abort_goal` | focused active or paused goal | Abort/archive an obsolete, impossible, unsafe, or user-cancelled focused goal |
|
|
123
|
-
| `propose_task_list` | active or paused goal | Propose a structured task list for user confirmation (stops the turn) |
|
|
124
|
-
| `complete_task` | active or paused goal | Mark a task complete with optional `verificationSummary`. If the task has a `verificationContract`, the summary is required (does not stop turn) |
|
|
125
|
-
| `skip_task` | active or paused goal | Mark a task skipped with a required reason (does not stop turn) |
|
|
126
|
-
| `propose_goal_tweak` | tweak drafting only | Submit a revision to the focused goal (shows Confirm / Continue Chatting dialog) |
|
|
127
|
-
| `step_complete` | hidden / legacy | Compatibility no-op; Sisyphus no longer requires a step counter |
|
|
128
|
-
| `create_goal` | hidden | Direct calls are rejected; normal creation goes through `propose_goal_draft` |
|
|
30
|
+
## Todo
|
|
129
31
|
|
|
130
|
-
|
|
32
|
+
The single tool replaces the complete retained plan:
|
|
131
33
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
## Completion behavior
|
|
143
|
-
|
|
144
|
-
Completion is also explicit and is checked by an independent pi auditor agent. The executor calls `complete_goal` with its completion claim:
|
|
145
|
-
|
|
146
|
-
```json
|
|
147
|
-
{
|
|
148
|
-
"status": "complete",
|
|
149
|
-
"completionSummary": "What was completed and what evidence proves it."
|
|
150
|
-
}
|
|
34
|
+
```ts
|
|
35
|
+
todo({
|
|
36
|
+
baseRevision: 3,
|
|
37
|
+
tasks: [
|
|
38
|
+
{ key: "implement", subject: "Implement the bridge", status: "in_progress" },
|
|
39
|
+
{ key: "verify", subject: "Verify it", status: "pending", dependsOn: ["implement"] }
|
|
40
|
+
],
|
|
41
|
+
remove: []
|
|
42
|
+
})
|
|
151
43
|
```
|
|
152
44
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
- `<approved/>` archives the goal as complete.
|
|
156
|
-
- `<disapproved/>`, no marker, an error, or an abort rejects completion and leaves the goal open.
|
|
157
|
-
|
|
158
|
-
The auditor is semantic, not a paperwork checklist: it should reject scaffold-only, alpha, generated-template, proxy-metric, build-only, or weakly verified completions when the real user outcome is not satisfied.
|
|
159
|
-
|
|
160
|
-
By default the auditor uses the current/default pi model. Configure it via `.pi/pi-goal-x-settings.json`, or interactively with `/goal-settings` (see [Configuration](#configuration)).
|
|
45
|
+
An existing unfinished task cannot disappear unless `remove` names its key and gives a non-empty reason. Completed work may leave the current working plan. Stale revisions, normalized dependency collisions, invalid dependency graphs, and plans above the 16 KiB serialized UTF-8 budget leave state unchanged. Model context renders unfinished work in full, summarizes completed keys, and injects nothing when all work is complete.
|
|
161
46
|
|
|
162
|
-
|
|
47
|
+
Events:
|
|
163
48
|
|
|
164
|
-
- `
|
|
165
|
-
-
|
|
166
|
-
- the auditor's approval report
|
|
167
|
-
- full current goal details, including objective, status, usage, mode, and file path
|
|
168
|
-
|
|
169
|
-
Sisyphus goals use the same completion tool as regular goals. The stricter part is the prompt/criteria standard: the agent should only call completion after the whole ordered objective is actually satisfied and likely to survive independent auditing. A paused goal can also be completed directly when the agent already has enough evidence that every requirement is satisfied; it does not need a resume just to call `complete_goal`.
|
|
170
|
-
|
|
171
|
-
## Schema gates
|
|
172
|
-
|
|
173
|
-
The shipped gates are intentionally small and mechanical.
|
|
174
|
-
|
|
175
|
-
| Gate | Prevents |
|
|
176
|
-
|---|---|
|
|
177
|
-
| Focus consistency | `/goals` accidentally becoming Sisyphus, or `/sisyphus` becoming regular mode |
|
|
178
|
-
| Confirm-before-commit | The agent silently creating or replacing a discussion-based goal |
|
|
179
|
-
| Direct set intent | `/goals-set` and `/sisyphus-set` are explicit user shortcuts that bypass draft confirmation |
|
|
180
|
-
| Completion auditor gate | Archiving completion unless an independent pi auditor agent returns `<approved/>` |
|
|
181
|
-
| Abort gate | Aborting missing, stale, completed, or reasonless goals |
|
|
182
|
-
| Direct-create rejection | Hidden `create_goal` calls creating goals without the confirmation flow |
|
|
183
|
-
| Post-stop block | Continuing to call tools after `pause_goal`, `abort_goal`, `complete_goal`, or `propose_goal_tweak` stops the turn |
|
|
184
|
-
| Empty-turn guard | Pure chat loops that would keep auto-continuing without meaningful goal work |
|
|
185
|
-
| Abort pause | Active goals staying active after user abort / Ctrl-C |
|
|
186
|
-
| Disk reconciliation | External pause/archive/delete/status changes being ignored or overwritten by stale memory |
|
|
187
|
-
| Post-compaction reminder | Losing the active objective after session compaction |
|
|
188
|
-
|
|
189
|
-
## Files
|
|
190
|
-
|
|
191
|
-
```text
|
|
192
|
-
.pi/goals/sessions/<session-id>/active_goal_<timestamp>_<id>.md
|
|
193
|
-
.pi/goals/sessions/<session-id>/archived/goal_<timestamp>_<id>.md
|
|
194
|
-
.pi/goals/sessions/<session-id>/goal_events.jsonl
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
Multiple `active_goal_*.md` files may exist simultaneously within a session directory. This is the session-level open goal pool. The selected/focused goal is intentionally not stored in these files; focus lives in session custom state.
|
|
198
|
-
|
|
199
|
-
Each file contains:
|
|
200
|
-
|
|
201
|
-
1. extension-owned JSON metadata;
|
|
202
|
-
2. a user-editable `# Goal Prompt` section;
|
|
203
|
-
3. progress/status information.
|
|
204
|
-
|
|
205
|
-
Before commands, tools, and lifecycle hooks act on a focused goal, the runtime reconciles the focused record against the active goal file on disk. External archive/delete/status changes therefore win over stale in-memory state and cannot resurrect deleted active files. Prompt-body edits are still picked up from the `# Goal Prompt` section; focus is never stored in goal markdown.
|
|
206
|
-
|
|
207
|
-
Goal paths are constrained to `.pi/goals/sessions/<session-id>/` and its `archived/` child for current writes. Legacy `.pi/goals/` and `.pi/goals/archived/` paths remain readable for migration. Absolute paths, traversal, NUL bytes, symlinks, and unsafe metadata paths are rejected.
|
|
208
|
-
|
|
209
|
-
## Configuration
|
|
210
|
-
|
|
211
|
-
All settings live in a single file: **`.pi/pi-goal-x-settings.json`**
|
|
212
|
-
|
|
213
|
-
Configured interactively via `/goal-settings`, or edited directly:
|
|
214
|
-
|
|
215
|
-
```json
|
|
216
|
-
{
|
|
217
|
-
"disableTasks": false,
|
|
218
|
-
"disableContracts": false,
|
|
219
|
-
"subtaskDepth": 1,
|
|
220
|
-
"provider": "fireworks",
|
|
221
|
-
"model": "accounts/fireworks/models/deepseek-v4-flash",
|
|
222
|
-
"thinkingLevel": "high",
|
|
223
|
-
"disabled": false
|
|
224
|
-
}
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
| Field | Default | Purpose |
|
|
228
|
-
|---|---:|---|
|
|
229
|
-
| `disableTasks` | `false` | Suppress task list features entirely when `true` |
|
|
230
|
-
| `disableContracts` | `false` | Suppress verification contract enforcement when `true` |
|
|
231
|
-
| `subtaskDepth` | `1` | Maximum nesting depth for subtasks |
|
|
232
|
-
| `provider` | system default | Provider name for the auditor agent |
|
|
233
|
-
| `model` | system default | Model name for the auditor agent |
|
|
234
|
-
| `thinkingLevel` | system default | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
|
|
235
|
-
| `disabled` | `false` | When `true`, skip the completion audit entirely |
|
|
236
|
-
|
|
237
|
-
**Env var overrides:**
|
|
238
|
-
- `PI_GOAL_DISABLE_TASKS=1` — disable task features (takes precedence over file)
|
|
239
|
-
- `PI_GOAL_DISABLE_CONTRACTS=1` — disable contract enforcement (takes precedence over file)
|
|
240
|
-
- `PI_GOAL_SETTINGS_FILE=custom-path.json` — alternative settings file path (relative to cwd or absolute)
|
|
241
|
-
|
|
242
|
-
## Environment variables
|
|
243
|
-
|
|
244
|
-
| Variable | Default | Purpose |
|
|
245
|
-
|---|---:|---|
|
|
246
|
-
| `PI_GOAL_AUTO_CONFIRM` | unset | When `1`, auto-confirms drafts in headless/test contexts |
|
|
247
|
-
| `PI_GOAL_DISABLE_TASKS` | — | When `1`, disable task features (overrides settings file) |
|
|
248
|
-
| `PI_GOAL_DISABLE_CONTRACTS` | — | When `1`, disable contract enforcement (overrides settings file) |
|
|
249
|
-
| `PI_GOAL_SETTINGS_FILE` | `.pi/pi-goal-x-settings.json` | Alternative settings file path (relative to cwd or absolute) |
|
|
49
|
+
- `pi-todo:state` — complete `TodoState` snapshot
|
|
50
|
+
- `pi-todo:request-state` — asks the producer to replay current state
|
|
250
51
|
|
|
251
52
|
## Development
|
|
252
53
|
|
|
253
54
|
```bash
|
|
254
|
-
npm install
|
|
255
55
|
npm test
|
|
256
56
|
npm run check
|
|
57
|
+
npm run build
|
|
257
58
|
npm pack --dry-run
|
|
59
|
+
(cd packages/todo && npm pack --dry-run)
|
|
60
|
+
PI_ACCEPTANCE_BIN="$(command -v pi)" npm run test:installed
|
|
258
61
|
```
|
|
259
62
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
The experiment harness under `experiments/` runs full pi sessions against real model calls and mechanical rubrics.
|
|
263
|
-
|
|
264
|
-
```bash
|
|
265
|
-
cd experiments
|
|
266
|
-
bash harness/run.sh C1-vague-goal-set --count 3 --grade --no-smoke
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
## Package contents
|
|
270
|
-
|
|
271
|
-
The npm package ships only the runtime extension, docs, and package metadata. The extension is split into small modules:
|
|
272
|
-
|
|
273
|
-
```text
|
|
274
|
-
extensions/goal.ts orchestration, commands, tools, events, timers
|
|
275
|
-
extensions/goal-record.ts goal record types, normalization, creation helpers
|
|
276
|
-
extensions/goal-pool.ts open-goal pool, focus resolution, list/selector text helpers
|
|
277
|
-
extensions/goal-core.ts display helpers
|
|
278
|
-
extensions/goal-draft.ts lightweight confirmation prompt, proposal validation, drafting tool gate
|
|
279
|
-
extensions/goal-policy.ts lifecycle, pause/resume/complete, and Sisyphus policy
|
|
280
|
-
extensions/goal-auditor.ts independent pi auditor agent for completion approval, config, and progress tracking
|
|
281
|
-
extensions/goal-ledger.ts event append, read, validation, sanitization, and reconstruction
|
|
282
|
-
extensions/goal-questionnaire.ts built-in question UI and question tool registration
|
|
283
|
-
extensions/goal-tool-names.ts centralized published tool names and allowlists
|
|
284
|
-
extensions/prompts/goal-prompts.ts active, continuation, tweak, and stale prompts
|
|
285
|
-
extensions/storage/goal-files.ts goal file paths, serialization, parsing, archive IO
|
|
286
|
-
extensions/widgets/goal-widget.ts above-editor goal beacon component
|
|
287
|
-
extensions/widgets/goal-notifications.ts widget-style notification text
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
## Design principles
|
|
291
|
-
|
|
292
|
-
- **User owns intent**: only the user starts, replaces, resumes, clears, or confirms goals; the agent may only pause, complete, or abort through schema-gated lifecycle tools with evidence/reason.
|
|
293
|
-
- **One commit path**: normal goal creation goes through drafting and confirmation.
|
|
294
|
-
- **Schema beats prompt walls**: recurring failure modes are handled by validators and tool-call interceptors.
|
|
295
|
-
- **Visible contracts**: confirmed goals and completion reports are printed fully into the conversation.
|
|
296
|
-
- **Lifecycle-shaped tool surface**: the agent sees only tools appropriate to the current phase.
|
|
297
|
-
- **Disk-backed continuity**: goal state survives context churn and can be audited from `.pi/goals/sessions/<session-id>/`.
|
|
298
|
-
- **Human-owned focus**: the agent may work on the focused goal, but only user commands/UI selection switch focus.
|
|
299
|
-
|
|
300
|
-
## Upstream
|
|
301
|
-
|
|
302
|
-
This repository is a downstream fork of [@capyup/pi-goal](https://github.com/capyup/pi-goal). To sync with upstream changes:
|
|
303
|
-
|
|
304
|
-
```bash
|
|
305
|
-
git fetch upstream
|
|
306
|
-
git merge upstream/main
|
|
307
|
-
# resolve conflicts, test, commit
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
The `upstream` remote should point to `https://github.com/capyup/pi-goal.git`.
|
|
311
|
-
|
|
312
|
-
## Release policy
|
|
313
|
-
|
|
314
|
-
This repository can be validated locally with tests and packaging checks. Publishing a new npm version, pushing tags, and running `pi update` are explicit release steps and are not part of ordinary implementation goals unless requested.
|
|
315
|
-
|
|
316
|
-
## License
|
|
317
|
-
|
|
318
|
-
MIT
|
|
63
|
+
Installed-package acceptance builds and packs both tarballs, installs each alone under a temporary `PI_CODING_AGENT_DIR`, verifies real Pi package discovery/replay and deterministic lifecycle behavior, then removes the temporary profiles. It never touches the normal Personal Pi profile.
|
package/dist/goal-auditor.d.ts
CHANGED
|
@@ -1,72 +1,18 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import type {
|
|
3
|
-
import { createAgentSession, type ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
4
|
-
import type { GoalRecord } from "./goal-record.ts";
|
|
5
|
-
import { type GoalSettings } from "./goal-settings.ts";
|
|
6
|
-
export interface AuditorProgress {
|
|
7
|
-
/** Current tool being executed by the auditor, if any */
|
|
8
|
-
currentTool?: string;
|
|
9
|
-
/** Arguments passed to the current tool (truncated for display) */
|
|
10
|
-
currentToolArgs?: string;
|
|
11
|
-
/** When the current tool started (ms since epoch) */
|
|
12
|
-
currentToolStartedAt?: number;
|
|
13
|
-
/** Recent text output lines from the auditor's assistant messages */
|
|
14
|
-
recentOutput: string[];
|
|
15
|
-
/** Phase of the audit */
|
|
16
|
-
phase: "running" | "tool_executing" | "producing_report" | "thinking" | "done";
|
|
17
|
-
/** Elapsed ms since audit started */
|
|
18
|
-
elapsedMs: number;
|
|
19
|
-
/** Current step label shown to the user (e.g. "Inspecting files...") */
|
|
20
|
-
label?: string;
|
|
21
|
-
/** Completion percentage from 0 to 100 */
|
|
22
|
-
percentage?: number;
|
|
23
|
-
}
|
|
24
|
-
export type AuditorProgressCallback = (progress: AuditorProgress) => void;
|
|
1
|
+
import { createAgentSession, createBashTool, type ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import type { Goal } from "./goal-contract.ts";
|
|
25
3
|
export interface GoalAuditorResult {
|
|
26
4
|
approved: boolean;
|
|
27
|
-
disapproved: boolean;
|
|
28
5
|
output: string;
|
|
29
6
|
model?: string;
|
|
30
|
-
thinkingLevel?: ThinkingLevel;
|
|
31
7
|
error?: string;
|
|
32
8
|
}
|
|
33
|
-
export declare function parseAuditorDecision(output: string):
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
};
|
|
37
|
-
export interface AuditorVerificationEvidence {
|
|
38
|
-
/** The agent's verification summary describing what was checked. */
|
|
39
|
-
summary: string;
|
|
40
|
-
/** The goal's verification contract (what the agent was required to verify), if any. */
|
|
41
|
-
contract?: string;
|
|
42
|
-
}
|
|
43
|
-
export declare function buildGoalAuditorPrompt(args: {
|
|
44
|
-
goal: GoalRecord;
|
|
45
|
-
completionSummary?: string | null;
|
|
46
|
-
detailedSummary: string;
|
|
47
|
-
verificationSummary?: string | null;
|
|
48
|
-
settings?: GoalSettings;
|
|
49
|
-
}): string;
|
|
50
|
-
/** Tool name for auditor progress reporting */
|
|
51
|
-
export declare const REPORT_AUDITOR_PROGRESS_TOOL_NAME = "report_auditor_progress";
|
|
52
|
-
/** Parameters for the report_auditor_progress tool */
|
|
53
|
-
export declare const reportAuditorProgressParams: Type.TObject<{
|
|
54
|
-
label: Type.TString;
|
|
55
|
-
percentage: Type.TNumber;
|
|
56
|
-
}>;
|
|
9
|
+
export declare function parseAuditorDecision(output: string): boolean;
|
|
10
|
+
export declare function buildGoalAuditorPrompt(goal: Goal, completionSummary: string, bashAvailable?: boolean): string;
|
|
11
|
+
export declare function createReadOnlyAuditorBash(cwd: string): ReturnType<typeof createBashTool> | null;
|
|
57
12
|
export declare function runGoalCompletionAuditor(args: {
|
|
58
13
|
ctx: ExtensionContext;
|
|
59
|
-
goal:
|
|
60
|
-
completionSummary
|
|
61
|
-
detailedSummary: string;
|
|
62
|
-
verificationSummary?: string | null;
|
|
63
|
-
settings?: GoalSettings;
|
|
14
|
+
goal: Goal;
|
|
15
|
+
completionSummary: string;
|
|
64
16
|
signal?: AbortSignal;
|
|
65
|
-
onProgress?: AuditorProgressCallback;
|
|
66
|
-
/**
|
|
67
|
-
* Optional factory for creating the auditor agent session.
|
|
68
|
-
* Exposed for testing so a mock/controllable session can be injected.
|
|
69
|
-
* Defaults to the real createAgentSession from @earendil-works/pi-coding-agent.
|
|
70
|
-
*/
|
|
71
17
|
createSession?: typeof createAgentSession;
|
|
72
18
|
}): Promise<GoalAuditorResult>;
|