observal-pi

Session telemetry extension for Pi that pushes conversation traces to your Observal server.

Install

pi install npm:observal-pi

Prerequisites

1. An Observal account (run observal auth login to authenticate)
2. Pi installed (>=0.74.0)

What it does

• Incremental push: After each user prompt (agent_end), durably stages new JSONL lines before sending them to Observal
• Acknowledged checkpoints: Advances byte and line cursors only after a contiguous server acknowledgement
• Final push: On session exit, sends remaining lines and a SHA-256 audit manifest; mismatches replay from the requested range
• Crash recovery: Retries durable pending batches and rebuilds missing/corrupt cursors from the authenticated server checkpoint
• Status indicator: Shows ● observal in the footer with line count

Commands

Command	Description
/obs-sync	Show sync status (lines pushed, server URL)
/obs-sync flush	Force push pending lines now
/obs-sync config	Show config file path and server URL

Design

• Zero dependencies: only node:* built-ins
• Fail-open: never throws, never crashes pi. If the server is unreachable, pi continues normally
• 5s timeout: all HTTP calls abort after 5 seconds
• Chunked uploads: batches of 500 lines max per request
• Retry-safe: pending batches retain stable source indexes and are retried until acknowledged

Configuration

The extension reads credentials from ~/.observal/config.json (written by observal auth login):

{
  "server_url": "https://your-server.observal.dev",
  "access_token": "..."
}

Acknowledged cursors are stored atomically in ~/.observal/sync_state.json. Unacknowledged Pi batches remain in ~/.observal/pi_session_outbox/ until the server confirms a contiguous checkpoint.

License

Apache-2.0. See LICENSE