Runtime flow

This page follows observable product events through their owners. Use it when you need to answer “what runs next?” without collapsing Agent reasoning, App behavior, JavaScript execution, native transport and rendering into one box.

Boot

1. The host mounts storage and loads native model, transport, credential and hardware adapters.
2. InstalledAppIndex seeds the firmware-embedded Pi Agent System release.
3. Any approved interrupted ordinary App update is recovered before the App index is loaded.
4. Installed ordinary source releases are read from apps/<id>/release.
5. AppSupervisor creates the resident System Guest and loads its Root View plus Agent loop.
6. Native Tools and installed App Tool definitions become one routed Tool catalog.
7. The host begins normal frame, model-event, install and schedule polling.

boot
  → storage + native adapters
  → recover approved update
  → load System App + installed ordinary Apps
  → create resident Agent Guest
  → merge native Tools + App Tools
  → STARTING → IDLE

Person prompt → Agent Tool → App Action

1. The Root View emits the narrow agent.submit command.
2. The host passes the prompt to the resident Harness; model work occurs off the UI frame.
3. The Harness selects a public Tool from the merged catalog.
4. RoutedToolHost keeps native Tools native and routes App Tools by installed Tool name.
5. The request enters the single ordinary Action queue with one absolute 80-second deadline.
6. An Action Guest is loaded/reused, receives source: "tool", and runs the named function.
7. The completed JSON-serializable result returns through the pending Agent Tool call.
8. The resident Harness continues its model turn and streams text events back to the Root View.

UI event → same App Action

pointer down / tap
  → PocketJS hit test
  → onPress returns PocketPi.action(name, args)
  → host queues the named Action
  → Action Guest executes with source: "ui"
  → result is logged/handled by host
  → committed Data invalidates the View

The View does not call the Action function in its own Guest. This preserves one mutation path and keeps provider/SQLite work away from touch and frame callbacks.

App schedule → headless Action

native clock reaches due declaration
  → App schedule store claims it
  → same Action queue
  → Action Guest executes with source: "schedule"
  → success recorded only after completion
  → View may remain closed

A deterministic App schedule does not wake the model. An Agent wake schedule instead injects a prompt into the resident Harness when the Agent is idle.

Transaction → revision → View

Action Guest
  PocketPi.data.transaction()
      BEGIN IMMEDIATE
      SQL writes
      COMMIT
      app.commit()
          ↓
  atomic App revision increments
          ↓
foreground frame compares in-memory revision
          ↓ stale only
  Projection queries through read-only View mount
          ↓
  View.state updates → PocketJS reconcile → DrawList → host display

Multiple commits before the next frame coalesce into one refresh. A background View performs no query; it catches up when foregrounded. Revision contains no data; it only says the durable source of truth may have changed.

Responsiveness boundary

Model requests, native Tools, HTTP/MCP and ordinary Actions must not block a host frame or touch callback. The host advances the resident Agent every frame even while another App owns the visible View. This lets a person navigate while an Agent turn or App service call is in flight.

Foreground is a display/input selection, not an Agent lifecycle switch. Opening an App does not recreate Pi Agent or move the model loop into that App.