@tinoy/pi-pause0.3.0
Park pi's agent loop until a deadline or an explicit resume: /pause, /unpause and a footer row.
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
[!WARNING] Do not install anything here yet.
This is a fast-moving prototype: the interfaces change without notice, and nothing here is stable. Every package in this project is headed for a stable 1.0, but that is still some way off. Install one only if you intend to follow the code and expect breakage.
@tinoy/pi-pause
Park pi's agent loop until a deadline (or an explicit resume): a paused session issues no provider request, and a wake that arrives while the pause is active waits instead of being lost.
pi install npm:@tinoy/pi-pause
What it needs at call time
A writable runtime directory for the state file, and nothing else: no machine feature is probed at load, and every failure is fail-open — an unreadable state file reads as not paused, so a bug here can never strand a session.
Registers
/pause, /unpause
/pause with no argument pauses until an explicit release. A duration follows the command
(/pause 45m): a bare number is minutes, s/m/h name a unit, and suffixed segments
compound (90s, 1h30m). /pause status prints the state file and the remaining time;
/pause off releases, and /pause resume, /pause on, /pause clear, /pause none are
its accepted synonyms. A zero duration clears the pause. /unpause is the release verb
under its own name: pi's built-in /resume belongs to the session switcher, so a release
command cannot live there. /pause <duration> while a pause is active replaces the
deadline in both directions, indefinite included.
Where the pause lives
$XDG_RUNTIME_DIR/pi-pause.json (tmpfs, so a pause never survives a reboot), one record
{ paused, until, since, rev, by } rewritten whole by an atomic temp-file-plus-rename.
PI_PAUSE_STATE overrides the path for a caller that needs a named file. Every process
that loaded this extension reads the same file and watches it, so a flip in one session
reaches the others and a release applies at once.
The pause is enforced at two boundaries, both awaited by the agent loop: turn_start, the
first hook of every turn and every wake source (including a triggerTurn wake such as an
intercom delivery, which bypasses input entirely), and before_provider_request, which
holds a pause set while a turn was already in flight. Nothing is parked mid-batch,
mid-tool-result or mid-stream. A timed pause ends at its deadline with nothing sent to the
session; an indefinite pause is re-evaluated on a ceiling-bounded wait chunk, so it can
only outlive its intent if the state file itself still says paused. PI_PAUSE_CEILING_MS
overrides that ceiling (30 minutes).
A park lives in the process, not in the file: /quit, Ctrl+D, stdin EOF, SIGTERM and
ctx.shutdown() release a parked run in about a second, while Escape and Ctrl+C do not —
the escape hatch for a stuck park is /quit or a signal. The footer carries the pause
(\uf04c fa-pause and the deadline) in every session that loaded this extension, and
/pause status answers in that session alone.
Works better with
| Neighbour | You gain | You lose without it | Install |
|---|---|---|---|
subagents.defaultExtensions |
a child session loads pause and parks on the same state file as its parent, instead of continuing to issue requests while the parent is parked | a child session keeps working through the pause — only an interactive session that discovered this extension is held | not a package |
Caveats
No workspace package is a caveat for this one: nothing in this repository imports or
references the pause extension, and its only package dependency is @tinoy/pi-ext-lib.
Dependencies
pi-supplied imports (@earendil-works/pi-coding-agent) are peer dependencies with a *
range and are never bundled. Plain dependencies: @tinoy/pi-ext-lib.
Licence
MIT — see the repository LICENSE.