Layers and ownership
The architecture is easiest to maintain when product policy stays in editable App/System source and mechanisms that require trust, bounds or hardware authority stay native.
Runtime composition
PocketPi product runtime
├── resident Harness + System App
├── App model, routing, schedules, lifecycle and recovery
├── installable ordinary Apps
├── PocketJS / QuickJS execution and UI
└── native host capabilities
└── target platform: hardware + drivers + OS/RTOS servicesPocketPi is the product-level runtime across these pieces. It is not defined by the lower scheduler/kernel layer; the target host uses that layer to implement storage, networking, clocks, threads, drivers and display/touch.
Layer responsibilities
| Layer | Owns | Does not own |
|---|---|---|
| Agent Harness | model/tool loop, messages, turn state and Tool calling | device credentials, App schema or rendering |
| PocketPi | resident System lifecycle, App catalog/routing, schedules, install/update/uninstall and ownership rules | generic UI layout implementation or domain product logic |
| PocketJS | Guest/module contracts, retained UI, layout, text and DrawList generation | which App is installed, which Tool belongs to it or which App is foreground |
| Ordinary App | domain Tools, Actions, schema, provider mapping, resources and View | global workspace, raw secrets or hardware drivers |
| Native host | hardware, storage enforcement, credentials, TLS/transport, limits and rendering adapter | Robinhood/Exa semantics or View policy |
Mechanism versus policy examples
| Mechanism stays native | Policy stays in source |
|---|---|
| credential storage and header application | which credential id/endpoint an App declares |
| one SQLite owner and read/write enforcement | tables, queries, normalization and retention |
| Tool route lookup and Action deadline | Tool description, JSON Schema and Action behavior |
| touch coordinates and PocketJS DrawList rendering | layout, screens, content and interaction events |
| scheduler clock and durable cursor | which App Action runs and with what args |
Changes and delivery boundary
| Change | Delivery |
|---|---|
| native host, PocketJS platform, AppSupervisor or System Framework | Firmware build and flash |
| Pi Agent Root View or resident Harness bundle | Firmware build and flash today |
| ordinary App manifest, schema, Actions, resources or View | Package and install/update .pocketapp |
| ordinary App Data | Action transaction; no release delivery |
Repository map
apps/ System App and ordinary App source
system/ shared Framework, net SDK and View SDK
crates/pocket-pi-agentos/ AppSupervisor and App contracts
crates/pocket-pi-embedded/ embedded resident Harness bridge
crates/pocket-pi-tools/ native workspace/device/schedule Tools
crates/pocket-pi-protocols/ model/provider codecs
hosts/esp32-sim/ macOS product-contract simulator
firmware/esp32-common/ shared ESP-IDF AgentOS host mechanisms
firmware/esp32-p4/ reference physical host
firmware/esp32-s3/ Waveshare ESP32-S3-Touch-LCD-4.3 host
tools/ build, provision and App ingress CLIsCanonical implementation design: docs/agentos-architecture.md ↗.