# 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.