pi-agent-web v0.1.0

Pi Agent Web v0.1.0 Release Notes

Pi Agent Web is a local, Session-native web workbench for Pi Coding Agent's RPC mode. It provides a multi-session development interface where active sessions run in isolated supervisor processes and background tasks continue undisturbed during browser navigation.

This release is built from verified commit 0f2172cc900a57a15c136f1585999b2aa3b4a8df following completion of the comprehensive benchmark harness, 800-trial recovery verification matrix, and representative dual-environment performance baseline registration (#28).

Highlights & Capabilities

• Native Session Truth: Directly reads and persists to native Pi JSONL files. No secondary database or out-of-sync history store.
• Supervisor Gateway & Process Isolation: One independently managed Pi RPC process per active Session, with hot-process pool bounds and graceful lifecycle teardown.
• Session-Scoped Browser State: Navigation switches only the active view; background turns continue streaming without interruption.
• Resilient Protocol & Recovery: Authenticated loopback WebSocket with fenced mutations, deterministic resync, and automated recovery across disconnects, replay gaps, process crashes, and session rekeys (verified across 800 fault-injection trials with 0 duplicate/lost events and 100% projection match).
• Rich Interaction Surface: Live Markdown rendering, collapsible thought/tool inspect panels, slash commands, image attachments, and Extension UI integration.
• Recoverable Session Deletion: Verified directory-environment deletion via same-filesystem move to recoverable trash; direct unlinks are strictly prohibited.

System Requirements

• Runtime: Node.js >= 22.0.0, pnpm 11.21.0
• Platform: macOS (Apple Silicon / Intel) or Linux (x86_64)
• Pi Compatibility: Tested against Pi Coding Agent RPC mode (@earendil-works/pi-coding-agent@0.84.2, protocol v1.4)
• Browser: Chromium-based modern browser with WebSocket and CSS Container Query support

Security & Operational Boundary

• Loopback-Only: The Gateway listens strictly on loopback interfaces (127.0.0.1 / ::1). It is a single-user workbench, not a multi-tenant or public server. Do not expose via public reverse proxy.
• Credential Storage: Provider API keys, secrets, and auth tokens remain strictly within Pi's native configuration files. Pi Agent Web never stores, persists, or transmits provider credentials.
• Untrusted Boundaries: All external and extension-rendered inputs, file names, and frame payloads are treated as untrusted and guarded by strict schema validation.

Performance Benchmarks & Evidence

• Reproducible representative benchmarks and frozen dual-environment baselines (GitHub Actions + local Apple Silicon M2 cohort) are documented in the Performance Benchmark Report.
• Evaluated against strict regression budgets across all six completion medians (streaming, 4-session fairness, content roundtrip; coalesced and sequential) and long-history synthetic stress (1,000 and 5,000 Turns, up to 16 MiB native history). The 5,000-Turn full-mount cell is a declared gap, not a passing measurement; see Issue #117.

Product Demo

• Visual preview cards are available in the repository README.
• The end-to-end multi-session workflow, background continuity, and recovery interactions are outlined in the Demo Storyboard.

Known Limitations & Deferred Work

• Gateway Restart Performance: Explicitly deferred to Issue #105. (Restart functional recovery is verified in the standard test suite).
• Multi-Client Adversarial Backpressure: Retained outside Phase 1; workbench assumes a single active browser operator.
• Desktop Application Packaging: Retained as deferred product direction Issue #21.
• Phase 2 Benchmark Coverage: Sustained-load arrival profiling, mixed-history 5,000-Turn full mounting, recovery fault-state coverage, and cross-layer resource measurements are carried by Issue #117. They are declared gaps, not passing results.
• Product Demonstration Recording: The storyboard in docs/demo-transcript.md is a plan, not a completed video. Recording delivery is carried by Issue #118.

Upgrade Expectations

This is the first published release, so there is no earlier supported version to upgrade from and no
migration is required. Replacing the unpacked directory and rerunning the install step is sufficient:

npm install --omit=dev --ignore-scripts

What is preserved across an in-place upgrade:

• Pi Session JSONL remains the only durable Session truth. The release does not create a second
  history store, so Session history survives any workbench upgrade and can also be read by Pi itself.
• Pi's own configuration, credentials, and Session directories are outside the archive and are never
  rewritten by the install or startup path.

What may be regenerated:

• Workbench-local data under the web data directory (workspace preferences, attachment blobs,
  recoverable session trash) uses the current schema. A file whose schema version is not recognized
  is treated as unreadable rather than migrated: the loader records an error and clears in-memory
  preference records, and the legacy hint path is re-read. Workspace preferences are discovery and
  presentation hints only; losing them does not affect Session truth.
• Recoverable session trash is convenience state. Its contents are not required for correctness.

Uninstalling is a directory removal. No system-wide installation, service registration, or registry
entry is created.

Upgrade expectations for future releases are not committed here. Any release that changes the
durable format, the Pi RPC boundary, or either compatibility contract must state its own migration
notes.

Quick Start & Installation

# 1. Download and unpack
tar -xzf pi-agent-web-v0.1.0.tar.gz
cd pi-agent-web-v0.1.0

# 2. Verify SHA-256 checksum
sha256sum -c pi-agent-web-v0.1.0.tar.gz.sha256

# 3. Install production dependencies
npm install --omit=dev --ignore-scripts

# 4. Launch workbench
npx pi-web

Documentation corrections merged after the tag was created (stale suite-5 reference names, the
benchmark report's p95 and artifact links, and the deferred-work pointers) are on main; the links
above resolve to main for that reason. The tagged tree itself is unchanged.

Verification Checksums

Asset	SHA-256 Checksum
pi-agent-web-v0.1.0.tar.gz	97389798ee97a320dafcfe97c2e35001c46e114bc039ddfb5bffc80b805f10dc