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.
101 lines
4.5 KiB
Markdown
101 lines
4.5 KiB
Markdown
# Pi Status Bridge — Implementation Plan
|
||
|
||
## Reason for existence
|
||
|
||
Turn the approved design into small, verifiable slices while preserving Pi as the source of truth for tool policy and model configuration.
|
||
|
||
## Milestone 1 — Bridge foundation
|
||
|
||
1. Create the bridge package and an explicit local protocol schema.
|
||
- Define agent ID, worktree path, state, event, extension-request, and command envelopes.
|
||
- Define socket path, file modes, lock/PID format, and stale-owner algorithm.
|
||
- Verify: schema tests reject malformed messages and cross-worktree requests.
|
||
|
||
2. Implement single-instance startup and Unix-socket serving.
|
||
- Acquire lock atomically; detect a live owner; recover only a proven-stale lock.
|
||
- Create the socket in `$XDG_RUNTIME_DIR` with owner-only permissions.
|
||
- Verify: a second bridge refuses startup; a different user cannot connect.
|
||
|
||
3. Implement the Pi RPC child adapter.
|
||
- Spawn `pi --mode rpc` with an explicit worktree cwd and session location.
|
||
- Correlate command IDs, parse JSONL, normalize state/event payloads, and preserve transcript cursors.
|
||
- Verify: a fake Pi RPC fixture exercises prompt, streaming, tool events, queue updates, and extension UI requests.
|
||
|
||
## Milestone 2 — Agent registry and recovery
|
||
|
||
1. Implement worktree-keyed agent management.
|
||
- Canonicalize paths before registry lookup.
|
||
- Create/resume the home agent on bridge startup.
|
||
- Create/resume worktree agents only when selected or inferred.
|
||
- Verify: separate worktrees never share agent IDs, transcript entries, or outgoing prompts.
|
||
|
||
2. Implement session persistence and recovery.
|
||
- Store the Pi session reference per agent.
|
||
- Restart unexpected exits with bounded exponential backoff.
|
||
- Resume the prior Pi session; publish failed-recovery state after limits are exhausted.
|
||
- Verify: injected crashes resume the expected session and stop retrying at the configured bound.
|
||
|
||
3. Proxy Pi-owned controls without bridge defaults.
|
||
- Read current model/thinking state from Pi.
|
||
- Forward supported user changes directly to Pi and refresh displayed state from Pi’s response/events.
|
||
- Verify: bridge restarts do not reapply an independent model or thinking value.
|
||
|
||
## Milestone 3 — Adapter-facing API and local helper
|
||
|
||
1. Implement adapter operations.
|
||
- Agent/session listing and explicit selection.
|
||
- State/transcript subscription and replay after reconnect.
|
||
- Prompt, steer, follow-up, abort, and extension UI response forwarding.
|
||
- Verify: a scripted local client can reconnect and catch up without duplicate events.
|
||
|
||
2. Build the local client helper.
|
||
- Make it the fallback transport for hosts that cannot open Unix sockets.
|
||
- Support only the approved bridge protocol; never start a network listener.
|
||
- Verify: helper cannot reach a socket owned by another user.
|
||
|
||
## Milestone 4 — Noctalia adapter
|
||
|
||
1. Implement the bar widget.
|
||
- Render state glyph/color, selected project, and attention badge.
|
||
- Keep streaming/tool detail out of the bar.
|
||
- Verify: fixture states map to the agreed compact bar states.
|
||
|
||
2. Implement shortcut and popover behavior.
|
||
- Infer focused worktree when unambiguous.
|
||
- Otherwise open a selector defaulted to home.
|
||
- Support explicit switching, transcript streaming, composer, queue/tool state, extension forms, session manager, and Pi-proxied controls.
|
||
- Escape dismisses the popover only.
|
||
- Verify: manual checklist passes on Noctalia.
|
||
|
||
## Milestone 5 — Hardening and release readiness
|
||
|
||
1. Add observability and safe failure presentation.
|
||
- Structured local logs for agent lifecycle, recovery, socket ownership, and protocol errors.
|
||
- Redact prompt and tool payload content by default.
|
||
- Verify: failure reports identify the agent/worktree without leaking transcript content.
|
||
|
||
2. Run the approved readiness gate.
|
||
- Execute automated bridge tests, manual Noctalia QA, cross-user socket rejection check, crash/recovery scenarios, and overnight soak.
|
||
- Verify: all exit criteria in `TEST_PLAN.md` pass before daily use.
|
||
|
||
## Dependencies
|
||
|
||
```text
|
||
Foundation → Pi RPC adapter → registry/recovery → adapter API/helper → Noctalia UI → hardening/soak
|
||
```
|
||
|
||
## Never rules
|
||
|
||
- Never let the bridge decide tool approval policy.
|
||
- Never route a prompt to a worktree different from the selected agent.
|
||
- Never expose a TCP listener in v1.
|
||
- Never persist model or thinking defaults outside Pi.
|
||
|
||
## Verification
|
||
|
||
```sh
|
||
# Plan completeness: all five planned milestones are present.
|
||
grep -c '^## Milestone' IMPLEMENTATION_PLAN.md
|
||
# Expected: 5
|
||
```
|