@tduyng/pi-goal 0.0.2 → 0.0.4

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.
Files changed (2) hide show
  1. package/README.md +43 -71
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,109 +1,81 @@
1
1
  # @tduyng/pi-goal
2
2
 
3
- Keep working toward an explicit objective without typing "continue" after each run. Goals survive reload and tree navigation, track token use, and pause when output repeats or a token budget runs out.
3
+ Long objectives that survive a reload and a tree switch, count what they spend, and stop when the budget runs out.
4
4
 
5
- ## /goal command
5
+ A task with more work than one turn needs an objective written down and a way to continue without typing "continue" every time. A goal is that objective, an optional token budget, and an optional check command.
6
6
 
7
- Set a long-running objective with an optional token budget:
7
+ Nothing until a goal exists. The three tools are deferred, so they are not declared to the model and enter the active set only while a goal is active or a request asks to create one. A session that never touches a goal pays no tokens for this package.
8
8
 
9
- ```
9
+ ## Completion needs a command
10
+
11
+ A goal can carry a check such as `bun test`, and `update_goal` cannot mark the goal complete unless that command exits 0. A model can be wrong about whether the tests pass. A command cannot. When the check fails, the output goes back to the model and the goal stays active.
12
+
13
+ ```text
10
14
  /goal refactor the auth module to use JWT refresh tokens
11
15
  /goal with token budget 50000 migrate the database schema
12
16
  ```
13
17
 
14
- Subcommands: `edit` (opens the objective in an editor), `budget <tokens|off>` (set, raise, or remove the token budget), `check <command|off>` (the command that must exit 0 before the goal can complete), `pause`, `resume`, `clear`. Raising the budget past current spend resumes a budget-limited goal.
15
-
16
- ## Tools
17
-
18
- - `create_goal`: the model creates a goal when the user explicitly asks. Objective max: 4,000 characters. Fails if an unfinished goal exists. A complete goal is replaced. When no token_budget is set, the response includes an advisory that spend is unbounded.
19
- - `get_goal`: returns the current goal's status, token and time usage, remaining budget, and thread ID.
20
- - `update_goal`: mark the goal `complete` or `blocked` after verifying the required conditions. Pass `notes` (max 3,000 characters) to replace the progress notes. `complete` runs the goal's check first and is refused unless it exits 0. The model should not mark a goal complete merely because the budget is nearly exhausted or because it is stopping work.
21
-
22
- Goal tools enter the active set while a goal is active or the user asks to create one. Otherwise their schemas stay out of the model request.
23
-
24
- ## Automatic continuation
25
-
26
- After a successful agent run, the extension queues a continuation prompt so the model keeps working without user input. Standing orders live in the system prompt (byte-stable for prompt cache). Live counters (elapsed time, tokens used) ride in the continuation message at the request tail.
27
-
28
- Only one continuation fires per turn. If the loop extension also queued a prompt, the `hasPendingMessages()` guard ensures exactly one wins.
29
-
30
- ### Runaway detection
31
-
32
- If the same tool-free output repeats 3 times in a row, the extension pauses the goal. Any tool call resets the streak.
33
-
34
- ### Stagnation nudge
35
-
36
- After 5 goal turns with no successful `edit` or `write` tool result, the continuation message carries a line naming the count and asking for the next concrete change, or for the blocked audit when a blocker keeps repeating. User input resets the count. The nudge never pauses the goal.
37
-
38
- ### Auto-continuation
39
-
40
- There is no fixed cap: a goal keeps queueing continuations until it completes, is paused, or hits its token budget. Stop one that is going nowhere with `/goal clear`.
18
+ | Subcommand | Effect |
19
+ | --- | --- |
20
+ | `/goal edit` | Open the objective in an editor |
21
+ | `/goal budget <tokens\|off>` | Set, raise or remove the budget |
22
+ | `/goal check <command\|off>` | The command that must exit 0 before completion |
23
+ | `/goal pause` | Stop queueing continuations |
24
+ | `/goal resume` | Start them again |
25
+ | `/goal clear` | Drop the goal |
41
26
 
42
- ### Token counting
27
+ Raising the budget past current spend resumes a budget-limited goal. Three tools back it: `create_goal`, `get_goal`, `update_goal`. `notes` replaces the progress notes, up to 3,000 characters, and those notes are what a later turn after a compaction starts from.
43
28
 
44
- Only `input` and `output` tokens count toward the goal budget. `cacheRead` and `cacheWrite` are excluded because providers report them as separate fields.
29
+ ## Cache behaviour
45
30
 
46
- ## Completion check and notes
31
+ Standing orders live in the system prompt and never change, so they ride in the cached prefix instead of invalidating it. Live counters, elapsed time and tokens used, travel in the continuation message at the request tail, which is not cached anyway.
47
32
 
48
- `create_goal` with `check`, or `/goal check <command>`, sets a shell command such as `bun test`. `update_goal` with status `complete` runs it first. A failing check keeps the goal active and returns the output to the model. `/goal check off` removes it.
33
+ Pausing is defensive rather than a fixed cap. Runaway detection fires when the same tool-free output repeats three times in a row. A stagnation nudge arrives after five goal turns with no successful `edit` or `write`, names the count, and asks for the next concrete change. Neither stops the work, and the budget is the only hard stop.
49
34
 
50
- The progress notes hold what is done, what failed and what is next. They are sent again in the next continuation after a compaction or a resume. A note written in a turn is already in that turn's context, so it is not repeated.
35
+ Only `input` and `output` tokens count toward the budget. `cacheRead` and `cacheWrite` are excluded, since providers report them as separate fields and counting them would end a goal on a warm prefix.
51
36
 
52
- ## Status bar
37
+ ## Loops
53
38
 
54
- Shows elapsed time, token usage, and budget during active pursuit. Other states display as `Goal paused`, `Goal blocked`, `Goal hit usage limits`, `Goal budget reached`, or `Goal complete`.
39
+ `/loop 5m check for failing CI jobs` refires a prompt on an interval. A loop with no prompt runs a maintenance check after each settle: review recent work and address anything stale, broken or half-finished.
55
40
 
56
- ## /loop command
57
-
58
- Repeat a prompt on a fixed interval (e.g. `5m`, `1h`, `30s`) or after each agent run settles:
59
-
60
- ```
41
+ ```text
61
42
  /loop 5m check for failing CI jobs
62
43
  /loop review recent work and fix unfinished items
63
44
  /loop stop
64
45
  ```
65
46
 
66
- Starting a loop fires the first prompt immediately. `/loop` and `/goal` share the pending-message guard to avoid duplicate continuations. Loop state is session-scoped. The timer dies with the pi process. For durable scheduled runs across restarts, use `pi -p "<prompt>"` from an OS scheduler.
67
-
68
- Interval format: a number followed by a unit. Supported units: `ms`, `s`, `m`, `h`, `d`. Bare numbers without a unit are not supported to avoid silent misinterpretation.
47
+ Starting a loop fires the first prompt immediately. The interval is a number plus `ms`, `s`, `m`, `h` or `d`, and a bare number is refused rather than guessed at. Self-paced mode fires 250ms after `agent_settled`, once pi's own retries and compactions are done.
69
48
 
70
- Self-paced mode fires 250ms after `agent_settled`, once pi's own retries and compactions have finished. The default prompt when none is provided: "Run a maintenance check: review recent work and address anything stale, broken, or left half-finished."
49
+ `/loop` composes with `/goal` instead of reimplementing it: exactly one continuation fires per turn, decided by `hasPendingMessages()`. Loop state is session-scoped and its timer dies with the process. For a run that must survive a restart, use `pi -p` from an OS scheduler.
71
50
 
72
- Subcommands: `stop` (also `cancel`, `clear`, `off`), or bare `/loop` to show status. The status bar shows the pace label (e.g. `Loop every 5m (3)`) and iteration count.
51
+ ## After a crash
73
52
 
74
- ## Design
53
+ State lives in custom session entries, with no external database, so resuming a session restores its goal. An interval loop re-arms and fires at once if its interval passed.
75
54
 
76
- The extension persists state as custom session entries, without an external database. Resuming a saved session restores its goal. Interval loops re-arm on resume, firing immediately if their interval has elapsed. The extension does not create goals automatically from ordinary tasks and does not reimplement timeout or retry logic that pi already handles.
55
+ A goal that was mid-turn when the process died gets one continuation when the session reopens. A turn that ended on a user message, a tool result, or a tool call that never ran counts as cut off.
77
56
 
78
- ### Crash resume
57
+ A turn aborted, or one that ended in an error, does not. An aborted turn was a deliberate stop, and an errored turn is what the goal already pauses on. Only an interactive session resumes, because a headless run has no editor to send a message from.
79
58
 
80
- Reopening a session whose goal was mid-turn when the process died queues one continuation, so
81
- the run picks up instead of waiting for the user to type. A turn that ended on a user message,
82
- a tool result, or a tool call that never ran counts as cut off. A turn the user aborted, or one
83
- that ended in an error, does not: the first was their own stop, and the second is what pi-goal
84
- already pauses on. The resume counts as an automatic continuation, and only an interactive
85
- session resumes, because a headless run has no editor to send a message from. A resume pi
86
- refuses, because it is already replaying the interrupted turn, says nothing: the goal continues
87
- from that turn's own settle.
59
+ A goal that hit its token budget resumes with the budget raised to usage plus 50,000 tokens, and the status bar says so.
88
60
 
89
- ### Blocked and completion audits
61
+ ## Install
90
62
 
91
- The standing orders in the system prompt require the model to verify completion against the actual current state before marking a goal complete. For blocked status, the same blocking condition must repeat for at least 3 consecutive goal turns before the model calls update_goal with status blocked. Resuming a previously blocked goal resets the count.
63
+ ```bash
64
+ pi install npm:@tduyng/pi-goal
65
+ ```
92
66
 
93
- ### Budget resume
67
+ Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-goal`
94
68
 
95
- When resuming a goal that hit its token budget, the extension raises the budget to `tokensUsed + 50,000` so the next turn can proceed. The status bar notes the raised budget.
69
+ No configuration. A check command needs a shell, and nothing else.
96
70
 
97
- ### Prompt matching
71
+ `/create-goal` in `../prompts/create-goal.md` expands a plain task into a strict objective and calls `create_goal`. The objective quality decides whether the loop stops early, so use it for anything long-running.
98
72
 
99
- The `promptRequestsGoal` heuristic requires an action verb (create, set, start, new, add, track, pursue, manage, establish) plus a goal noun, or the phrase "long-running". A bare "goal" does not enable the tools.
73
+ ## Limits
100
74
 
101
- ## Install
75
+ - An objective is capped at 4,000 characters and notes at 3,000. A goal that does not fit in a page is a plan, and a plan belongs in a file.
102
76
 
103
- ```bash
104
- pi install npm:@tduyng/pi-goal
105
- ```
77
+ - The check has a 300 second timeout and returns 1,500 bytes, so it is a gate and not a test report.
106
78
 
107
- Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-goal`
79
+ - The extension never creates a goal from an ordinary task. A request has to name the intent, either an action verb with a goal noun or the phrase "long-running", or `/goal` has to be run deliberately.
108
80
 
109
- No configuration is required.
81
+ - `/goal clear` is the way out of a goal that is going nowhere. Nothing caps continuations, because the goal decides when it is done, and the budget decides when it is not.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@tduyng/pi-goal",
3
- "version": "0.0.2",
4
- "description": "Long-running objectives that survive reload and tree navigation, plus a timed or self-paced loop to drive them.",
3
+ "version": "0.0.4",
4
+ "description": "Long-running objectives that survive reload and tree navigation, plus a timed or self-paced loop. Zero tokens until a goal exists.",
5
5
  "keywords": [
6
6
  "pi",
7
7
  "pi-package",