pi-gui/docs/quick-pane-v1-design.md

Quick Pane v1 Design

Goal

Quick Pane is a small native window opened by a desktop/window-manager hotkey. It keeps a lightweight chat for short requests and returns useful answers and offers an explicit manual full-session continuation when needed.

Scope

• Cold-launchable, independent Tauri window.
• Compact request input, quick-model picker, and workspace picker.
• Configured default workspace, quick model, follow-up model, supplemental prompt, and read-only tool-call guidance.
• Ephemeral Quick Pane UI state and best-effort runtime cleanup.
• Advisory read-only/no-subagent instructions, inline permission/clarification prompts, and explicit normal-session handoff.

Non-goals

• Persisted quick history.
• Named profiles.
• App-managed WM binding writes.
• Trusted prevention of mutable tools or direct edits.
• Trusted prevention of subagents.
• A memory-only Pi runtime; Pi may write temporary session data while running.

Invocation

Desktop/WM configuration owns the hotkey so it works while Pi GUI is absent. Settings displays and copies the required command; it does not register or modify system bindings.

The app creates or focuses a dedicated Quick Pane window. Esc and Close hide the window without clearing an idle runtime, draft, model catalog, or transcript. Reopening within three minutes preserves that chat. Focusing an idle chat after more than three minutes closes it and prepares a fresh runtime; active work is never renewed on this timer.

Request lifecycle

1. Pane chooses configured default workspace and quick model, with per-request overrides.
2. It starts an isolated Pi RPC runtime in the chosen workspace.
3. Immutable prompt text instructs short requests, read-only inspection, zero subagents, and configured tool-call budget. Current Pi RPC cannot trusted-enforce those instructions.
4. Supplemental user instructions append beneath those prompt guardrails. Pane maps each exact submitted raw prompt back to entered user text, so transcript rendering never parses delimiter-like text from instructions or requests. Unknown reflected messages with the Quick Pane advisory prefix are hidden.
5. Pane streams the full ordered user/assistant transcript, tool status, and inline extension requests. Follow-ups reuse the same runtime until explicit or stale renewal. Starting each follow-up clears only prior turn's handoff answer state; transcript messages remain visible.
6. After first completed assistant answer, it displays a prominent manual Continue in full session action. Escalation and runtime-error notices remain visible and also offer handoff. No answer triggers a full session automatically.

Chat reset and layout

Ctrl+N starts a new chat: it aborts active work when needed, closes the old runtime with retryable cleanup, clears draft/transcript and submitted-prompt mappings, then prepares a fresh runtime and model catalog. Automatic stale renewal performs the same idle-chat replacement while preserving the current draft.

Quick Pane opens at 640×240 with a 520×240 minimum. Frontend content measurement requests native growth up to 520px tall after transcript updates; beyond that cap, transcript and model results scroll inside pane while outer document and pane remain clipped.

Escalation

Mutations, subagents, multi-step work, and complex work preflight-escalate. The quick agent explains why. The user clicks Continue in full session to open a new normal session with:

• original request;
• transcript-derived current-chat context and escalation note or partial findings;
• selected workspace; and
• configured follow-up model.

No full session opens automatically.

Permissions and privacy

Quick Pane surfaces Pi extension select, confirm, input, and editor requests inline. User explicitly answers every prompt. Existing policy remains authoritative: ordinary workspace reads may be allowed, external-directory reads may ask, and sensitive paths may deny.

Quick Pane UI request, output, and transcript stay in memory only. Hiding the pane preserves an idle chat for up to three minutes. Ctrl+N, stale idle renewal, app teardown, or another explicit chat replacement clears in-memory chat state and requests best-effort quick-runtime cleanup. Pi may write temporary session data while the child runs. A deliberate handoff persists only in newly created normal-session history.

Failure handling

Settings-startup and model-catalog preparation errors render an inline Retry action. Retry completes failed-runtime cleanup before preparing a replacement; model selection and Send remain disabled until a valid runtime catalog is ready. Request/runtime failures offer Continue only when a valid request and handoff configuration exist. An empty catalog remains visible with model selection and Send disabled. No silent fallback model is used.

Settings validation

Settings reject invalid model, workspace, custom prompt, or tool-call limit. Failed save keeps previously stored configuration and marks invalid fields.

Acceptance

From cold or hot desktop state, Quick Pane starts an unlimited chat without a time-based abort. Automated component, bridge, persistence, and native tests cover behavior; a manual cold-launch/hotkey smoke test verifies desktop integration.