pi-gui/specs/FULL_PI_PANEL_SPEC.md

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

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.