pi-remote-control 1.0.0

package/docs/adr/0023-return-remote-compact-results.md

@@ -0,0 +1,29 @@
+# Return remote compact results
+
+## Title
+
+Return remote compact results
+
+## Status
+
+Accepted
+
+## Context
+
+ADR 0021 added `/compact` as an explicit allowlisted remote action. The current request path only tells iOS that the daemon accepted the command for delivery to the owning TUI extension. It does not tell iOS whether Pi compaction eventually succeeded, what summary was produced, or why compaction failed.
+
+Pi's extension API triggers compaction asynchronously through the live TUI context and supports completion and error callbacks.
+
+## Decision
+
+Return a `requestId` from `POST /v1/sessions/{sessionId}/compact` and report the asynchronous outcome on the session WebSocket as `remote_compact_result`.
+
+The TUI extension handles `remote_compact` by calling `ctx.compact()` with completion and error callbacks. On success, it posts `{ "type": "remote_compact_result", "requestId": "...", "ok": true, "summary": "...", "firstKeptEntryId": "...", "tokensBefore": 12345 }` to the daemon. On failure, it posts `{ "type": "remote_compact_result", "requestId": "...", "ok": false, "message": "..." }`.
+
+The daemon forwards this result to iOS WebSocket subscribers for the same session. The result is live stream state, not durable daemon state and not part of HTTP session snapshots.
+
+## Consequences
+
+The iOS app can correlate compact completion with the original request and show success summaries or failure messages.
+
+Clients that need compact results must keep the session WebSocket open after the HTTP compact request is accepted.

package/docs/architecture.md

@@ -0,0 +1,96 @@
+# Architecture
+
+## Purpose
+
+`pi-remote-control` is a long-lived local relay service that exposes authenticated, Tailscale-reachable remote control for Pi TUI sessions that the user explicitly enables. It is distributed as a Pi package, but the daemon process itself is not a Pi extension runtime.
+
+## Pi package shape
+
+The package contains two runtime surfaces:
+
+- Daemon binary: the long-lived HTTP/WebSocket service used by the iOS app and the Pi TUI extension.
+- Pi extension: the TUI-facing control surface that registers remote-control commands, owns the active Pi session integration, and forwards session events to the daemon.
+
+The extension must not host the daemon server in-process. Pi extensions are loaded per Pi process and are rebound during session replacement flows, so a server started directly from extension load would be tied to the wrong lifecycle and could be attempted once per Pi session/process.
+
+## Process lifecycle
+
+The daemon is started by one of these explicit singleton mechanisms:
+
+1. Manual CLI:
+   - `pi-remote-control start`.
+2. Pi extension commands:
+   - `/remote-control` starts the daemon if needed before enabling the current TUI session.
+   - `/remote-control-pair` starts the daemon if needed before creating a pair code.
+
+OS service installation is intentionally deferred for the MVP.
+
+The extension may perform a cheap health check when a command runs, but it must not auto-start the daemon during extension load. Daemon startup goes through singleton lock acquisition and returns immediately when an existing daemon is healthy.
+
+## Singleton ownership
+
+Only the daemon process owns the network listener, pairing state, device tokens, active TUI session registry, and iOS WebSocket fanout. Singleton enforcement uses `daemon.lock` under the daemon state directory. The lock is created atomically during startup and contains the daemon PID for `status` and `stop`.
+
+If another Pi process loads the extension, it sees the existing daemon and may register its own TUI session only after the user runs `/remote-control` in that process.
+
+## Pi extension responsibilities
+
+The extension responsibilities are session-aware:
+
+- Register `/remote-control` as a no-argument toggle for the current TUI session.
+- Register `/remote-control-pair` as the only pair-code creation command and render its pairing link as a QR code with expiration time.
+- Start the daemon on demand when either command needs it.
+- When `/remote-control` enables a session, open a control channel to the daemon, register current session metadata, and keep the registration fresh with heartbeats.
+- When a locally active session heartbeat finds that the daemon no longer has the registration, re-register the current TUI session; if re-registration fails, clear local active state and notify the user.
+- When `/remote-control` disables a session or the TUI session shuts down, unregister it; if shutdown cleanup is missed, the daemon expires the registration after the TUI PID exits or heartbeats stop.
+- Forward Pi turn, message, assistant streaming, tool execution, queue, status, and lifecycle events to the daemon while remote control is active. These TUI-to-daemon events are package-internal inputs for daemon normalization.
+- Compute structured runtime-status snapshots from the live TUI context and send them to the daemon when status inputs change.
+- Receive daemon-forwarded prompt, abort, and compact commands and apply them to the current live TUI runtime through Pi extension APIs.
+- Report asynchronous compact success or failure results back to the daemon for iOS WebSocket subscribers.
+
+The extension owns live Pi session control. It does not expose a network listener to iOS.
+
+## Daemon responsibilities
+
+The daemon responsibilities are independent of Pi SDK session ownership:
+
+- Serve the HTTP/WebSocket API documented in `docs/interfaces.md`.
+- Enforce device token authentication for iOS requests and non-loopback TUI control requests.
+- Persist pairing codes, paired device token hashes, and daemon metadata.
+- Track currently activated TUI sessions and group them into projects for iOS display.
+- Relay prompt, abort, and compact requests from iOS to the TUI extension that owns the target session.
+- Forward TUI-reported compact results to subscribed iOS clients.
+- Store the latest TUI-reported runtime-status snapshot for each active session and include it in session state sent to iOS.
+- Serve bounded recent transcript snapshots and older transcript pages for active sessions by reading Pi session JSONL files and normalizing entries into public `TranscriptMessage` values.
+- Normalize live TUI Pi events into public transcript stream events for subscribed iOS WebSocket clients without using the stream for full historical transcript payloads.
+- Broadcast session updates to subscribed iOS WebSocket clients.
+
+The daemon does not use Pi SDK or RPC to discover, open, prompt, stream, or abort sessions in the MVP.
+
+## Session runtime model
+
+A live session controller is represented by a TUI extension control channel, not a daemon-created Pi runtime. The control channel is the authority for one remote-control-enabled TUI session. It also provides runtime-status snapshots for model, usage, cost, and context information. If the channel closes, the owning TUI PID exits, or heartbeats stop, the daemon marks the session inactive, removes it from project/session listings, and notifies iOS subscribers. If the same TUI process still has local remote control active and later observes the missing registration through heartbeat polling, it re-registers the session.
+
+Multiple TUI processes may enable remote control at the same time. Each active session has one owning TUI control channel. The daemon rejects prompt or abort requests for sessions without an active owner.
+
+## Persistence model
+
+The daemon binds the configured remote-facing address and, for specific non-loopback bind addresses, an additional `127.0.0.1` listener on the same port for local TUI control. The extension uses the loopback listener by default; iOS uses the configured advertised URL.
+
+Session detail reads are bounded and derive transcript history from the active session's Pi JSONL session file: the daemon returns a recent transcript window first, then serves older transcript pages on request. Session detail reads and initial WebSocket state also include the latest TUI-reported `RuntimeStatus` snapshot when available. HTTP transcript reads and WebSocket live updates expose the same public `TranscriptMessage` shape. WebSocket streams are for normalized live updates, status updates, and asynchronous remote-action results; they must not carry unbounded session history. The initial WebSocket `session_state` is further bounded to a small recent window with oversized transcript payloads truncated to previews.
+
+The daemon stores its own durable state in a daemon state directory, defaulting to `~/.pi/remote-control` and overridable with `PI_REMOTE_CONTROL_DIR`.
+
+Durable daemon-owned files:
+
+- `config.json`: daemon configuration such as bind address and advertised base URL.
+- `daemon.sqlite`: SQLite database for paired devices, token hashes, pairing codes, and metadata.
+- `daemon.lock`: singleton lock file containing the daemon PID.
+
+Active TUI sessions are process state, not durable daemon state. Pi session transcripts remain in Pi's own JSONL session files under Pi's session directory. The daemon reads those files for HTTP transcript snapshots and pages instead of maintaining a duplicate completed-transcript snapshot in memory.
+
+## Installation model
+
+The package can be installed with Pi package installation, for example from a local path, git source, or npm source. The package manifest exposes the extension through the `pi.extensions` field and the daemon binary through the normal package binary entry.
+
+Installing the Pi package makes Pi aware of `/remote-control` and `/remote-control-pair`; it does not by itself imply that the daemon process is running or that any TUI session is remotely visible. Pairing QR codes require an advertised base URL that is reachable from iOS, such as a Tailscale HTTPS or HTTP URL.

package/docs/data-model.md

@@ -0,0 +1,284 @@
+# Data model
+
+## Persistent storage
+
+The daemon state directory defaults to `~/.pi/remote-control` and can be overridden with `PI_REMOTE_CONTROL_DIR`.
+
+```text
+~/.pi/remote-control/
+├── config.json
+├── daemon.sqlite
+└── daemon.lock
+```
+
+The directory must be created with owner-only permissions. Database and token-bearing files must not be world-readable. `daemon.lock` is created atomically and contains the daemon PID for singleton enforcement, `status`, and `stop`.
+
+## SQLite schema
+
+`daemon.sqlite` is the daemon-owned source of truth for remote access state. Active TUI sessions are process state and Pi session JSONL files remain the source of truth for transcripts.
+
+```sql
+create table meta (
+  key text primary key,
+  value text not null
+);
+
+create table devices (
+  id text primary key,
+  name text not null,
+  token_hash text not null unique,
+  created_at text not null,
+  last_seen_at text,
+  revoked_at text
+);
+
+create table pairing_codes (
+  id text primary key,
+  code_hash text not null unique,
+  created_at text not null,
+  expires_at text not null,
+  consumed_at text
+);
+```
+
+Pairing codes and device token hashes are durable. Active session registry entries are rebuilt by currently running Pi TUI extensions after the user enables `/remote-control`. Completed transcript history is read from Pi session JSONL files, not stored in daemon SQLite or active registry memory.
+
+## Config file
+
+```ts
+type DaemonConfig = {
+  bindAddress: string;
+  advertisedBaseUrl?: string;
+};
+```
+
+`config.json` is human-editable daemon configuration. It does not contain allowed project roots for the MVP because project visibility is derived from active remote-control TUI sessions. `bindAddress` is the remote-facing listener. When it is a specific non-loopback address, the daemon also listens on `127.0.0.1` on the same port for local TUI control. `advertisedBaseUrl` is the URL encoded into pairing QR codes and used by iOS for future daemon calls; it must not be a loopback or wildcard address when pairing a separate device.
+
+## Daemon process state
+
+```ts
+type DaemonState = {
+  pid: number;
+  startedAt: string;
+  version: string;
+  bindAddress: string;
+  stateDir: string;
+};
+```
+
+Stored process state is used for health checks and singleton detection. It is not session history.
+
+## Pairing code
+
+```ts
+type PairingCode = {
+  codeHash: string;
+  expiresAt: string;
+  createdAt: string;
+  consumedAt?: string;
+};
+```
+
+Pairing codes are short-lived. The daemon stores code hashes, not raw codes. Raw pair codes are created only for `/remote-control-pair` and are encoded into the Pi TUI QR code.
+
+## Pairing link
+
+```ts
+type PairingLink = {
+  scheme: "pi-remote";
+  action: "pair";
+  baseUrl: string;
+  code: string;
+  expiresAt: string;
+};
+```
+
+The raw link is encoded as a `pi-remote://pair?...` URL and rendered as a QR code by `/remote-control-pair`. The raw link is not printed as a separate TUI text line.
+
+## Paired device
+
+```ts
+type PairedDevice = {
+  id: string;
+  name: string;
+  tokenHash: string;
+  createdAt: string;
+  lastSeenAt?: string;
+  revokedAt?: string;
+};
+```
+
+The iOS app stores the bearer token in Keychain. The daemon stores only token hashes.
+
+## Active project
+
+```ts
+type ActiveProject = {
+  id: string;
+  name: string;
+  path: string;
+};
+```
+
+An active project exists while at least one registered TUI session for that project has remote control enabled.
+
+## Active TUI session
+
+```ts
+type ActiveTuiSession = {
+  id: string;
+  piSessionId: string;
+  projectId: string;
+  sessionFile: string;
+  name?: string;
+  pid: number;
+  messageCount: number;
+  isStreaming: boolean;
+  runtimeStatus?: RuntimeStatus;
+  registeredAt: string;
+  lastSeenAt: string;
+};
+```
+
+An active TUI session is owned by one Pi extension control channel. It is removed when `/remote-control` disables it, the TUI session shuts down, or the control channel closes. If the daemon removes it because heartbeats stopped but the same TUI process still has local remote-control state active, the TUI extension can recreate the active session by re-registering on the next heartbeat miss. Its `sessionFile` points to the Pi JSONL transcript used for HTTP transcript reads. Its `runtimeStatus` is the latest structured runtime-status snapshot reported by the owning TUI extension.
+
+## Runtime status
+
+```ts
+type RuntimeStatus = {
+  model: null | {
+    provider: string;
+    id: string;
+    name?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    reasoning?: boolean;
+  };
+  thinkingLevel: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | null;
+  usage: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: {
+      input: number;
+      output: number;
+      cacheRead: number;
+      cacheWrite: number;
+      total: number;
+    };
+  };
+  context: null | {
+    tokens: number | null;
+    contextWindow: number;
+    percent: number | null;
+  };
+  updatedAt: string;
+};
+```
+
+`RuntimeStatus` is computed by the live TUI extension from Pi extension context. It is process state in the daemon, not durable storage. `context.tokens` and `context.percent` may be `null` when Pi reports current context usage as unknown.
+
+## Session snapshot
+
+```ts
+type SessionSnapshot = {
+  session: ActiveTuiSession;
+  messages: TranscriptMessage[];
+  olderMessagesCursor?: string;
+  hasOlderMessages: boolean;
+  tools: ToolCallStatus[];
+  isStreaming: boolean;
+  pendingMessageCount: number;
+  runtimeStatus: RuntimeStatus | null;
+};
+```
+
+The daemon returns a bounded recent-message snapshot for active sessions so newly connected iOS clients can render persisted state before incremental events arrive. Snapshot messages are derived from the session's Pi JSONL `sessionFile` at request time and normalized into `TranscriptMessage` values. The snapshot includes the latest TUI-reported `RuntimeStatus` when available. Older transcript history is loaded through explicit transcript page requests.
+
+## Transcript message
+
+```ts
+type TranscriptMessage = {
+  id: string;
+  role: "user" | "assistant" | "toolResult" | "system";
+  content: TranscriptContentBlock[];
+  text: string;
+  textTruncated?: boolean;
+  textOriginalBytes?: number;
+  createdAt: string;
+  toolCallId?: string;
+  toolName?: string;
+  isError?: boolean;
+  isStreaming: boolean;
+};
+
+type TranscriptContentBlock =
+  | { type: "text"; text: string; truncated?: boolean; originalBytes?: number }
+  | { type: "thinking"; thinking: string; truncated?: boolean; originalBytes?: number }
+  | { type: "toolCall"; id: string; name: string; arguments: unknown; argumentsTruncated?: boolean; argumentsOriginalBytes?: number }
+  | { type: "image"; data: string; mimeType: string; truncated?: boolean; originalBytes?: number };
+```
+
+`TranscriptMessage` is the public transcript shape used by both HTTP transcript reads and WebSocket live updates. `content` preserves structured Pi message blocks. `text` is a display summary derived from text-like blocks and kept for clients that need a simple preview. Tool-result messages carry `toolCallId`, `toolName`, and `isError` when present. Truncation metadata is used when the daemon intentionally sends a preview instead of the full string payload.
+
+## Transcript page
+
+```ts
+type TranscriptPage = {
+  messages: TranscriptMessage[];
+  olderMessagesCursor?: string;
+  hasOlderMessages: boolean;
+};
+```
+
+Transcript pages contain bounded message windows ordered oldest-to-newest by `createdAt` and are derived from the session's Pi JSONL `sessionFile` at request time. Cursor values are generated from the oldest loaded message's `createdAt` timestamp, are daemon-encoded, and are opaque to clients. Clients merge pages and live updates by de-duplicating `TranscriptMessage.id`.
+
+## Transcript stream event
+
+```ts
+type TranscriptStreamEvent =
+  | { type: "session_state"; state: SessionSnapshot }
+  | { type: "turn_start"; turnIndex: number; createdAt?: string }
+  | { type: "turn_end"; turnIndex: number }
+  | { type: "transcript_message_start"; message: TranscriptMessage }
+  | { type: "transcript_message_patch"; messageId: string; contentIndex?: number; patch: TranscriptMessagePatch }
+  | { type: "transcript_message_end"; message: TranscriptMessage }
+  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: unknown }
+  | { type: "tool_execution_update"; toolCallId: string; toolName: string; partialResult: unknown }
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result?: unknown; isError: boolean }
+  | { type: "runtime_status"; status: RuntimeStatus }
+  | RemoteCompactResultEvent
+  | { type: "session_closed" }
+  | { type: "error"; error: string };
+
+type TranscriptMessagePatch =
+  | { type: "text_delta"; delta: string }
+  | { type: "thinking_delta"; delta: string }
+  | { type: "toolCall"; toolCall: { type: "toolCall"; id: string; name: string; arguments: unknown } }
+  | { type: "replace"; message: TranscriptMessage };
+
+type RemoteCompactResultEvent =
+  | { type: "remote_compact_result"; requestId: string; ok: true; summary: string; firstKeptEntryId: string; tokensBefore: number }
+  | { type: "remote_compact_result"; requestId: string; ok: false; message: string };
+```
+
+Stream events are daemon-normalized and public to iOS. They are derived from package-internal TUI Pi events and TUI-computed runtime-status snapshots but do not expose raw Pi event payloads. `turn_start` and `turn_end` are lifecycle signals; transcript content remains represented by `TranscriptMessage` events. `runtime_status` replaces the previous runtime-status snapshot for the session. `remote_compact_result` reports the asynchronous outcome of a remote compact request and is correlated by `requestId`; it is not stored in daemon durable state. The initial `session_state` stream event is limited to at most 20 recent messages; oversized string payloads in those messages are truncated to their first 10 KiB and marked with truncation metadata.
+
+## TUI control channel
+
+```ts
+type TuiControlChannel = {
+  sessionId: string;
+  pid: number;
+  status: "active" | "closing";
+  lastHeartbeatAt: string;
+  latestRuntimeStatus?: RuntimeStatus;
+};
+```
+
+The control channel is the daemon's route for sending remote prompt, abort, and compact commands to the owning TUI extension and for receiving compact results. Loopback TUI control requests do not require a bearer token; non-loopback TUI control requests do.
+
+## Tool state
+
+`tools` is a compact snapshot of active or recent tool execution state associated by `toolCallId`. Tool-call declarations are preserved inside assistant `TranscriptMessage.content`; tool execution progress and completion are delivered on the WebSocket stream as normalized tool events.