@tduyng/pi-goal 0.0.3 → 0.0.4

package/README.md

@@ -1,66 +1,42 @@
 # @tduyng/pi-goal
 
-Give the agent an objective once, then stop typing "continue". Goals survive reload and tree navigation, count what they spend, and pause on their own when the work repeats or the budget runs out.
+Long objectives that survive a reload and a tree switch, count what they spend, and stop when the budget runs out.
 
-## What it costs
+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.
 
-Nothing until a goal exists. `create_goal`, `update_goal`, and `get_goal` are deferred tools: they are not declared to the model, and they enter the active set only while a goal is active or you ask to create one. A session that never touches a goal pays no tokens for this package.
+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.
 
-The standing orders live in the system prompt and are byte-stable, so they ride in the prompt cache rather than invalidating it. Live counters such as elapsed time and tokens used travel in the continuation message at the request tail, which is not cached anyway.
+## Completion needs a command
 
-## /goal
+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.
 
 ```text
 /goal refactor the auth module to use JWT refresh tokens
 /goal with token budget 50000 migrate the database schema
 ```
 
-Subcommands:
-
-| Command | Effect |
+| Subcommand | Effect |
 | --- | --- |
 | `/goal edit` | Open the objective in an editor |
-| `/goal budget <tokens\|off>` | Set, raise, or remove the token budget |
-| `/goal check <command\|off>` | The command that must exit 0 before the goal can complete |
+| `/goal budget <tokens\|off>` | Set, raise or remove the budget |
+| `/goal check <command\|off>` | The command that must exit 0 before completion |
 | `/goal pause` | Stop queueing continuations |
 | `/goal resume` | Start them again |
 | `/goal clear` | Drop the goal |
 
-Raising the budget past current spend resumes a budget-limited goal.
-
-## The tools
-
-`create_goal` is for when you explicitly ask for a goal: an objective of up to 4,000 characters, an optional token budget, an optional check. It fails if an unfinished goal exists, replaces a complete one, and adds an advisory when no budget is set, because unbounded spend is worth saying out loud.
-
-`get_goal` returns status, token and time usage, remaining budget, and the thread id.
-
-`update_goal` marks the goal `complete` or `blocked`. `notes` replaces the progress notes, up to 3,000 characters. Completion runs the goal's check first and is refused unless the command exits 0, so the model cannot call a goal done over a red test.
-
-## Continuation
-
-After a successful run the extension queues one continuation prompt, so the model keeps working without input. One continuation fires per turn: if `/loop` also queued a prompt, `hasPendingMessages()` makes exactly one of them win.
-
-Runaway detection pauses a goal when the same tool-free output repeats 3 times in a row. Any tool call resets the streak.
-
-A stagnation nudge arrives after 5 goal turns with no successful `edit` or `write` result. The continuation message names the count and asks for the next concrete change, or for the blocked audit when a blocker keeps repeating. It never pauses the goal. Your own input resets the count.
-
-There is no fixed cap. A goal queues continuations until it completes, is paused, or hits its budget, and `/goal clear` is how you stop one that is going nowhere.
+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.
 
-Only `input` and `output` tokens count toward the budget. `cacheRead` and `cacheWrite` are excluded, because providers report them as separate fields.
+## Cache behaviour
 
-## Completion check and notes
+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.
 
-`create_goal` with `check`, or `/goal check <command>`, sets a command such as `bun test`. The check runs before `update_goal` can complete the goal, and a failing check keeps it active and returns the output to the model.
+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.
 
-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 this turn is already in this turn's context, so it is not repeated.
+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.
 
-## Status bar
+## Loops
 
-Elapsed time, tokens used, and budget while the goal runs. The other states read `Goal paused`, `Goal blocked`, `Goal hit usage limits`, `Goal budget reached`, and `Goal complete`.
-
-## /loop
-
-Repeat a prompt on an interval, or after each run settles:
+`/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.
 
 ```text
 /loop 5m check for failing CI jobs
@@ -68,23 +44,19 @@ Repeat a prompt on an interval, or after each run settles:
 /loop stop
 ```
 
-Starting a loop fires the first prompt immediately. Interval format is a number plus one of `ms`, `s`, `m`, `h`, `d`. 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. With no prompt it runs a maintenance check: review recent work and address anything stale, broken, or half-finished. The status bar shows the pace and the iteration count, for example `Loop every 5m (3)`.
+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.
 
-Loop state is session-scoped and the timer dies with the pi process. For runs that must survive a restart, use `pi -p "<prompt>"` from an OS scheduler.
+`/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.
 
-## Resume and limits
+## After a crash
 
-State is stored as custom session entries, with no external database. Resuming a session restores its goal, and an interval loop re-arms and fires at once if its interval has passed. The extension never creates a goal from an ordinary task.
+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.
 
-A goal that was mid-turn when the process died gets one continuation when you reopen the session, so the run picks up instead of waiting for you. A turn that ended on a user message, a tool result, or a tool call that never ran counts as cut off. A turn you aborted or one that ended in an error does not: the first was your own stop and the second is what the goal already pauses on. Only an interactive session resumes, because a headless run has no editor to send a message from.
+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.
 
-For blocked status the same condition must repeat for at least 3 consecutive goal turns, and resuming a blocked goal resets that count.
+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.
 
-A goal that hit its token budget is resumed with the budget raised to usage plus 50,000 tokens, and the status bar says so.
-
-`promptRequestsGoal` needs 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 switch the tools on.
+A goal that hit its token budget resumes with the budget raised to usage plus 50,000 tokens, and the status bar says so.
 
 ## Install
 
@@ -94,4 +66,16 @@ pi install npm:@tduyng/pi-goal
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-goal`
 
-No configuration required.
+No configuration. A check command needs a shell, and nothing else.
+
+`/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.
+
+## Limits
+
+- 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.
+
+- The check has a 300 second timeout and returns 1,500 bytes, so it is a gate and not a test report.
+
+- 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.
+
+- `/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

@@ -1,6 +1,6 @@
 {
   "name": "@tduyng/pi-goal",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Long-running objectives that survive reload and tree navigation, plus a timed or self-paced loop. Zero tokens until a goal exists.",
   "keywords": [
     "pi",