Schedules
PocketPi has two scheduling models because reasoning work and deterministic App work have different owners. Use an Agent wake to ask the resident Agent to think; use an App schedule to run one named Action without a model turn.
Choose by owner
| Agent wake | App schedule | |
|---|---|---|
| Declared by | Agent through schedule.* Tools | App release in app.json |
| Persistent state | Pi Agent schedule store | App-local schedule state |
| Runs | A prompt through the resident Harness | One local Action with fixed args |
| Model required | Yes | No |
| Example | “Every morning, review research and decide what needs attention.” | “Refresh portfolio data every five minutes.” |
Declare an App schedule
"schedules": [
{
"id": "portfolio-refresh",
"everyMinutes": 5,
"action": "refreshPortfolio",
"args": {}
}
]The Action name is local and unqualified. Installation evaluates actions.js and rejects the App if the Action is missing. The runtime clamps intervals to at least 60 seconds.
Headless execution
- The scheduler claims a due App declaration.
- The shared Action runner loads or reuses that App's Action Guest.
- The Action executes with
source: "schedule". - Any successful transaction commits SQLite and increments the App revision.
- The schedule records success only after the Action completes.
- A closed View remains unloaded; it projects current data when opened later.
Admission and busy behavior
v1 executes one ordinary Action at a time. Scheduled Actions share that bounded runner rather than creating background concurrency. Hosts poll schedules only when install/uninstall and other exclusive product work allow admission. This keeps behavior deterministic on constrained hardware.
Update and uninstall behavior
- An App update replaces its schedule declarations with the candidate release after successful activation.
- Existing App schedule state is reconciled to the current declaration.
- Uninstall removes all schedules and cursors owned by that App.
- Removing an App Tool does not affect Pi Agent wake schedules, but a future wake may no longer find that Tool.