@narumitw/pi-goal 0.54.3 → 0.54.5
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 +117 -190
- package/dist/chunks/{chunk-QWIUWKRW.js → chunk-VJ5LR26S.js} +57 -77
- package/dist/chunks/chunk-VJ5LR26S.js.map +7 -0
- package/dist/chunks/{chunk-UQRRW4CY.js → chunk-WQIA35U2.js} +6 -5
- package/dist/chunks/chunk-WQIA35U2.js.map +7 -0
- package/dist/chunks/{menu-WEFDREGC.js → menu-JMGWQZIT.js} +7 -22
- package/dist/chunks/menu-JMGWQZIT.js.map +7 -0
- package/dist/chunks/{settings-ui-MVYTTBHW.js → settings-ui-JG3PFRB5.js} +6 -18
- package/dist/chunks/settings-ui-JG3PFRB5.js.map +7 -0
- package/dist/index.ts +111 -126
- package/dist/index.ts.map +2 -2
- package/docs/managing-goals.md +47 -0
- package/docs/settings.md +91 -0
- package/package.json +55 -58
- package/src/accounting.ts +62 -66
- package/src/command-registration.ts +104 -102
- package/src/command.ts +101 -112
- package/src/commands.ts +465 -501
- package/src/errors.ts +127 -122
- package/src/goal-contract.ts +64 -64
- package/src/goal.ts +25 -25
- package/src/lifecycle.ts +615 -628
- package/src/markers.ts +6 -6
- package/src/menu.ts +565 -591
- package/src/persistence.ts +177 -192
- package/src/prompts.ts +53 -67
- package/src/run-protocol.ts +299 -325
- package/src/runtime.ts +1422 -1495
- package/src/safety.ts +51 -51
- package/src/settings-ui.ts +366 -393
- package/src/settings.ts +134 -147
- package/src/tool-policy.ts +6 -6
- package/src/tools.ts +371 -347
- package/src/wait.ts +47 -51
- package/src/workflow-mutex.ts +68 -68
- package/dist/chunks/chunk-QWIUWKRW.js.map +0 -7
- package/dist/chunks/chunk-UQRRW4CY.js.map +0 -7
- package/dist/chunks/menu-WEFDREGC.js.map +0 -7
- package/dist/chunks/settings-ui-MVYTTBHW.js.map +0 -7
package/README.md
CHANGED
|
@@ -2,23 +2,24 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@narumitw/pi-goal) [](https://pi.dev) [](./LICENSE)
|
|
4
4
|
|
|
5
|
-
Give Pi
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
Give Pi one session-scoped objective and let it continue after Pi becomes fully idle.
|
|
6
|
+
Goal mode stops when work completes, pauses, waits for an external event, or reaches a safety limit.
|
|
7
|
+
Explicit completion, blocker, and wait tools give each managed run a clear stopping reason.
|
|
8
8
|
|
|
9
9
|
## ✨ Features
|
|
10
10
|
|
|
11
|
-
- Starts
|
|
11
|
+
- Starts and manages one session goal through `/goal` and its status, pause, resume, edit, and clear routes.
|
|
12
12
|
- Continues exactly once from Pi's settled idle boundary after queued work, retries, and compaction have finished.
|
|
13
13
|
- Waits quietly for a follow-up when transient provider retries are exhausted instead of terminally blocking the Goal.
|
|
14
14
|
- Uses explicit `goal_complete`, `goal_blocked`, and `goal_wait` tools with stale-goal guards and evidence requirements.
|
|
15
|
+
- Renders an accepted `goal_complete` summary as Markdown in the TUI.
|
|
15
16
|
- Tracks active, paused, blocked, usage-limited, budget-limited, waiting, and complete outcomes separately.
|
|
16
17
|
- Pauses after a configurable response limit or repeated no-progress runs and offers a guided review before continuing.
|
|
17
18
|
- Supports optional token budgets that stop Goal-owned work immediately when exhausted.
|
|
18
19
|
- Keeps Goal continuation accounting out of the leading system instructions so post-activation provider request prefixes remain stable.
|
|
19
20
|
- Persists the goal in the current session across reload, resume, compatible forks, and compaction.
|
|
20
21
|
- Rejects stale continuations and tool calls after replacement, pause, completion, limits, or other terminal state changes.
|
|
21
|
-
- Optionally exposes a default-off
|
|
22
|
+
- Optionally exposes a default-off protocol for trusted extensions to start, observe, and cancel one Goal lifecycle.
|
|
22
23
|
|
|
23
24
|
## 📦 Install
|
|
24
25
|
|
|
@@ -41,90 +42,48 @@ npm --workspace @narumitw/pi-goal run build
|
|
|
41
42
|
pi -e ./packages/pi-goal
|
|
42
43
|
```
|
|
43
44
|
|
|
44
|
-
The package declares `dist/index.ts`, so an unbuilt local checkout
|
|
45
|
+
The package declares `dist/index.ts`, so Pi cannot load an unbuilt local checkout.
|
|
46
|
+
Pi extensions run with your user permissions.
|
|
47
|
+
Goal mode can start repeated paid model turns and edit the current workspace, so review its limits and source before installing it.
|
|
45
48
|
|
|
46
49
|
## 🚀 Quick start
|
|
47
50
|
|
|
48
|
-
Run `/goal <objective>` to start
|
|
49
|
-
Use the manager to review
|
|
51
|
+
Run `/goal <objective>` to start Goal mode, or run `/goal` to open the state-aware manager.
|
|
52
|
+
Use the manager to review, pause, resume, edit, or clear the current goal.
|
|
50
53
|
|
|
51
54
|
## ⚙️ Settings
|
|
52
55
|
|
|
53
|
-
Settings
|
|
54
|
-
|
|
56
|
+
Use `/goal` → **Settings…** in TUI mode, or edit `<getAgentDir()>/pi-goal.json` (normally `~/.pi/agent/pi-goal.json`).
|
|
57
|
+
A missing file uses the defaults without creating it:
|
|
55
58
|
|
|
56
59
|
```json
|
|
57
60
|
{
|
|
58
|
-
"rpc": {
|
|
59
|
-
"enabled": false
|
|
60
|
-
},
|
|
61
61
|
"continuationLimits": {
|
|
62
62
|
"automaticTurns": 25,
|
|
63
63
|
"noProgressTurns": 3
|
|
64
|
-
}
|
|
64
|
+
},
|
|
65
|
+
"rpc": { "enabled": false }
|
|
65
66
|
}
|
|
66
67
|
```
|
|
67
68
|
|
|
68
|
-
|
|
69
|
-
The
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
Visible Goal tools do not mean Goal mode is active, and only the latest effective active Goal contract authorizes their use.
|
|
87
|
-
Pi-goal never widens a restrictive active-tool policy; activation rejects when required terminal tools are missing, and an active Goal pauses if they later disappear.
|
|
88
|
-
The retired `toolVisibility` key is ignored and preserved as unknown data when another setting is saved.
|
|
89
|
-
|
|
90
|
-
`experimental.goals` is a removed legacy setting.
|
|
91
|
-
If it remains `true`, pi-goal accepts the settings file, ignores the old queue feature, and shows an affected-user warning that recommends `/goal edit` when an active objective exists or `/goal <objectives>` when no active goal exists.
|
|
92
|
-
Later settings saves preserve unknown legacy fields instead of deleting them.
|
|
93
|
-
|
|
94
|
-
`rpc.enabled` accepts a boolean and defaults to `false`.
|
|
95
|
-
When disabled, a valid managed-run start receives `RPC_DISABLED`; manual and restored Goals remain unchanged.
|
|
96
|
-
A Settings-menu change applies immediately after its atomic save.
|
|
97
|
-
Disabling rejects new starts but lets an already accepted run continue publishing its exact state and accept its exact cancellation until terminal, avoiding stranded work.
|
|
98
|
-
Reload, replacement, and shutdown clear that in-memory ownership.
|
|
99
|
-
|
|
100
|
-
`continuationLimits` controls the runaway guards:
|
|
101
|
-
|
|
102
|
-
- `automaticTurns` accepts a positive safe integer or `null` and defaults to `25`.
|
|
103
|
-
It counts every completed normal `turn_end` owned by automatically started Goal work, including model responses inside tool loops and matching Pi-owned retries.
|
|
104
|
-
The user-triggered kickoff, resume, edit, and ordinary user runs are not charged.
|
|
105
|
-
At the limit, the goal becomes `paused` with cause `continuation_limit`, pending continuation/recovery is cancelled, and the current operation is aborted before a 26th normal response starts.
|
|
106
|
-
Pi may invoke a provider adapter once more with an already-aborted signal to produce its synthetic terminal event; that event is not counted and cannot resume Goal work.
|
|
107
|
-
Set this field explicitly to `null` to opt into Unlimited mode; existing explicit `null` values remain compatible.
|
|
108
|
-
- `noProgressTurns` is a positive safe integer and defaults to `3`.
|
|
109
|
-
At the end of an automatic run, pi-goal compares visible assistant text after Unicode normalization, lowercasing, control-character removal, and whitespace collapse.
|
|
110
|
-
Thinking and tool blocks are excluded; empty and punctuation-only output are equivalent.
|
|
111
|
-
Consecutive empty or identical tool-free outputs increment the repeat count.
|
|
112
|
-
Different non-empty output starts a new run at one, and any attempted tool call resets it.
|
|
113
|
-
Set this field to `null` to disable only this heuristic.
|
|
114
|
-
|
|
115
|
-
Settings are reread at Pi startup, session replacement, and `/reload`; direct external file edits are not watched live, while changes made through the Goal menu apply immediately.
|
|
116
|
-
A missing file remains absent and uses the built-in defaults.
|
|
117
|
-
The first successful settings change creates the file atomically; later saves preserve unknown fields.
|
|
118
|
-
|
|
119
|
-
Omitted fields use the defaults above.
|
|
120
|
-
Invalid or malformed existing settings are never overwritten; they produce a warning and fall back to all defaults.
|
|
121
|
-
In the TUI, Goal Settings becomes a read-only summary that identifies the invalid file and directs the user to fix it and run `/reload`.
|
|
122
|
-
Reload Pi after changing the file.
|
|
123
|
-
|
|
124
|
-
Plan mode or another restrictive policy may hide Goal tools.
|
|
125
|
-
Pi-goal does not fight that policy on restore or on later turns: activation rejects when required terminal tools are unavailable, and an already-active goal pauses without automatic continuation if they disappear.
|
|
126
|
-
A restrictive allowlist created before `goal_wait` existed can still run ordinary Goals with `goal_complete` and `goal_blocked`, but the model cannot enter external waiting until that allowlist also includes `goal_wait`.
|
|
127
|
-
The pause aborts a Goal-owned kickoff, resume, active-edit, or automatic-continuation prompt, but it does not cancel or stale-block an unrelated user or extension turn, including startup follow-ups after a restrictive restore.
|
|
69
|
+
The automatic-work limit counts model responses in Goal-owned automatic work, including tool loops.
|
|
70
|
+
The no-progress guard pauses repeated tool-free output.
|
|
71
|
+
Choose **Unlimited** or **Off** explicitly to disable the corresponding guard; Unlimited requires confirmation and can continue consuming tokens and provider cost.
|
|
72
|
+
Neither these guards nor an optional token budget is a dollar-cost cap.
|
|
73
|
+
|
|
74
|
+
Menu saves apply immediately, run in order, preserve unknown fields, and publish atomically.
|
|
75
|
+
Manual edits apply at session start or `/reload`.
|
|
76
|
+
Invalid settings remain untouched, use defaults, and make the TUI Settings screen read-only until repaired and reloaded.
|
|
77
|
+
|
|
78
|
+
Read the [settings reference](./docs/settings.md) for exact counting rules, accepted values, managed-run RPC behavior, tool-policy restrictions, and legacy-setting recovery.
|
|
79
|
+
|
|
80
|
+
## 🔒 Security and privacy
|
|
81
|
+
|
|
82
|
+
Goal mode can start repeated paid model turns and use active Pi tools, including tools that modify the workspace.
|
|
83
|
+
The default automatic-work limit and optional token budget reduce runaway work but are not dollar-cost caps.
|
|
84
|
+
Setting `rpc.enabled` to `true` lets trusted installed extensions request and cancel managed runs through Pi's shared event bus.
|
|
85
|
+
The protocol does not authenticate or sandbox installed extensions.
|
|
86
|
+
Workflow mutual exclusion is cooperative and does not prevent unrelated processes or extensions from editing the same workspace.
|
|
128
87
|
|
|
129
88
|
## 🤝 Workflow coexistence
|
|
130
89
|
|
|
@@ -133,12 +92,15 @@ On the characterized Pi `0.84.2` runtime, it participates in the anonymous `work
|
|
|
133
92
|
An active Goal holds the group through ordinary work, external waiting, continuation delivery, compaction recovery, and provider retry.
|
|
134
93
|
Paused, blocked, usage-limited, budget-limited, complete, cleared, and legacy-queue-only states do not hold it.
|
|
135
94
|
|
|
136
|
-
Direct starts, menu starts, managed-run starts, stopped resumes, and stopped-goal edits use one final synchronous admission
|
|
95
|
+
Direct starts, menu starts, managed-run starts, stopped resumes, and stopped-goal edits use one final synchronous admission.
|
|
96
|
+
Admission occurs after validation and confirmation but before any tool, Goal-state, persistence, prompt, queue, or status mutation.
|
|
137
97
|
Replacing or editing an already active or waiting Goal retains its current owner.
|
|
138
|
-
If admission is busy, TUI and RPC show an anonymous warning, print and JSON direct routes throw before mutation
|
|
98
|
+
If admission is busy, TUI and RPC show an anonymous warning, while print and JSON direct routes throw before mutation.
|
|
99
|
+
Managed-run RPC emits one terminal `ACTIVATION_FAILED` event without creating a Goal.
|
|
139
100
|
|
|
140
101
|
Restored active Goal state acquires before tool restoration, persistence publication, status, wait timers, retry state, or continuation work.
|
|
141
|
-
If restoration is busy, the Goal moves only to its existing paused safe state
|
|
102
|
+
If restoration is busy, the Goal moves only to its existing paused safe state.
|
|
103
|
+
It does not change active tools or schedule work, and you can resume it after the other workflow ends.
|
|
142
104
|
Restored stopped Goals and inert legacy queues do not acquire or schedule automatic work.
|
|
143
105
|
|
|
144
106
|
An active Goal still pauses if a non-participating restrictive policy later removes its required terminal tools.
|
|
@@ -156,73 +118,43 @@ Guaranteed coexistence with Plan mode requires `@narumitw/pi-plan-mode` `0.52.0`
|
|
|
156
118
|
|
|
157
119
|
## 💬 Commands
|
|
158
120
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
Status, Settings, Help, invalid-settings guidance, Clear, and Close remain shallow, labeled routes.
|
|
178
|
-
Arrow keys navigate, Enter selects or submits, Escape goes Back, and Ctrl+C closes the full flow.
|
|
179
|
-
- In RPC mode, bare `/goal` and `/goal status` report the current summary through an observable notification without opening terminal UI.
|
|
180
|
-
Pi exposes no extension-command output channel in print or JSON mode, so those routes reject with an explicit unsupported-mode error instead of misreporting stderr as status output.
|
|
181
|
-
- Menu-driven Replace and Clear actions preview the exact affected goal and require confirmation.
|
|
182
|
-
Existing direct routes remain immediate for compatibility and automation.
|
|
183
|
-
- `/goal <goal_to_complete>` starts goal mode.
|
|
184
|
-
If another unfinished goal exists, Pi asks for confirmation before replacing it with a new active goal and resetting its usage counters.
|
|
185
|
-
Failed kickoff delivery clears a new goal or restores the exact prior Goal and tool-policy snapshot; a previously active or waiting Goal keeps its existing workflow ownership.
|
|
186
|
-
- `/goal --tokens 100k <goal_to_complete>` starts or replaces goal mode with a token budget.
|
|
187
|
-
`k` and `m` suffixes are accepted, for example `100k` or `1.5m`.
|
|
188
|
-
- `/goal edit <goal_to_complete>` updates the existing goal objective without resetting usage counters.
|
|
189
|
-
A successful active edit rotates the stale-turn guard and starts a fresh safety epoch.
|
|
190
|
-
Paused, blocked, and usage-limited goals stay stopped and retain their safety state until resume.
|
|
191
|
-
A budget-limited goal reactivates only when `edit --tokens` raises its budget above current usage.
|
|
192
|
-
Failed prompt delivery restores the exact previous Goal, guard id, safety counters, cause, tool-policy snapshot, and active ownership when applicable.
|
|
193
|
-
- `/goal pause` stops prompt injection and auto-continuation, aborts the current turn, and keeps the goal for later resume.
|
|
194
|
-
Only active goals can be paused.
|
|
195
|
-
- `/goal resume` resumes a paused, blocked, usage-limited, or budget-limited goal when its token budget allows it, rotates the stale-turn guard id, resets the automatic-response/repeat safety epoch when the queued resume prompt starts, clears a safety-pause cause, and reports the new finite epoch or explicit Unlimited state.
|
|
196
|
-
Objective, cumulative usage, and elapsed time are preserved.
|
|
197
|
-
If prompt delivery fails, the original stopped state, guard id, counters, fingerprint, and cause are restored.
|
|
198
|
-
- `/goal clear` clears the current goal, status, pending continuation, inert legacy queue state, and legacy persisted state for the current working directory without aborting unrelated in-flight work.
|
|
199
|
-
|
|
200
|
-
The experimental ordered-goal queue has been removed.
|
|
201
|
-
Use `/goal edit <objective>` to reprioritize the active objective instead.
|
|
202
|
-
For example, if `task b` is complete and `task c` is in progress, edit the objective to say: `task b is complete; do task a next; after task a, continue task c, then task d; do not redo task b unless verification shows it is incomplete.`
|
|
203
|
-
|
|
204
|
-
Former queue command words such as `add`, `prioritize`, `drop-last`, `skip`, `push`, `unshift`, `pop`, and `shift` are ordinary objective text for unaffected users.
|
|
205
|
-
If a session still has legacy queue settings or persisted queue state, those words show a migration warning instead of replacing the active Goal.
|
|
206
|
-
|
|
207
|
-
Goal objectives are limited to 4,000 characters.
|
|
208
|
-
Put longer instructions in a file and reference the file path from `/goal`.
|
|
121
|
+
| Command | Purpose |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| `/goal` | Manage the current goal in TUI; report its summary in RPC. |
|
|
124
|
+
| `/goal status` | Report the current goal and progress. |
|
|
125
|
+
| `/goal [--tokens <budget>] <objective>` | Start automatic work, confirming replacement of an unfinished goal. |
|
|
126
|
+
| `/goal edit [--tokens <budget>] <objective>` | Update the objective or budget without resetting cumulative usage. |
|
|
127
|
+
| `/goal pause` | Pause an active goal and abort its current turn, preserving progress. |
|
|
128
|
+
| `/goal resume` | Resume an eligible stopped goal or wake an active waiting goal. |
|
|
129
|
+
| `/goal clear` (alias: `stop`) | Immediately clear the goal and pending continuation, not unrelated in-flight work. |
|
|
130
|
+
|
|
131
|
+
All routes support TUI and RPC; bare `/goal` and `status` reject print and JSON modes, while direct mutation routes remain available.
|
|
132
|
+
Objectives are limited to 4,000 characters; reference a file for longer instructions.
|
|
133
|
+
`--tokens` must precede the objective and accepts positive amounts such as `100k` or `1.5m`.
|
|
134
|
+
`status`, `pause`, `resume`, and `clear`/`stop` reject trailing arguments; other text starts an objective.
|
|
135
|
+
|
|
136
|
+
Starting, editing an active goal, or resuming can trigger paid model work; [token budgets](#-token-budgets-and-elapsed-time) are not dollar-cost caps.
|
|
137
|
+
Direct Clear is immediate, while menu Clear requires confirmation.
|
|
138
|
+
See [Managing goals](./docs/managing-goals.md) for safety-epoch resets, failed-delivery recovery, budget-limited edits, and migration from removed queue commands.
|
|
209
139
|
|
|
210
140
|
## 🛠️ Tools
|
|
211
141
|
|
|
212
|
-
- `goal_complete` records completion only for the exact active goal id
|
|
142
|
+
- `goal_complete` records completion only for the exact active goal id, requires an evidence-based summary, and renders an accepted summary as Markdown in the TUI.
|
|
213
143
|
- `goal_blocked` records a true repeated impasse with the exact goal id, reason, evidence, and repeated-turn count.
|
|
214
144
|
- `goal_wait` pauses automatic continuation after the agent arranges an external wake source, with an optional bounded resume deadline.
|
|
215
145
|
|
|
216
146
|
## 🔁 Session and reload behavior
|
|
217
147
|
|
|
218
|
-
Goal state is stored
|
|
148
|
+
Goal state is stored in the current Pi session.
|
|
219
149
|
`/reload` and reopening the same Pi session can restore that session's unfinished goal.
|
|
220
|
-
An active restored goal
|
|
150
|
+
An active restored goal at or above its finite automatic-work limit pauses before another provider request and reports that progress is saved.
|
|
151
|
+
Use `/goal` to review and continue.
|
|
221
152
|
A restored waiting Goal remains quiet, excludes offline and waiting wall time from active elapsed time, and restores only its absolute optional deadline timer.
|
|
222
153
|
An active restored goal pauses when workflow admission is busy or either required terminal tool is missing, without changing the active tool set.
|
|
223
154
|
Active elapsed time is checkpointed before shutdown and restarted after reload only when the Goal is not waiting, so offline and stopped wall-clock time is excluded.
|
|
224
155
|
Automatic-response counts, repeat fingerprints, and safety-pause causes persist across reload and compaction.
|
|
225
|
-
A direct non-`/goal` user
|
|
156
|
+
A direct non-`/goal` user or RPC input resets the safety epoch only while the goal is active and reclassifies the in-flight run as manual.
|
|
157
|
+
Extension input and messages sent while stopped do not reset it.
|
|
226
158
|
Starting a new Pi session in the same working directory does not inherit the old goal.
|
|
227
159
|
|
|
228
160
|
The legacy `{ goal }` shape remains valid, and missing safety fields normalize to zero/defaults.
|
|
@@ -253,10 +185,11 @@ This version no longer reads that global file, and `/goal clear` removes any leg
|
|
|
253
185
|
|
|
254
186
|
## 💰 Token budgets and elapsed time
|
|
255
187
|
|
|
256
|
-
The TUI budget chooser
|
|
257
|
-
|
|
188
|
+
The TUI budget chooser treats a token budget as cumulative Goal usage and keeps the independent automatic-work response limit visible.
|
|
189
|
+
The final model call may exceed the selected token budget, so it is not a dollar-cost cap.
|
|
258
190
|
Choosing a preset or entering a custom value remains provisional until the objective is submitted; cancelling the chooser, custom input, or objective editor creates no Goal.
|
|
259
|
-
**Increase budget and resume…** shows the
|
|
191
|
+
**Increase budget and resume…** shows the current budget and usage and requires a new total above current usage.
|
|
192
|
+
It previews the new total and automatic-work epoch, then resumes only after confirmation.
|
|
260
193
|
If the goal or its usage changes while that dialog is open, no change is applied.
|
|
261
194
|
|
|
262
195
|
For each persisted assistant message, `pi-goal` uses finite, non-negative `usage.totalTokens` when available.
|
|
@@ -265,12 +198,14 @@ It does not add `reasoning` because reasoning is already part of output, or `cac
|
|
|
265
198
|
Goal usage is the current branch's cumulative assistant total minus the baseline captured when the goal started, clamped at zero after branch rewinds.
|
|
266
199
|
|
|
267
200
|
Provider usage becomes authoritative only when an assistant message finishes, so a budget can overshoot by one model call.
|
|
268
|
-
When completed tool activity first exposes exhaustion, the goal transitions once to `budget_limited
|
|
201
|
+
When completed tool activity first exposes exhaustion, the goal transitions once to `budget_limited`.
|
|
202
|
+
It cancels continuation, recovery, waits, and stale Goal-owned work, aborts the current turn, and releases workflow ownership.
|
|
269
203
|
It does not queue a summary or another model turn after budget exhaustion.
|
|
270
204
|
Stale Goal tool calls remain blocked until an unrelated user or extension turn begins or the Goal is explicitly reactivated.
|
|
271
205
|
A budget-limited Goal cannot call `goal_complete`; raise its budget above current usage and resume or edit it first.
|
|
272
206
|
|
|
273
|
-
The default 25-response automatic-work limit is a response-count boundary, not a fixed cost ceiling
|
|
207
|
+
The default 25-response automatic-work limit is a response-count boundary, not a fixed cost ceiling.
|
|
208
|
+
Context size, cache pricing, output length, and provider rates vary, and the final capped response is still retained.
|
|
274
209
|
Pi derives displayed cost estimates from provider-reported token usage and local model pricing; pi-goal does not query a billing balance or enforce a dollar cap.
|
|
275
210
|
For tighter token control, choose a smaller `automaticTurns` value and/or use `/goal --tokens`; choosing Unlimited removes only the response-count boundary.
|
|
276
211
|
|
|
@@ -281,8 +216,10 @@ Legacy session entries are migrated by preserving their accumulated seconds and
|
|
|
281
216
|
## ✅ How completion works
|
|
282
217
|
|
|
283
218
|
While a goal is active, Goal-owned messages carry persistence rules and a `<goal_id>` stale-turn guard, and pi-goal exposes `goal_complete`.
|
|
284
|
-
Kickoff, resume, edited-objective, wait-resume, and automatic-continuation prompts
|
|
285
|
-
They
|
|
219
|
+
Kickoff, resume, edited-objective, wait-resume, and automatic-continuation prompts place a trust boundary before the escaped objective and identify it as user-provided task data.
|
|
220
|
+
They preserve its full scope across turns and require the agent to derive concrete requirements from the objective and referenced artifacts.
|
|
221
|
+
The prompts treat the current worktree, command output, tests, runtime behavior, pull request state, rendered artifacts, and external state as authoritative.
|
|
222
|
+
Previous conversation and plans are context, not proof.
|
|
286
223
|
|
|
287
224
|
Goal helper names, definitions, and active prompt metadata remain stable across Goal activation, continuation, token accounting, wait resume, completion, and clearing.
|
|
288
225
|
Mode-only positive instructions live in the append-only active Goal contract instead of globally active tool prompt metadata.
|
|
@@ -290,12 +227,15 @@ Current token-budget usage is carried by the newly appended Goal prompt instead
|
|
|
290
227
|
The first accepted handoff for each Goal identity persists one deterministic hidden Goal contract at the same agent-start boundary, after previously retained conversation history.
|
|
291
228
|
The contract explicitly supersedes earlier Goal contracts, excludes mutable token, iteration, and elapsed-time counters, and stays at its appended history position.
|
|
292
229
|
Editing, replacing, and stopped-state resume append a new superseding active contract without deleting earlier provider input; failed handoff delivery appends no contract.
|
|
293
|
-
Completion, clearing, and stopped transitions append one inactive superseding contract
|
|
230
|
+
Completion, clearing, and stopped transitions append one inactive superseding contract.
|
|
231
|
+
Compaction and session restore append a missing current-state contract without waking a waiting Goal.
|
|
294
232
|
These structural guarantees make provider prefix reuse possible, but the provider still decides cache eligibility, cache hits, pricing, and billing.
|
|
295
233
|
|
|
296
|
-
Before completion, the shared audit tells the agent to treat completion as unproven
|
|
234
|
+
Before completion, the shared audit tells the agent to treat completion as unproven.
|
|
235
|
+
The agent must inspect evidence for every named artifact, command, test, gate, invariant, and deliverable and match each check to the requirement it supports.
|
|
297
236
|
Weak, indirect, missing, or merely consistent evidence means work must continue.
|
|
298
|
-
This prompt wording is a behavioral guardrail, not proof
|
|
237
|
+
This prompt wording is a behavioral guardrail, not proof.
|
|
238
|
+
Pi-goal can enforce the current goal id and reject empty or plainly contradictory summaries, but it cannot prove that external work is complete.
|
|
299
239
|
|
|
300
240
|
To finish, the agent must call `goal_complete` with the exact current `goal_id` and a `summary` of completion evidence.
|
|
301
241
|
Missing or stale `goal_id` values are rejected before summary validation.
|
|
@@ -303,13 +243,16 @@ Paused, blocked, usage-limited, and budget-limited goals cannot be completed unt
|
|
|
303
243
|
The summary is completion evidence, not the stale-turn safety token.
|
|
304
244
|
|
|
305
245
|
If a turn ends before completion, `pi-goal` records usage and creates one continuation intent unless a circuit breaker pauses it first.
|
|
306
|
-
It dispatches that continuation only from Pi's `agent_settled` lifecycle
|
|
246
|
+
It dispatches that continuation only from Pi's `agent_settled` lifecycle.
|
|
247
|
+
Retries, automatic compaction, steering, and follow-up work must be drained, `ctx.isIdle()` must be true, and no messages may be pending.
|
|
307
248
|
Repeated settled events cannot dispatch the same intent twice.
|
|
308
|
-
Goal-owned kickoff, resume, active-edit, and automatic-continuation deliveries are bound to the goal instance that created them
|
|
249
|
+
Goal-owned kickoff, resume, active-edit, and automatic-continuation deliveries are bound to the goal instance that created them.
|
|
250
|
+
A delayed prompt from a replaced goal is aborted without rolling back, injecting, or stopping the newer goal.
|
|
309
251
|
Plain assistant text never marks a goal complete—even an exact-reply objective pauses safely when the model repeatedly omits `goal_complete`.
|
|
310
252
|
|
|
311
|
-
Manual compaction does not emit `agent_settled`, so its completion hook uses the same single-flight dispatcher
|
|
312
|
-
Pi extensions cannot reserve an idle turn atomically like Codex core
|
|
253
|
+
Manual compaction does not emit `agent_settled`, so its completion hook uses the same single-flight dispatcher only when Pi is idle.
|
|
254
|
+
Pi extensions cannot reserve an idle turn atomically like Codex core.
|
|
255
|
+
Another extension can win the race after the idle check, and its newer turn supersedes the old continuation intent.
|
|
313
256
|
|
|
314
257
|
## ⏳ External waiting
|
|
315
258
|
|
|
@@ -325,11 +268,13 @@ goal_wait({
|
|
|
325
268
|
|
|
326
269
|
`goal_id` must match the current active Goal, `reason` must contain 1–1,000 characters, and the optional `resume_after_ms` must be a whole number from 1 through 2,147,483,647.
|
|
327
270
|
The deadline is a safety wake-up rather than a polling interval.
|
|
328
|
-
Requests below 10,000 milliseconds are accepted for compatibility but clamped to an effective 10,000-millisecond deadline
|
|
271
|
+
Requests below 10,000 milliseconds are accepted for compatibility but clamped to an effective 10,000-millisecond deadline.
|
|
272
|
+
The tool result reports both the requested and effective values.
|
|
329
273
|
Prefer deadlines measured in minutes instead of repeated short wakes.
|
|
330
274
|
Omitting `resume_after_ms` intentionally permits an indefinite quiet wait.
|
|
331
275
|
|
|
332
|
-
An accepted call keeps the canonical Goal status active, checkpoints active elapsed time, cancels pending continuation work
|
|
276
|
+
An accepted call keeps the canonical Goal status active, checkpoints active elapsed time, and cancels pending continuation work.
|
|
277
|
+
It persists the reason and optional absolute deadline and terminates the normal single-tool run.
|
|
333
278
|
Call `goal_wait` alone because Pi only guarantees early termination when every finalized result in a parallel tool batch terminates.
|
|
334
279
|
|
|
335
280
|
When Pi exhausts retries for a transient provider error such as HTTP 429, pi-goal enters the same active waiting state without a deadline instead of marking the Goal blocked.
|
|
@@ -358,7 +303,12 @@ Editing or replacing a waiting Goal clears the previous wait so the updated obje
|
|
|
358
303
|
## 🚧 Blocked goals
|
|
359
304
|
|
|
360
305
|
`goal_blocked` is intentionally narrower than completion or ordinary clarification.
|
|
361
|
-
Every goal-mode prompt
|
|
306
|
+
Every goal-mode prompt requires these fields for the blocked audit:
|
|
307
|
+
|
|
308
|
+
- the exact current `goal_id`;
|
|
309
|
+
- a specific reason, up to 1,000 characters, describing the required user or external action;
|
|
310
|
+
- concrete evidence from failed resolution attempts, up to 4,000 characters;
|
|
311
|
+
- `repeated_turns` showing that the same blocker recurred for at least three consecutive goal turns.
|
|
362
312
|
A resumed goal starts a fresh blocker audit.
|
|
363
313
|
Empty or oversized reasons/evidence, stale ids, non-whole turn counts, stopped goals, and fewer than three turns are rejected.
|
|
364
314
|
Accepted blocker reports set `blocked`, stop automatic continuation, and terminate the tool batch when Pi can do so safely.
|
|
@@ -369,9 +319,11 @@ The user can resolve the external condition and run `/goal resume` to rotate the
|
|
|
369
319
|
## 🛑 Interruption and queued-input behavior
|
|
370
320
|
|
|
371
321
|
A user pause or aborted turn produces `paused`; a terminal provider/account quota error produces `usage_limited`; another non-retryable agent error produces `blocked`.
|
|
372
|
-
Each stopped transition cancels pending continuation intent or delivery
|
|
322
|
+
Each stopped transition cancels pending continuation intent or delivery and aborts stale work when applicable.
|
|
323
|
+
Stale tool calls remain blocked until the next non-goal user prompt, successful reactivation or replacement, or `/goal clear`.
|
|
373
324
|
On `/goal clear`, the extension clears goal state, continuation markers, and any stale tool-call block without aborting an unrelated in-flight turn.
|
|
374
|
-
Retryable provider interruptions and overflow compaction retries stay `active` while Pi retries
|
|
325
|
+
Retryable provider interruptions and overflow compaction retries stay `active` while Pi retries.
|
|
326
|
+
No extra continuation is queued, and automatic ownership remains charged through retry `agent_start` events.
|
|
375
327
|
If matching provider recovery still exists at `agent_settled`, retries are exhausted and the Goal enters a deadline-free active wait before any continuation dispatches.
|
|
376
328
|
A later non-Goal input wakes the same Goal without rotating its stale-turn guard, so the model can continue, complete, or enter another wait with the current `goal_id`.
|
|
377
329
|
If matching compaction recovery still exists at `agent_settled`, the Goal becomes `blocked` because recovery did not produce usable context.
|
|
@@ -382,7 +334,8 @@ User and extension work that starts before settlement supersedes the older conti
|
|
|
382
334
|
|
|
383
335
|
With `rpc.enabled: true`, pi-goal exposes a session-local, dependency-free protocol over Pi's shared `pi.events` bus.
|
|
384
336
|
It is intended for trusted sibling extensions that need to start, observe, and cancel one Goal lifecycle without driving the `/goal` command.
|
|
385
|
-
Installed Pi extensions remain fully privileged
|
|
337
|
+
Installed Pi extensions remain fully privileged.
|
|
338
|
+
This setting controls only whether pi-goal cooperates with these channels; it does not provide authentication or sandboxing.
|
|
386
339
|
|
|
387
340
|
The public channels are:
|
|
388
341
|
|
|
@@ -418,13 +371,14 @@ A successful start produces canonical state on `pi-goal:event:${runId}`:
|
|
|
418
371
|
}
|
|
419
372
|
```
|
|
420
373
|
|
|
421
|
-
|
|
422
|
-
`complete` is
|
|
374
|
+
Later state events use `active`, `complete`, `blocked`, `paused`, `usage_limited`, `budget_limited`, or `cleared`.
|
|
375
|
+
Only `complete` is a successful terminal outcome.
|
|
423
376
|
A matching completion may include `summary`; other terminal outcomes may include `reason`.
|
|
424
377
|
Events come only from canonical Goal persistence and only for the matching managed run.
|
|
425
378
|
Manual and restored Goals are not adopted or broadcast, unchanged persistence does not duplicate a status, and each run emits at most one terminal event.
|
|
426
379
|
|
|
427
|
-
Terminal events are dispatched after the underlying Goal transition settles
|
|
380
|
+
Terminal events are dispatched after the underlying Goal transition settles.
|
|
381
|
+
A listener can start the next managed run directly after `complete` without re-entering completion cleanup.
|
|
428
382
|
Other terminal statuses leave a stopped Goal that must be resolved or cleared first.
|
|
429
383
|
If a manual edit, replacement, or edit transition rotates the Goal id, the prior managed run ends as `cleared` with a superseded reason; the replacement remains outside that run.
|
|
430
384
|
|
|
@@ -477,45 +431,18 @@ No compatibility aliases are registered.
|
|
|
477
431
|
|
|
478
432
|
## 🗂️ Package layout
|
|
479
433
|
|
|
480
|
-
```
|
|
434
|
+
```text
|
|
481
435
|
packages/pi-goal/
|
|
482
|
-
├──
|
|
483
|
-
├──
|
|
484
|
-
│ └──
|
|
485
|
-
├──
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
│ ├── commands.ts # Per-factory user-command controller
|
|
490
|
-
│ ├── tools.ts # Goal completion and blocker tool adapters
|
|
491
|
-
│ ├── lifecycle.ts # Pi session, agent, tool, and compaction event adapter
|
|
492
|
-
│ ├── goal-contract.ts # Deterministic post-compaction model contract
|
|
493
|
-
│ ├── runtime.ts # Per-factory Goal state, transitions, prompts, and budgets
|
|
494
|
-
│ ├── tool-policy.ts # Goal tool names and read-only availability checks
|
|
495
|
-
│ ├── safety.ts # Output normalization and no-progress fingerprint state
|
|
496
|
-
│ ├── wait.ts # External-wait validation and session timer ownership
|
|
497
|
-
│ ├── errors.ts # Pi-aligned provider error and retry classification
|
|
498
|
-
│ ├── markers.ts # Bounded Goal prompt marker parsing and formatting
|
|
499
|
-
│ ├── run-protocol.ts # Default-off managed-run protocol and session ownership
|
|
500
|
-
│ └── *.ts # Package-local parsing, settings, prompts, accounting, and persistence
|
|
501
|
-
├── README.md
|
|
502
|
-
├── LICENSE
|
|
503
|
-
├── tsconfig.json
|
|
504
|
-
└── package.json
|
|
505
|
-
```
|
|
506
|
-
|
|
507
|
-
`index.ts` is the Pi entrypoint and forwards to `goal.ts`; the other source modules are internal.
|
|
508
|
-
The package exposes its Pi extension through `package.json`:
|
|
509
|
-
|
|
510
|
-
```json
|
|
511
|
-
{
|
|
512
|
-
"pi": {
|
|
513
|
-
"extensions": ["./dist/index.ts"]
|
|
514
|
-
}
|
|
515
|
-
}
|
|
436
|
+
├── src/ # State, safety, waiting, settings, and protocol modules
|
|
437
|
+
│ ├── index.ts # Thin Pi entrypoint
|
|
438
|
+
│ └── goal.ts # Goal lifecycle, commands, and tools
|
|
439
|
+
├── dist/ # Generated Jiti runtime
|
|
440
|
+
├── scripts/build-runtime.mjs # Runtime builder
|
|
441
|
+
├── docs/ # Published reference documentation
|
|
442
|
+
└── test/ # Behavior and lifecycle coverage
|
|
516
443
|
```
|
|
517
444
|
|
|
518
|
-
The generated runtime is built from
|
|
445
|
+
The generated runtime is built from `src/index.ts` and does not import back into `src`.
|
|
519
446
|
|
|
520
447
|
## 🔎 Keywords
|
|
521
448
|
|