PSA/ee/docs/plans/2026-01-05-spotlight-quick-ask/PRD.md

# Spotlight Quick Ask Overlay (AI Chat)

## Summary
Add a **Spotlight-style “Quick Ask” overlay** that opens centered over the app and lets users ask a question fast. When an answer begins returning, the UI **expands into a chat-style dialog** with the response streaming in. The user can then optionally **move the in-progress chat into the existing chat sidebar** (right sidebar), continuing with the normal chat UI.

Quick Ask and the sidebar chat are **the same underlying chat session** (same persistence, same chat id, same messages). The difference is primarily UX: Quick Ask is optimized for “one quick question”, while the sidebar is optimized for extended interaction.

## Problem Statement
Today, AI chat lives in the right sidebar and requires a more deliberate UI mode switch. Users often want to ask a fast question without opening/committing to the sidebar. We need a lightweight, global entry point that feels like macOS Spotlight: a focused input that can quickly expand to show results.

## Goals
- A global keyboard shortcut opens a centered overlay:
  - macOS: `⌘` + `↑` (hardcoded initially)
  - Windows/Linux: `Ctrl` + `↑` (hardcoded initially)
- Quick Ask starts as a minimal input UI; upon sending a prompt and receiving the first response bytes/chunks, it transitions to an expanded dialog showing:
  - user prompt
  - assistant response streaming in (token/chunk streaming supported)
  - follow-up prompts supported (multi-turn)
- Quick Ask shares as much logic as possible with the existing sidebar chat:
  - message persistence (create chat + save messages)
  - request/response handling (including “function proposed” / approval flows if enabled)
  - stop/cancel
  - error handling
- In “expanded dialog” state, provide an action to **move/open the chat in the right sidebar**:
  - The right sidebar should open and display the same session seamlessly.
  - Quick Ask should close (or optionally remain open in minimized state; see Open Questions).
- Messages asked via Quick Ask must persist exactly as messages asked via the sidebar chat do today.

## Non-Goals
- A configurable shortcut UI (future enhancement; we will hardcode initially).
- A full “command palette” that searches app entities (assets/tickets/etc).
- A chat history list UI (the current sidebar chat does not expose prior chats).
- New analytics/telemetry, observability, or rollout flags beyond existing AI gating (unless requested).

## Users / Personas
- **Technician**: wants a fast answer while working in tickets/projects without changing context.
- **Dispatcher/Coordinator**: uses quick prompts for “how do I…” and procedural guidance.
- **Admin**: may use AI to understand settings/integrations quickly.

## Primary User Flows
### Flow A: Quick One-Off Answer
1. User presses `⌘↑` / `Ctrl↑`.
2. Overlay opens centered and focuses the input.
3. User types question and hits `Enter`.
4. Overlay expands; assistant response streams in.
5. User hits `Esc` to close overlay.

### Flow B: Follow-Ups in Overlay
1. User opens overlay and asks question.
2. While response is shown, user asks a follow-up in the same overlay.
3. Chat continues as a single persisted chat session.

### Flow C: Move to Sidebar
1. User opens overlay, asks question, sees response.
2. User clicks “Open in sidebar”.
3. Right sidebar opens showing the same session.
4. User continues in the normal sidebar chat UI.

## UX / UI Notes
### Overlay look & feel (“Spotlight style”)
- Centered on screen horizontally + vertically.
- Rounded container, subtle border/shadow; darkened translucent backdrop.
- Collapsed state:
  - single prominent input (optionally with “Ask Alga…” placeholder)
  - small hint row (e.g., `Esc` to close, `Enter` to ask)
- Expanded dialog state:
  - input remains available at bottom for follow-ups
  - transcript area above (user + assistant)
  - streaming indicator while generating
  - “Open in sidebar” control (only in expanded state)
- Accessibility:
  - focus trap while open
  - `Esc` closes
  - reasonable ARIA labeling via existing `Dialog` component patterns

### Transition (“seamless switch”)
- Use a single Dialog container; animate height/width between collapsed and expanded states.
- Expansion should trigger when:
  - user submits a prompt, and
  - the response begins (first SSE chunk / first tokens received), OR
  - immediately after submit if non-streaming response is used.

### Keyboard behaviors
- Global shortcut toggles open/close when appropriate.
- Inside overlay:
  - `Enter` submits prompt (single-line mode).
  - `Shift+Enter` inserts a newline (multiline input supported).
  - `Esc` closes overlay.
- Shortcut should still work even when focus is inside a text input/textarea/contentEditable in the main app.
- If the right sidebar chat is already open, the shortcut should focus the sidebar chat (instead of opening Quick Ask).

## Technical Design Notes
### Current-State Notes (as observed in repo)
- Right sidebar is toggled in `server/src/components/layout/DefaultLayout.tsx` via `⌘/Ctrl + L`.
- EE sidebar chat uses `ee/server/src/components/layout/RightSidebarContent.tsx`, which renders `ee/server/src/components/chat/Chat.tsx`.
- Chat persistence is handled via server actions in `ee/server/src/lib/chat-actions/chatActions.tsx` (`createNewChatAction`, `addMessageToChatAction`, `updateMessageAction`).
- Chat requests are currently sent to `POST /api/chat/v1/completions` (delegates to `ee/server/src/services/chatCompletionsService.ts`).
- Streaming endpoints exist at `POST /api/chat/stream/*` (delegates to `ee/server/src/services/chatStreamService.ts`), and there is a client-side SSE parser in `ee/server/src/services/streaming.ts`.

### Proposed Architecture
#### 1) Extract shared chat “session” logic
Create a headless hook/service (EE-only) that encapsulates:
- conversation state (model messages + UI messages)
- `chatId` lifecycle (create on first send)
- persistence for user + assistant messages
- request execution (completions today; optional SSE streaming)
- abort/stop
- function proposal/approval flow state (if applicable)

This logic becomes the single source of truth for both:
- sidebar chat UI
- Quick Ask overlay UI

#### 2) Add an EE “Quick Ask Overlay” component
Implement `QuickAskOverlay` as an EE component that:
- is controlled from `DefaultLayout` (open state + close handler)
- uses the shared chat session hook for sending and rendering
- supports “collapsed” and “expanded” UI states
- exposes an “Open in sidebar” action to hand off the active session

In CE builds (or when AI is disabled), the overlay should either:
- do nothing on shortcut, or
- show a small “EE required / AI unavailable” message consistent with existing patterns (decision).

#### 3) Enable handoff (“Open in sidebar”)
Introduce a minimal shared state channel between overlay and sidebar:
- Option A (preferred): a `ChatSessionProvider` at layout/root that stores the active session and exposes:
  - `activeSessionId` / `activeSession`
  - `setActiveSession(...)`
  - `openInSidebar(sessionId)` helper
- Sidebar chat reads from this provider; if a session is active, it renders that session (instead of creating a new one).
- The overlay calls `openInSidebar()` and closes itself.

This avoids brittle prop drilling and ensures both UIs show the same in-memory stream while also persisting to the DB.

### Streaming vs non-streaming
- The Quick Ask overlay UI must support streamed updates.
- Implementation can start by:
  - using the existing `POST /api/chat/stream/...` SSE endpoint and progressively appending chunks, OR
  - extending the completions service to provide an SSE mode.
- Even if the backend currently emits a single SSE chunk, the UI should be built to handle true token streaming later without rewrites.

### Persistence requirements
- On first user message in a session:
  - create chat row (title defaults to first user message)
  - persist user message
- On assistant completion:
  - persist assistant message
- When using streaming:
  - persist assistant message once final (or update incrementally if/when supported by server actions; optional).

### Gating / Feature Availability
- The existing `AI-stuff` feature flag check in `ee/server/src/components/layout/RightSidebarContent.tsx` should be reused for Quick Ask.
- If AI is disabled, opening Quick Ask should present a clear disabled state and not call the API.

## Risks / Edge Cases
- Global shortcut conflicts with OS/browser navigation or app keybindings.
- Focus stealing: opening Quick Ask while typing in a form could be disruptive.
- Session handoff consistency: ensuring the sidebar renders the exact in-memory state (esp. during streaming) without duplicating sends.
- SSE parsing and abort behavior across browsers.

## Open Questions
1. Where should “chat history” live for revisiting past sessions (if not already present in the product)?

## Acceptance Criteria / Definition of Done
- Pressing `⌘↑` on macOS or `Ctrl↑` on Windows opens a centered Spotlight-like overlay with focused input.
- If the right sidebar chat is already open, pressing `⌘↑` / `Ctrl↑` focuses the sidebar chat instead of opening Quick Ask.
- Submitting a question causes the overlay to expand and display the assistant response streaming in.
- Messages asked in Quick Ask persist using the same storage path as the sidebar chat.
- Clicking “Open in sidebar” opens the right sidebar and shows the same session, allowing continued conversation.
- The right sidebar continues to work as before for starting a new chat; the new shared logic does not regress existing chat behavior.