alex
b7fea83ed6
Deliver the initial local bridge, Noctalia v4/v5 adapters, desktop client, service unit, tests, and implementation documentation for persistent Pi status and control.
102 lines
4.5 KiB
Markdown
102 lines
4.5 KiB
Markdown
# Pi Status Bridge — Design
|
||
|
||
## Reason for existence
|
||
|
||
Provide a persistent, local Pi coding-agent experience through a compact status-bar UI without duplicating Pi’s terminal TUI or weakening tool-owned safety policy.
|
||
|
||
## Goals
|
||
|
||
- Keep one Pi RPC agent per project/worktree, plus a home-directory agent started with the bridge.
|
||
- Open a chat-like popover by shortcut; accept prompts, steering messages, follow-ups, and structured extension questions.
|
||
- Present compact status in Noctalia: state glyph/color, active project, and attention badge.
|
||
- Make the bridge reusable by future desktop/status-bar adapters.
|
||
- Resume sessions after bounded automatic recovery.
|
||
|
||
## Non-goals
|
||
|
||
- Terminal emulation or embedding Pi’s terminal TUI.
|
||
- Rendering rich TUI-only extension overlays.
|
||
- Inventing approval policy or interpreting tool permissions.
|
||
- A network service, remote control, or adapters beyond Noctalia in v1.
|
||
|
||
## Architecture
|
||
|
||
```text
|
||
Noctalia bar + popover ─┐
|
||
├─ local client helper ─ Unix socket ─ Pi Status Bridge
|
||
future host adapter ────┘ │
|
||
├─ Agent registry
|
||
├─ session/recovery supervisor
|
||
└─ pi --mode rpc (one child/worktree)
|
||
```
|
||
|
||
### Bridge
|
||
|
||
The bridge is the only component that starts, stops, and restarts Pi. It owns:
|
||
|
||
- Agent registry keyed by canonical project/worktree path.
|
||
- A long-lived `pi --mode rpc` child per active worktree.
|
||
- Translation of Pi JSONL events into a stable local event model.
|
||
- Session resume after child restart, bounded exponential backoff, and terminal error state after exhaustion.
|
||
- A per-user Unix-domain socket under `$XDG_RUNTIME_DIR` with restrictive permissions.
|
||
- A lock/PID file with stale-owner recovery.
|
||
|
||
It exposes only local request/response and subscription operations: enumerate/select agents, send `prompt`/`steer`/`follow_up`, abort, read state/transcript, proxy model/thinking commands, and answer extension UI requests.
|
||
|
||
### Noctalia adapter
|
||
|
||
The adapter is presentation only:
|
||
|
||
- Bar: glyph/color, selected project name, attention badge.
|
||
- Shortcut: choose the focused worktree when unambiguous; otherwise open a selector defaulted to home.
|
||
- Popover: transcript, composer, tool activity, queue state, extension UI requests, agent/session manager, and Pi-proxied model/thinking controls.
|
||
- Escape hides the popover only; it never aborts Pi.
|
||
|
||
The popover always permits explicit project/worktree switching.
|
||
|
||
## Agent lifecycle
|
||
|
||
1. Bridge starts and acquires the lock.
|
||
2. It creates/resumes the home agent.
|
||
3. A focused worktree or explicit selection creates/resumes that worktree’s agent.
|
||
4. On unexpected child exit, the bridge retries with bounded exponential backoff and resumes the saved Pi session.
|
||
5. After retry exhaustion, it publishes an error state and exposes explicit restart/retry controls.
|
||
|
||
## Interaction contract
|
||
|
||
| State | Bar | Popover action |
|
||
| --- | --- | --- |
|
||
| Idle | neutral glyph | send prompt, browse transcript |
|
||
| Streaming/tool active | working glyph | stream response/tool progress, steer or abort |
|
||
| Queued input | attention badge | inspect queue or send follow-up |
|
||
| Extension question/confirmation | attention badge | render request and return response unchanged |
|
||
| Failed recovery | error glyph | inspect failure and retry/restart |
|
||
|
||
## Policy and configuration boundaries
|
||
|
||
- Extensions/tools decide whether approval is required.
|
||
- The bridge forwards only RPC-compatible structured extension requests and responses.
|
||
- Pi chooses model and thinking defaults and remains the source of truth.
|
||
- The popover may display current Pi values and forward supported changes; it stores no competing defaults or persistence policy.
|
||
|
||
## Security invariants
|
||
|
||
- **Never** listen on TCP for v1.
|
||
- **Never** allow another user to attach to the socket.
|
||
- **Never** map a bridge request to another worktree silently.
|
||
- **Never** treat a bridge/UI action as permission to bypass extension-owned approvals.
|
||
|
||
## Key risks
|
||
|
||
- Focused-window worktree inference can fail; explicit selection is mandatory.
|
||
- TUI-only extension overlays cannot cross the RPC boundary.
|
||
- The local client helper must retain same-user-only access.
|
||
- Named-session controls must clearly show the selected worktree before acting.
|
||
|
||
## Verification
|
||
|
||
```sh
|
||
# After implementation: required architecture artifacts exist.
|
||
test -f DESIGN.md && test -f IMPLEMENTATION_PLAN.md && test -f TEST_PLAN.md
|
||
```
|