@fradser/pi-goal
Thread-scoped goals for Pi with three tools, authorized continuation, and evidence-based completion.
Package details
Install @fradser/pi-goal from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@fradser/pi-goal- Package
@fradser/pi-goal- Version
0.2.0- Published
- Nov 12, 2026
- Downloads
- 245/mo · 245/wk
- Author
- fradser
- License
- MIT
- Types
- extension
- Size
- 378.8 KB
- Dependencies
- 1 dependency · 4 peers
Pi manifest JSON
{
"extensions": [
"./index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@fradser/pi-goal
One thread-scoped objective, authorized continuation, and evidence-based completion.
pi install npm:@fradser/pi-goal
Commands
| Command | Behavior |
|---|---|
/goal <objective> |
Show one [goal] requesting row with the typed words, and ask the model to create or revise one concise, outcome-focused objective. |
/goal |
Show the complete current objective and reason. |
/goal pause |
Stop current Goal work and pending continuation. |
/goal resume |
Authorize continuation, preserving accumulated tokens, elapsed time and run count. |
/goal clear |
End the current Goal without claiming completion. |
An action verb is one only by itself: /goal clear my schedule is a request for the
model, not a command that clears the goal.
A goal belongs to its thread. A fresh thread never adopts another thread's goal. The command queues the user's request; it does not create a second goal or overwrite an existing objective with a raw additive fragment. The accepted model revision commits one concise objective that preserves explicit requirements, without adding unrequested implementation details or inferred scope.
Tools
create_goal({objective})starts one goal. The objective is the goal's only requirement text: there is no second verification field and no completion condition beside it. Another unfinished goal must be revised or explicitly cleared first. A goal has no spending cap and none can be set: it is bounded by its work, not by a ceiling.get_goal({section?, cursor?})reads the goal.summaryand the compatibility aliasobjectivereturn the same view. Long model responses include a content-bound continuation cursor; the initial TUI result displays the full body.update_goal(...)performs exactly one operation: requeststatus: "complete"with an optionalcompletion_summary, reportstatus: "blocked"with a reason, carry out an explicit user pause withstatus: "paused"and a reason, or commit a completeobjectiverevision.
Use ordinary work tools for research. There is no research_goal, saved
next_action, or separate Goal history tool. Old history reads direct the caller
to the thread transcript. Empty updates and mixed operations are rejected, and so
is a call that carries a field this version does not declare: a removed field
cannot be silently dropped from a revision that is applied.
Run-start context
Pi 1.2 before_agent_start contributes Goal capability and current state through structured system prompt sections once per run. Tool rounds do not inject or replay runtime messages. The runtime enforces current state independently; use get_goal for updated details during a run.
Continuation and completion
A normal settled turn does not invoke a checker. The runtime authorizes another
run after any successful turn, within the configured limits and with no queued
user input, and progress means something new: a tool receipt this session has
not already produced resets the window, whatever the tool. Reading, searching,
running gates and delegating work count when they add something new, so a long
investigation or verification stretch is not interrupted; repeating the same call
with the same output, answering without calling a tool, and producing nothing at
all are what fill the window. Three consecutive runs with nothing new stop
automatic continuation and say so; /goal resume starts the window again. A
failed turn stops the goal at once, so an outage is not retried. An aborted run
has no settle boundary in Pi, so the runtime closes it at agent_settled and
keeps its authorization instead of stranding the loop. A quiet turn waiting on a
living delegated child holds the window without spending a chance; the child's
completed result is new work and re-arms a stop the runtime itself wrote. A
user's own turn with new work does the same, so a stalled goal does not need a
manual resume before progress continues. A
requirement revision does not clear that memory, so re-wording the objective
cannot make the same receipt count twice. A user's own turn is always new work,
and /goal <text> is that user's turn even though the command delivers it as a
custom message, so a request keeps the full window for the work that follows.
Goal introspection (create_goal, get_goal, update_goal) and a monitor that
has not reached a terminal status are not work. Unrelated background agents do not
count as Goal progress.
Each automatic continuation carries the objective, its untrusted-data boundary, the work policy and the live no-new-work streak inside the checkpoint message, so a run started from a checkpoint is never an empty instruction even if the goal was created after that run's system prompt was assembled. The checkpoint stays hidden from the transcript.
Generation and dispatch checks authorize each continuation exactly once. User input invalidates a queued continuation. Failed and interrupted runs wait for explicit recovery rather than fabricating a user pause. Restoring a session restores its objective but grants no continuation by itself.
Only an explicit completion request invokes one fresh tool-less check. The check
receives the complete objective plus bounded, attributed
observations from this thread. Executor claims are escaped untrusted data. The
checker cannot inspect files or run tests: the executor must collect concrete
verification first. A final MET accepts completion; NOT MET leaves the goal
unmet. Errors, cancellation and superseded results are distinct and cannot complete
the goal. Three refused completion requests do not pause it.
The same reported blocker must recur on three consecutive model turns with no new work before the goal becomes blocked. Repeated reports in one turn count once; new work, requirement revisions and a session boundary reset the streak.
Usage is a report, not a ceiling. Main-model usage and completion-check usage are
recorded against the goal, and nothing stops because a number got large: with no
spending cap anywhere, the no-new-work window above is what stops a stalled loop,
and maxAutonomousRuns is the only optional ceiling. A record an earlier version wrote
with a tokenBudget is read without it, so a goal that stopped under one continues
as any stopped goal does. A record that carries a verificationContract from an
earlier version is read without it too: the objective is the only requirement the
check judges.
Display
Transcript results use the shared pi-kit [goal] <action or state> band. Command
and automatic results are durable custom session messages, not replaceable info
notifications. Each event has one result. Settled objectives, reasons and reports
wrap in full without ctrl+o expansion. A row's body is the objective and any stop
reason; usage stays on the record and in the run-start counters, so no row repeats
a token count.
/goal <request> keeps its own row: one [goal] requesting line with the typed
words under it. The shared band strips control bytes from those words. The complete
request body stays out of the terminal transcript, so the row that reports what the
goal became never sits under a wall of prompt text. That body still reaches the
model, and it remains in the session record. A session replayed without this
renderer is the one exception: Pi then prints the stored body through its default
custom-message rendering.
The passive footer keeps the Codex-style Pursuing goal · 2h 25m while work is
running or continuation is authorized. Otherwise it reads Goal waiting,
Goal paused or Goal blocked, followed by elapsed time.
A running check temporarily replaces that row with one neutral activity line, without a [goal] prefix.
All TUI cases and trigger conditions.
Storage and settings
Active state is an atomic record under Pi's own agent directory:
~/.pi/agent/goals/<project key>/<id>/record.json. Goal state belongs to the
sessions that share a working directory, and the project key keeps two projects
apart, so a new goal writes nothing into the working tree. A write lock protects
revision checks, requirement changes and continuation claims. Completion and clear
write the terminal complete status and detach the thread: the record is kept, so
what was asked for and how it ended stay readable. No Goal archive is created.
A goal stored by an earlier version in <project>/.pi/goals is still read, locked
and written where it lives, and its legacy prose, research and history files are
left untouched; they do not reactivate finished goals. The normal Pi transcript
retains the result.
Global settings are ~/.pi/agent/goal.json; a project's overrides are
settings.json inside that project's goal directory. An override stored by an
earlier version in <project>/.pi/goals/settings.json is still read. Supported
settings are maxAutonomousRuns, provider
and model. The check defaults to the current session model. A model that only
an extension registers, or a virtual router, is not named to the tool-less child
because it loads no extensions; the configured or session model is used when it
can be resolved, otherwise the child selects one from the models it can see.
PI_GOAL_MODEL, PI_GOAL_PROVIDER and PI_GOAL_MAX_RUNS provide temporary
overrides.
maxAutonomousRuns is a lifetime continuation allowance; unset is unlimited and
0 disables continuation. Resume does not replenish the allowance. Legacy research
and check-bypass settings are ignored; the completion check cannot be bypassed.
Verification
python3 -m pytest packages/goal/tests/ -q
bun x tsc --noEmit -p packages/goal/tsconfig.tests.json
bun run typecheck
bun pm pack --destination /tmp --quiet --cwd packages/goal
uv run --no-project --with pyte python packages/goal/tests/goal_native_completion.py
uv run --no-project --with pyte python packages/goal/tests/goal_native_request_row.py
uv run --no-project --with pyte python packages/goal/tests/goal_native_request_continuation.py
uv run --no-project --with pyte python packages/goal/tests/goal_native_revision.py
sh packages/goal/tests/goal_docker.sh
uv run --python 3.13 --no-project packages/goal/tests/goal_real_model_e2e.py --output /tmp/goal-real-model-hy4
Native acceptance uses a scripted provider inside a real Pi CLI/TUI and decodes
complete terminal frames, including resizing and interactive management. It makes
no remote model calls. Docker acceptance installs the packed Goal and its required
kit and TypeBox dependencies into an isolated Pi environment; test fixtures inject the
scripted provider/checker, without other production extensions or host credentials.
The optional real-model command is separate: it needs MAGPIE_BASE_URL and
MAGPIE_API_KEY, sends requests through a host-only proxy, and exercises one native
hunyuan-eval/hy4-dev Goal session. It proves native integration, not learning benefit.