@subaud-tools/pi-schedule
Scheduled actions for pi agents — prompts, shell checks, notifications, one-shots, and bounded polls
Package details
Install @subaud-tools/pi-schedule from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@subaud-tools/pi-schedule- Package
@subaud-tools/pi-schedule- Version
0.6.1-subaud-tools.3- Published
- Nov 21, 2026
- Downloads
- 959/mo · 239/wk
- Author
- schuettc
- License
- MIT
- Types
- extension, skill
- Size
- 229.3 KB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"skills": [
"./skills"
],
"extensions": [
"./src/extension.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-schedule
Recurring scheduled tasks for pi agents.
Give the agent a way to schedule work like:
- security reviews
- package / artifact version checks
- status polls
- any other recurring prompt-driven task
Published as a pi package (pi install).
Install
pi install npm:pi-schedule
# or local
pi install ./pi-schedule
# or one-shot
pi -e ./src/extension.ts
How it works
| Piece | Behavior |
|---|---|
| Tool | schedule — create / list / cancel / enable / disable / run_now / history / trust |
| Kinds | prompt (default) · shell · notify · message — what fires when due |
| Storage | Hybrid: global ~/.pi-schedule/schedules.json + project .pi/schedule.json |
| Syntax | Intervals (30m, 2h, 1d) and daily wall-clock (09:00) |
| Fire | On session start when due; also while the session stays open (30s ticker) |
| Skip | If pi was launched with an initial prompt (pi "do X"), due jobs are not checked or triggered for that start |
| Trust | Project-scope jobs only auto-fire in trusted projects (schedule action=trust); global scope is unaffected |
| Reliability | Run ledger, single-flight locks, missed-window policy, privilege tiers, fire caps — see docs/RELIABILITY.md |
Storage is daemon-ready: each job tracks nextRunAt / lastRunAt so a future headless runner can share the same files.
Compatibility: works on any pi ≥ 0.74. On pi ≥ 0.84.1, privilege blocks also terminate the scheduled turn early — a read-only/suggest job that attempts a mutating tool ends without a wasted follow-up model call (mixed read+mutate batches still report findings in text). On older pi the extra field is ignored and blocks behave as before.
Agent skill
The package ships a schedule skill (skills/schedule/SKILL.md) that
loads on-demand and teaches the agent how to schedule well: when to use
kind (prompt / shell / notify / message), every vs dailyAt, privilege
tier, shell wakeOn, the missed-window tradeoff, and self-contained prompts.
The tool is self-describing for mechanics; the skill owns the patterns.
Agent tool
schedule
action: create | list | cancel | enable | disable | run_now | history
name?: short label (create)
kind?: prompt | shell | notify | message (default prompt)
prompt?: task / reminder text; shell follow-up instruction
command?: shell only — run via bash -lc
wakeOn?: shell only — always | failure | success | never
successPrompt?: shell only — agent text on exit 0
failurePrompt?: shell only — agent text on non-zero / killed
timeoutMs?: shell only — default 60000, max 600000
once?: one-shot relative delay ("10m" / "30s"), then terminate (xor every/dailyAt)
maxRuns?: max deliveries (ok+error) before auto-disable
every?: "30m" | "2h" | "1d" | "2h at 09:00" (xor dailyAt/once)
dailyAt?: "09:00" (xor every/once)
scope?: "global" | "project" (default: project if .pi exists)
missedWindow?: "catch_up_one" | "skip" (default catch_up_one)
tier?: "read_only" | "suggest" | "mutate" (default read_only; shell→mutate)
id?: job id
limit?: history row count
Job kinds
| kind | What happens | Agent turn? |
|---|---|---|
| prompt (default) | Inject isolated task contract | yes |
| shell | pi.exec("bash", ["-lc", command]); optional wake via wakeOn |
only if wake fires |
| notify | UI/console reminder | no |
| message | Session custom message (display only) | no |
Shell jobs always store tier=mutate (command runs outside the agent tool path). Prefer wakeOn=failure for CI polls so success is silent.
Never embed secrets in command. The command is stored verbatim (it must re-run) and is visible in list; persisted shell output is automatically scrubbed of common credential shapes (Bearer …, api_key=…, ghp_…/sk-…/AKIA… tokens → [REDACTED]) before it lands in schedules.json or the session transcript — but redaction is pattern-based, not a guarantee. Use env vars or a credentials file instead.
Lifecycle: once and maxRuns
once— fire one time after a relative delay (once="10m",once="30s"), then auto-disable. Ideal for reminders and delayed follow-ups.run_nowwon't re-fire a terminated one-shot — recreate it.maxRuns— cap a recurring job to N deliveries (counts ok + error; skips/locks don't count). After the cap, the job auto-disables withterminated: maxRuns. Re-enabling clears the flag and resumes counting.
A terminated job is disabled and excluded from due scans. list shows [off/terminated:once] or […:maxRuns].
Anchored intervals (every … at HH:MM)
Plain every intervals count from creation: a job made at 10:37 with every="2h" fires 12:37, 14:37, … — the phase is whatever the clock said when you created it.
Anchoring fixes the phase to a wall-clock time you choose:
every="2h at 09:00"fires 09:00, 11:00, 13:00, … regardless of when the job was created.- First run: the next anchored tick, even if that is less than one full interval away (created 08:50 → first fire 09:00).
- Why: polls and reviews that should land on round hours (or any fixed grid) no longer drift by an accidental creation-time offset.
Notes:
fromis accepted as a synonym:every="5m from 09:07"ticks 09:07, 09:12, …- Anchored ticks step in fixed milliseconds, like all intervals. On DST days the wall-clock phase can shift by an hour; use
dailyAtwhen you need DST-exact daily times. every="1d at 09:00"is valid but is just a fixed-step daily;dailyAt="09:00"is the better tool for that.
Privilege enforcement (strict read_only)
The privilege fence covers exactly the scheduled turn: it arms when the
fired [scheduled-task] prompt becomes the active user message and stands
down when that agent run settles (or a user message takes over). The calling
interactive turn is never fenced — a mid-turn run_now no longer blocks the
caller's own bash/edit/write.
While a scheduled read_only turn is active, only a known-read allowlist
of tools may run (read, grep, web_search, semantic search, display, and
read-only terminal inspection — terminal_read/terminal_list/
terminal_wait).
Everything else — bash/edit/write, terminal exec/write tools
(terminal_exec, terminal_tools, …), the mcp gateway,
peer messaging, and any unknown tool — fails closed. This closes the gap
where non-core mutating tools (e.g. terminal_exec) bypassed the old core
blocklist. PI_SCHEDULE_PRIVILEGE_MODE=legacy restores the old blocklist
({edit, write, bash} only) if your scheduled tasks need non-core read tools.
suggest blocks exec surfaces (bash, terminal_* including the
terminal_tools loader) and peer messaging but keeps drafting tools open;
mutate blocks nothing.
Run history closes the loop
Each agent-turn fire writes two ledger rows under one runId: delivered
when the prompt is sent, then ok (turn settled) when the fired turn's run
settles. schedule action=history collapses them, so a run's latest state is
always visible — verify a run_now end-to-end by watching the row flip
delivered → ok.
Examples
# Daily STATIC security review at 09:00, project-scoped, read-only.
# (Static = read/search only. A git-driven "recent changes" review would need
# bash, which read_only blocks — use tier="mutate" for that.)
schedule action=create name="security-review"
prompt="Review the code under src/ for security issues (injection, auth bypass, exposed secrets). Summarize findings with file:line. If none, say 'No findings'."
dailyAt="09:00" scope="project" tier="read_only"
# Hourly review on the hour — anchored, not drifting from creation time.
schedule action=create name="hourly-heartbeat" kind="notify"
prompt="Hour checkpoint." every="1h at 00:00"
# Direct shell poll — no agent turn on green; wake only on failure.
schedule action=create name="ci-poll" kind="shell"
command="gh run list --limit 1 --json conclusion -q '.[0].conclusion'"
wakeOn="failure"
failurePrompt="Latest CI run failed. Inspect logs and propose or apply fixes."
every="5m" missedWindow="skip"
# Human reminder (no model tokens).
schedule action=create name="stretch" kind="notify"
prompt="Stand up and stretch." every="1h"
# One-shot reminder in 5 minutes, then done.
schedule action=create name="break" kind="notify"
prompt="Eye break — look 20ft away for 20s." once="5m"
# Bounded CI poll — stop after 10 checks even if still failing.
schedule action=create name="deploy-watch" kind="shell"
command="gh run list --limit 1 --json conclusion -q '.[0].conclusion'"
wakeOn="failure" failurePrompt="Deploy failed — investigate."
every="5m" maxRuns=10 missedWindow="skip"
# Check package versions every day via an agent prompt that must use the shell.
schedule action=create name="pkg-versions"
prompt="Run `npm outdated` for prod dependencies. Report only meaningful updates as current→latest with a one-line rationale. If nothing meaningful, reply 'No findings'."
every="1d" tier="mutate" missedWindow="skip"
# List / history / force / cancel
schedule action=list
schedule action=history id=abc123def456
schedule action=run_now id=abc123def456
schedule action=cancel id=abc123def456
Delivery rules
- Session start (
startup/new/resume): load hybrid store → process due jobs. - CLI initial prompt: only on process
startup, if launched with a user message (pi "check this"), skip due checks./newand/resumestill process due jobs. - Missed window:
catch_up_onefires once when overdue;skiponly fires within grace (max(2×tick, 25% period)), otherwise advances without firing. - In-session ticker: every 30s, if the agent is idle, process newly due jobs (capped).
run_now: attempts force delivery; tool reports actual status (ok/locked/error), never invents success.- Locks + ledger: O_EXCL file lock + idempotency key; forensic trail in
~/.pi-schedule/runs.jsonl.
Origin-first delivery (multi-session projects)
A due job is evaluated inside every live session on the project. Without routing, whichever session's ticker fires first wins the lock and the agent turn lands there — confusing when you have several sessions open on one project and a scheduled prompt barges into unrelated work. The origin-first ladder targets delivery instead:
- Origin session alive — the session that created the job (recorded as
originSessionId) delivers the full agent turn; every other session defers (a complete no-op — no lock, no ledger, no schedule advance). - Origin gone, lone session — the single remaining session delivers the full turn (one session is never the confusing case).
- Origin gone, several sessions open — the job waits: nothing about
it reaches any session and its due run is kept, so it is delivered once
rung 1 or 2 applies (its session resumed, or a lone session left), with
its own
missedWindowdeciding how many runs it owes. One session, elected deterministically (smallest live session id), records the wait once (waitingSince, onewaiting (origin absent)run-log row). Shell jobs still run their command once (under the lock) in that session, silently; a turn their result asks for is held (pendingWake) and delivered by the first session that may deliver the job.schedule action=listshows the waiting line.
Liveness comes from per-session heartbeat files under
~/.pi-schedule/presence/ (fresh within 3 ticks and pid-alive), refreshed
every tick and removed on shutdown. run_now is an explicit act in the
current session and always delivers a full turn there, ignoring the ladder;
on a job whose session is gone it also takes the job over (the current
session becomes its origin and its wait ends, delivering any held turn).
Jobs created before this feature (no originSessionId) are treated as
origin-absent, so they immediately stop hijacking arbitrary sessions.
On a pi build that does not expose a session id, delivery degrades to the
previous single-flight behavior.
Fired jobs use an isolated prompt contract:
[scheduled-task]
runId: …
jobId: …
…
## Task
…
## Contract
- isolated run; do not invent findings; say "No findings" if empty
- PRIVILEGE: read_only | suggest | mutate
File layout
~/.pi-schedule/
schedules.json
runs.jsonl
trusted.json
locks/
presence/ # per-session heartbeats (origin-first delivery)
<project>/.pi/schedule.json
Project trust
A .pi/schedule.json that arrives with a cloned repository can carry
kind: "shell" or tier: "mutate" jobs — left ungated that is arbitrary
code execution the moment pi opens in the repo. So project-scope jobs only
auto-fire when the project root is trusted (~/.pi-schedule/trusted.json):
- Opening pi in an untrusted project holds due project jobs back (they stay due, untouched) and notifies you once per session start.
- Trust a project explicitly with
schedule action=trust(after inspecting its.pi/schedule.json), or implicitly by creating a project-scope job there in an interactive turn. run_nowalways bypasses the gate — it is an explicit action carrying the privilege of its calling context.- Global-scope jobs are unaffected.
Reliability
Deep dive: docs/RELIABILITY.md.
Summary of MVP mitigations:
- External clock (
nextRunAt), not LLM timing - Missed-window policy + fire caps
- Single-flight locks + idempotency keys
- Append-only run ledger (
history) - Privilege tiers in the fire prompt
- Create rate limit + max jobs per scope
MVP scope
- tool + skill (a
scheduleskill ships inskills/, teaching kind/tier/scope/missed-window choices and self-contained prompt writing); no dedicated/scheduleslash command yet - action kinds: prompt / shell / notify / message (shell via
bash -lc, optionalwakeOn) - lifecycle:
onceone-shots +maxRunsbounded polling - no cron expressions yet
- no background OS daemon (in-session only; storage is ready)
delivered= action executed (prompt injected / shell finished / notify shown), not “agent finished correctly”
Dev
npm install
npm test
npm run typecheck
Publishing
Releases are CI-driven: push a v*.*.* tag and GitHub Actions publishes to
npm with provenance. One-time setup (npm token + NPM_TOKEN secret) and the
per-release flow are documented in docs/PUBLISHING.md.
npm version patch -m "release: %s" # bumps package.json + tags
git push origin master --follow-tags # triggers release.yml
License
MIT