67 lines
3.4 KiB
Markdown
67 lines
3.4 KiB
Markdown
# Quick Pane v1 Design
|
|
|
|
## Goal
|
|
|
|
Quick Pane is a small native window opened by a desktop/window-manager hotkey. It accepts one short request and returns either a useful answer or an explicit escalation within 60 seconds.
|
|
|
|
## 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, time limit, and read-only tool limit.
|
|
- 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 small Quick Pane window. `Esc` closes it and discards quick-only state.
|
|
|
|
## 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 one request, read-only inspection, zero subagents, configured wall-clock budget, and configured tool-call budget. Current Pi RPC cannot trusted-enforce those instructions; event-derived caps and cleanup are best effort.
|
|
4. Supplemental user instructions append beneath those prompt guardrails.
|
|
5. Pane streams answer, tool status, and inline extension requests.
|
|
6. On success it displays final answer. On a cap it preserves partial answer, explains the cap, and offers handoff.
|
|
|
|
## Escalation
|
|
|
|
Mutations, subagents, multi-step work, and likely-over-budget work preflight-escalate. The quick agent explains why. The user clicks **Continue in full session** to open a new normal session with:
|
|
|
|
- original request;
|
|
- 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. Closing pane removes them and triggers 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
|
|
|
|
Unavailable models, startup failures, and crashes render inline actionable errors: retry, pick another quick model, or open normal session. No silent fallback model is used.
|
|
|
|
## Settings validation
|
|
|
|
Settings reject invalid model, workspace, custom prompt, or numeric limit. Failed save keeps previously stored configuration and marks invalid fields.
|
|
|
|
## Acceptance
|
|
|
|
From cold or hot desktop state, the hotkey produces an answer or explicit escalation within 60 seconds. Automated component, bridge, persistence, and native tests cover behavior; a manual cold-launch/hotkey smoke test verifies desktop integration.
|