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.
120 lines
5.3 KiB
Markdown
120 lines
5.3 KiB
Markdown
# Full Pi Panel Specification
|
|
|
|
## Reason for existence
|
|
|
|
Replace the compact Noctalia status widget with a feature-equivalent local Pi
|
|
client panel. The bar remains a compact launcher and status indicator; the
|
|
panel is the single interaction surface.
|
|
|
|
## User flow
|
|
|
|
1. The user session starts one bridge-managed Home agent for `$HOME`.
|
|
2. Clicking the bar opens the **Output** view for the selected agent. Home is
|
|
selected by default.
|
|
3. Output shows transcript/history, live streaming/tool/queue state, extension
|
|
requests, and one composer anchored at the bottom.
|
|
4. The composer mirrors the confirmed TUI workflow: submit a normal prompt;
|
|
when Pi is busy, Pi queues it as a follow-up. The panel never asks the user
|
|
to choose prompt versus steer versus follow-up for ordinary submission.
|
|
5. **Settings** is the only location for folder management. Adding an absolute
|
|
folder explicitly creates/resumes its own agent, persists it, and selects it.
|
|
6. The user may switch among remembered agents from Settings. Previously added
|
|
folders do not start at login unless selected; Home is always running.
|
|
|
|
## Views
|
|
|
|
### Output (default)
|
|
|
|
- Header: selected folder, agent health, streaming/queue/recovery status.
|
|
- Scrollable transcript: user, assistant, tool result, and visible custom
|
|
messages. Thinking content follows Pi visibility policy; it is not exposed by
|
|
default merely because the panel exists.
|
|
- Tool activity: current tool name/progress while active and tool results in
|
|
history after completion.
|
|
- Composer: one input and one submit action. It accepts normal text, Pi command
|
|
syntax, prompt templates, and skills exactly as Pi RPC `prompt` accepts them.
|
|
- Suggestions: when composer input begins with `/`, show Pi-provided
|
|
`get_commands` entries. Selecting one inserts it; it does not execute until
|
|
submitted.
|
|
- Extension requests: select, confirm, input, and editor map to native panel
|
|
controls and return the exact request ID/response shape. Unsupported custom
|
|
TUI UI renders an explicit unsupported state and never approves anything.
|
|
|
|
### Settings
|
|
|
|
- Agent list: Home plus remembered explicit folders, each with state.
|
|
- Folder input: requires an absolute path. Adding it invokes `select_agent`;
|
|
bridge canonicalization remains authoritative.
|
|
- Session controls: current session metadata, retry/restart, and agent health.
|
|
- Pi controls: available models, current model, thinking level, and queue modes
|
|
are read from Pi and changed only through Pi proxy operations. No independent
|
|
bridge defaults or persistence are allowed.
|
|
|
|
## Bridge/API contract
|
|
|
|
The panel speaks only through `pi-status-bridge-client` over the owner-only
|
|
Unix socket. Required operations are:
|
|
|
|
| Purpose | Operation |
|
|
| --- | --- |
|
|
| agents | `list_agents`, `select_agent` |
|
|
| live state | `get_state`, `subscribe` |
|
|
| history | `get_transcript` |
|
|
| composer | `submit_prompt` |
|
|
| recovery | `retry`, `restart` |
|
|
| Pi controls | `get_available_models`, `set_model`, `set_thinking_level` |
|
|
| suggestions | `get_commands` |
|
|
| extension UI | `extension_response` |
|
|
|
|
`submit_prompt` is the only default composer operation. The bridge dispatches
|
|
it to Pi `prompt` when idle and Pi `follow_up` while streaming; Pi retains
|
|
queue semantics. Direct `steer` and `follow_up` may exist only as explicit
|
|
advanced/TUI-parity shortcuts after their exact behavior is verified; they are
|
|
not ordinary UI buttons.
|
|
|
|
## State and persistence
|
|
|
|
- Bridge persists the Pi session reference per canonical worktree.
|
|
- Noctalia persists the remembered folder list and last selected agent in its
|
|
plugin data directory, not the plugin installation directory.
|
|
- The bridge starts Home; Noctalia never spawns Pi or owns a socket lock.
|
|
- Agent IDs are bridge-issued. The panel never invents or maps IDs to another
|
|
worktree.
|
|
|
|
## Safety invariants
|
|
|
|
- Never expose TCP.
|
|
- Never silently select a non-Home folder.
|
|
- Never auto-approve extension/tool requests.
|
|
- Never replace Pi model, thinking, or queue policy with panel defaults.
|
|
- Never treat unsupported custom extension UI as approval.
|
|
- Never execute an arbitrary folder path through an unquoted shell command.
|
|
|
|
## Acceptance scenarios
|
|
|
|
- **Home startup:** After user login, Home appears as a ready/working agent
|
|
without opening the panel.
|
|
- **Folder add:** Entering an absolute folder in Settings creates/selects its
|
|
distinct agent; Home transcript and prompts remain isolated.
|
|
- **Normal prompt:** Submitting the one composer while idle sends one Pi prompt.
|
|
- **Busy prompt:** Submitting while Pi is active follows Pi's follow-up queue
|
|
behavior without an extra panel decision.
|
|
- **History:** Reopening Output replays existing transcript, then receives live
|
|
updates without duplicate cursor entries.
|
|
- **Command suggestion:** Typing `/` presents `get_commands` results; selection
|
|
inserts, not executes, a command.
|
|
- **Extension safety:** Confirm/select/input/editor responses preserve request
|
|
IDs and values; custom UI shows unsupported.
|
|
- **Recovery:** Failed-recovery state is visible with explicit retry/restart.
|
|
|
|
## Verification
|
|
|
|
```sh
|
|
npm run check && npm test
|
|
/usr/bin/noctalia plugins lint ~/.local/share/noctalia/plugins/pi-status-bridge
|
|
/usr/bin/noctalia config validate
|
|
```
|
|
|
|
Manual verify: open the panel, select Home, add a folder from Settings, submit a
|
|
prompt, close/reopen the panel, and confirm history plus status remain correct.
|