Pi Agent and /workspace
Pi Agent is the privileged resident System App. Its Agent loop, Tool registry and Root View share one long-lived Guest, and it alone owns the top-level /workspace.
Resident means one lifecycle
Firmware embeds the Pi Agent release so a blank device can boot. The System Guest is created once and remains outside the ordinary View/Action LRU caches. Opening an ordinary App changes only the foreground View. It does not reset the conversation, drop an active model request or rebuild the Tool registry.
Workspace is Agent-owned durable state
On ESP32-P4 and ESP32-S3, /workspace lives in LittleFS. In the simulator it maps to the directory supplied by --workspace. Agent files survive Guest activity and device restart. This is separate from every ordinary App's private data root.
/workspace/
├── memory.md Agent-managed files
├── notes.txt
├── .system/ runtime-owned state
│ └── app-events/<id>.json recent install/update outcomes
├── system/app/ firmware-seeded Pi Agent release
└── apps/<id>/
├── release/ installed App source
├── checkout/ Agent-editable candidate, when present
├── data/ App-owned SQLite/files
└── tmp/ disposable App filesThe Agent uses bounded file Tools; it does not receive raw access to another App's SQLite, native credential store or arbitrary host filesystem.
Core native Tools
| Area | Tools | Purpose |
|---|---|---|
| Workspace | read, write, edit, find, grep, ls | Durable Agent-managed files |
| Device | device.status, time.now | Bounded runtime facts |
| Context | workspace.context | Assemble durable workspace memory |
| Agent wakes | schedule.set, schedule.list, schedule.cancel, schedule.clear | Prompt the Agent now or later |
| Utility | bash | Allowlisted workspace/device commands |
Embedded bash is a command dispatcher, not POSIX. There are no processes, pipes, package manager or unrestricted host shell. Its name preserves the familiar Agent Tool shape; its implementation remains bounded for the device.
Agent wake versus App schedule
| Agent wake | App schedule | |
|---|---|---|
| Owner | Pi Agent workspace | Ordinary App manifest/runtime |
| Runs | A new prompt through the Agent loop | One named deterministic Action |
| Best for | Reasoning, follow-up and cross-App coordination | Refresh, cleanup and synchronization |
| Needs model | Yes | No |
What survives reboot today
- Agent workspace files and Agent wake schedule state survive.
- Installed Apps, App SQLite/files and App schedule cursors survive.
- Wi-Fi and model credentials survive in native stores on hardware.
- The in-heap conversation does not survive; session persistence is not implemented.