Introducing a new way to review your PRs.

Read the announcement

earendil-works / pi

AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI

View on GitHub

13 documents · Updated Nov 19, 2026

docs / p2-app

p2 app

Overview

Path-routing coverage note: this doc owns apps/p2/**. Changes under that glob route here, including the server and TUI hosts in apps/p2/src/hosts/, the browser and runtime support in apps/p2/src/, built-in and agent-written plugin surfaces in apps/p2/plugins/, public install/offline assets in apps/p2/public/, operational scripts in apps/p2/scripts/, tests in apps/p2/test/, app docs and design notes in apps/p2/docs/, vendored licenses in apps/p2/third-party/, and the Python speech service in apps/p2/voice-server/.

apps/p2 is a private, experimental self-hosted Pi Durable application. The package is an ESM Node app (apps/…/package.json) whose main commands run through node --import ./src/source.ts; apps/…/source.ts installs p2's dev module tracking and workspace source resolver before the server, TUI, scripts, or tests import app code. Runtime source aliases in apps/…/tsconfig.json point p2 at local monorepo package sources such as Chord, pi-ai, pi-durable, pi-env, pi-tui, and the public plugin API aliases @p2/app/v1*.

The server host starts in apps/…/server.ts. It chooses <P2_DATA_DIR> (default ~/.pi/p2), makes it private, creates <data>/plugins, enforces a single server per data directory with a process lock, refuses old data layouts through apps/…/host-dirs.ts, opens the server Chord store at <data>/server/store.sqlite, and optionally opens <data>/telemetry.sqlite when settings.json has telemetry: true. It then creates the server Chord host, loads built-in plugins from apps/p2/plugins/ plus user plugins from <data>/plugins, builds the browser web surface, creates the SessionWorkers manager, installs HTTP routes and WebSocket upgrade handling, and exposes plugin registries such as Routes, Upgrades, Authenticators, RequestResolvers, WorkerInitValues, and PageCookies from apps/…/server.ts. The host listens only on loopback; apps/…/principals.ts accepts loopback Host headers or hosts listed in P2_ALLOWED_HOSTS, rejects forwarded/marked localhost requests as local owners, and generates the page CSP.

Session work runs in forked worker hosts. apps/…/session-workers.ts wraps Chord's workers component so a session:<id> route starts one process per session, stamps each worker with a generation principal, logs and redacts output, restarts limited crash loops, and serializes relocation, pause, retry, suspend, and stop operations. apps/…/worker.ts is the child entry: it opens <data>/sessions/<id>/store.sqlite and files/, connects back to the server as the trusted parent, loads the worker core plus worker facets, starts Durable's Harness only after the worker is live, and sends worker telemetry to the server when enabled. Core worker contracts and registries live in apps/…/worker.ts, including HarnessConfig, HarnessEnvironments, InputGates, ConversationLocations, ReadOnlyConversations, ConversationConfigured, and Liveness. Session location moves are explicit state transitions through SessionLocation, so plugins that cache paths or remote connections must key them by the location version.

The browser host is served by apps/…/web.ts and booted by apps/…/main.tsx. createWeb serves only authenticated app pages, public PWA files, /_chord/web/base, and content-named Chord web-surface files; guests may load only their shared session pages, public files, and app code. The page template sets the initial theme before CSS, names the current web base with data-web-version, marks owner pages for telemetry, and hands Radius shell framing metadata to apps/…/shell-bridge.ts when present. The browser runtime in apps/…/web.tsx provides React contexts, plugin slots, navigation, sheets, connection/offline state, and registry hooks; app UI components are in apps/p2/src/web/ and plugins fill slots such as the app shell, composer controls, settings sections, command-menu pages, transcript renderers, and side panels.

The TUI has a separate trust boundary. apps/…/tui.ts is the unrestricted launcher: it authenticates by local owner key, saved cookie, owner/share link, or Radius, reads the visitor's local keybindings/themes/prefs, opens the fixed-origin Chord transport, and starts apps/…/tui-client.ts. The downloaded code is built server-side by apps/…/bundles.ts as one hash-addressed ESM from apps/…/tui-worker-runtime.ts plus selected plugins/…/tui.ts facets; the launcher fetches /__p2_tui and /__p2_tui/<hash>.mjs from the authenticated server and never imports facets from the visitor checkout. apps/…/tui-sandbox.ts runs the bundle in a Node >=26.5.1 worker with permission mode, empty environment, stdout/stderr discarded, V8 limits, and an RSS/ArrayBuffer watchdog; apps/…/tui-bootstrap.mjs drops file, network, child, worker, addon, WASI, inspector, fs facade, BroadcastChannel/environment-data, and other escape surfaces before importing the in-memory bundle. apps/…/tui-client.ts keeps terminal, clipboard, editor, browser-opening, download, suspend, grants, and WebSocket authority in the launcher; apps/…/tui-filter.ts strips unsafe terminal escapes before worker output reaches the real terminal. Shared TUI rendering code is under apps/p2/src/tui/.

Plugins are the app's main feature surface. apps/…/plugins.ts discovers plugin directories by facet files (server.ts[x], worker.ts[x], web.ts[x], tui.ts[x]) under built-in apps/p2/plugins/ and user <data>/plugins, with built-ins winning name clashes. Server and worker facets are loaded by Chord's plugins component with host packages from apps/…/host-packages.ts; web facets are bundled for Chord's web surface with browser host packages from apps/…/packages.ts; TUI facets are bundled by p2's own TUI bundler. Plugins import p2 only through @p2/app/v1 and per-kind modules in apps/p2/src/api/v1/, which re-export runtime contracts, registries, helpers, Chord primitives, and selected Node/server/worker/web/tui APIs. Built-in plugins cover sessions and catalog operations (apps/p2/plugins/sessions/), chat and Durable conversations (apps/p2/plugins/chat/), provider/model resources (apps/p2/plugins/models/), devices and owner cookies (apps/p2/plugins/devices/), sharing and guest grants (apps/p2/plugins/sharing/), remote environments/sandboxes (apps/p2/plugins/envs/), Radius transport (apps/p2/plugins/radius/), workspace files (apps/p2/plugins/workspace/), terminals, artifacts/views/tree, subagents, settings, logs/telemetry, MCP, Discord, voice, coding tools, code mode, backup, projects/rollups/sidebar grouping, and agent-written plugins.

Authentication and sharing are split between runtime host checks and plugins. The server rejects unknown Hosts, cross-origin browser requests, and stale page/TUI clients in apps/…/server.ts and apps/…/stale-page.ts. Owner cookies, one-time owner links, local owner HMAC challenge/claim, owner logout, and page-cookie renewal are implemented by apps/…/server.ts on top of private data-dir files managed by its OwnerAccess. Guest share links, email grants, Radius email admission, join pages, guest cookies, archive-triggered revocation, and per-session SessionAccess are in apps/…/server.ts. Radius ownership and relayed request resolution are contributed by apps/…/server.ts; the relay may authenticate the owner directly or provide a verified email for sharing to match.

Data and configuration live mostly in <P2_DATA_DIR>. apps/…/host-dirs.ts defines the per-host store layout (server/store.sqlite, sessions/<id>/store.sqlite, each with files/) and separate telemetry store. apps/…/settings.ts validates settings.json keys for default model, thinking, enabled models, stream/retry/compaction/tool settings, cache warming, web detail level, owner name, and telemetry. Plugin-specific private files include provider credentials and model resources in apps/p2/plugins/models/, environment configs in apps/p2/plugins/envs/, owner access material in apps/p2/plugins/devices/, shares in server-store tables from apps/p2/plugins/sharing/, server name in identity.json through apps/…/server-name-file.ts, TUI defaults in <data>/tui.json through apps/…/tui-preferences.ts, user plugins in <data>/plugins/, and voice service config in <data>/voice.json through apps/…/server.ts.

Operational scripts under apps/p2/scripts/ are local capabilities. dev.mjs supervises src/…/server.ts in explicit dev mode, tracks currently running session workers, preserves them across requested restarts, and serves a private Unix dev channel in <data>/dev.sock; reload.mjs sends explicit plugin reload or backend restart commands over that channel. owner-link.ts mints private /owner#<token> invitations by proving local owner access to the loopback server. migrate-data.ts performs the offline migration from old SQLite files (server.sqlite, catalog.sqlite, shares.sqlite, subagents.sqlite, sessions/<id>.sqlite) into per-host stores and files. cloud-bundle.ts builds a static Radius Cloud Brain web bundle for a specific full commit SHA, selecting a subset of web plugins and writing a manifest, script, stylesheet, and assets under the output SHA directory. Other scripts report data, migrate store pieces, trace telemetry, and verify live sessions.

Public assets are deliberately small and non-secret. apps/p2/public/manifest.webmanifest declares Pi as a standalone installable app with app icons. apps/…/sw.js caches the last app shell and content-named /_chord/web/ files for the newest two base versions so an already-opened app can start offline or through a slow server; it never caches conversation data, /__p2_tui, uploads, plugin routes, the current base hash endpoint, or WebSockets.

Voice mode spans the p2 plugin and an optional external Python service. apps/…/server.ts watches <data>/voice.json, fetches /voices from the service, proxies owner/participant rooms over /voice/room, sample WAVs over /voice/sample, and client logs over /voice/log, and keeps the service token server-side. apps/…/worker.ts stores the owner's per-agent voice switch and voice choice in a Durable document and contributes a prompt section while owner or guest voice mode is active. apps/…/server.py is the CPU speech service: every non-health request needs Authorization: Bearer $VOICE_TOKEN; it serves /voices, POST /speak, streaming TTS on /speak/stream, and STT on /listen. TTS engines are loaded in apps/…/engines.py from Supertonic, Pocket TTS, and Kokoro model files under VOICE_MODELS; VAD and transcription use Silero and Parakeet in server.py, with segmentation in apps/…/segmenter.py and tests in apps/…/test_segmenter.py.

Tests under apps/p2/test/p2/ use Node's test runner with fake providers, temporary data/workspace directories, and port 0. The helpers create full server fixtures and bare Chord hosts; apps/…/test-host.test.ts shows how worker/server facets are tested with stubs and memory links, while apps/…/tui-fixture.ts builds an in-memory server/worker/TUI topology. Browser tests use the CDP helper in apps/…/browser.ts and are controlled by CHROMIUM_BIN/P2_BROWSER_TESTS. Coverage is broad: session lifecycle, worker auth/OAuth, web reconnection and protocol mismatch, stale/offline service worker behavior, UI parity and mobile gestures, command menu, projects/sidebar/rollups, TUI rendering/grants/isolation/radius, voice protocol/UI, dev reloads, plugins, data migration, and validation.

Coupling

Risks

  • apps/…/tui-bootstrap.mjs, apps/…/tui-sandbox.ts, apps/…/tui-client.ts, and apps/…/tui-filter.ts enforce p2's visitor-machine boundary. If a future change evaluates downloaded bundle code before permission drops, forwards raw stdout/stderr or terminal escapes, or exposes launcher actions without grants, a malicious server can read/write local files, open network/child processes, steal clipboard/title data, or drive the visitor terminal. Evidence: apps/…/tui-isolation.test.ts contains explicit escape attempts for fs, raw descriptors, net/fetch/WebSocket, child, worker, inspector, BroadcastChannel, environment data, terminal OSC, and memory DoS.
  • apps/…/worker.ts, apps/p2/plugins/subagents/, and stop/queue handling are churn-prone. Recent history for apps/p2 includes a reverted Stop fix (684fddee0) followed by multiple queue/subagent fixes (f8a292842, 87661cf35, 7ce13c086); if Stop, dequeue, or subagent message restoration changes, user inputs can be lost, duplicated, or left queued behind stopped work.
  • apps/…/principals.ts, apps/…/server.ts, apps/…/server.ts, and apps/…/server.ts are security-sensitive because they distinguish loopback local ownership, remote device cookies, guests, Radius relay users, and proxy-marker downgrades. If Host/Origin/fetch-metadata checks or proxy-marker treatment regresses, another local user, a rebinding page, or a proxy could gain owner/device privileges or read shared session bytes.
  • apps/…/host-dirs.ts and apps/…/migrate-data.ts protect durable state during layout transitions. If assertMigrated misses an old file or migration copies/renames stores non-atomically, the server can start with an empty new store beside old production data or leave a partially migrated session; migrate-data.ts mitigates this with locks, staging directories, verification, backups, and dry-run support.
  • apps/…/sw.js can make stale app code persistent if its path matching or version extraction drifts from apps/…/web.ts. If it caches a sign-in/error page as the shell or serves an old non-content-named bundle, users can get stuck offline or repeatedly reload onto incompatible code; the service worker intentionally excludes /_chord/web/base and keeps only pages with data-web-version.
  • apps/…/server.ts and apps/…/server.py proxy live microphone audio and synthesized speech through authenticated WebSockets. If participant rechecks, socket limits, token forwarding, or room naming regress, a guest could retain access after revocation, view-only guests could listen/speak, or the service token could leak to browsers.