resolutionflow/docs/superpowers/specs/2026-04-02-flowpilot-cockpit-side-by-side-design.md

FlowPilot / FlowPilot Cockpit Side-by-Side — Design Spec

Date: 2026-04-02 Status: Approved Prerequisite: Sub-project 1 (Feature Flag Frontend Infrastructure) — completed Branch: feat/cockpit-harness (PR #124)

---

Context

ResolutionFlow's AI chat assistant lives at /assistant. On the feat/cockpit-harness branch (PR #124), this page was reframed as a triage cockpit with IncidentHeader, StepsPanel, FlowPilotAsks, and WhatWeKnow panels. The production version on origin/main retains the classic chat layout with ChatMessage and TaskLane.

Rather than replacing one with the other, both views will coexist on separate routes so beta users can try both and provide feedback. Long-term, the cockpit becomes a premium feature gated by the flowpilot_cockpit feature flag.

---

Design

1. Pages & Routing

Two page components, two route groups, one shared session backend.

Route	Page Component	Source	Description
/assistant, /assistant/:sessionId	FlowPilotPage.tsx	Production AssistantChatPage from origin/main + backported improvements	Classic chat layout: sidebar, chat messages, TaskLane side panel
/cockpit, /cockpit/:sessionId	CockpitPage.tsx	Current AssistantChatPage from feat/cockpit-harness	Cockpit layout: IncidentHeader, StepsPanel, FlowPilotAsks, WhatWeKnow, conversation log

Session portability: Both pages use the same ai_sessions backend and aiSessionsApi calls. Navigating from /assistant/abc123 to /cockpit/abc123 loads the same session — the cockpit renders triage panels on top of the same data.

File changes:

• Rename current AssistantChatPage.tsx → CockpitPage.tsx
• Create new FlowPilotPage.tsx from origin/main version of AssistantChatPage with improvements cherry-picked (session-switch race condition guard, etc.)
• Update router.tsx: add /cockpit and /cockpit/:sessionId routes pointing to CockpitPage, update /assistant routes to point to FlowPilotPage
• Remove the now-unused AssistantChatPage.tsx import from router

2. View Toggle

A toggle in the page header lets users switch between FlowPilot and FlowPilot Cockpit mid-session.

• Location: Top bar area of both pages, next to existing action buttons (Resolve/Escalate)
• Visibility: Only appears when viewing an active session (not on empty/new session state) AND only if the user has the flowpilot_cockpit feature flag enabled
• Visual: Segmented control / pill toggle — FlowPilot | Cockpit — with the active view highlighted
• Behavior: Clicking the other segment navigates via react-router navigate(): e.g., /assistant/abc123 → /cockpit/abc123
• Performance: Navigation is instant — no data refetch needed since both pages load the same session by ID from the API on mount
• Component: ViewToggle.tsx — shared component imported by both pages

Edge case: If the user is on /cockpit/:sessionId but loses the flowpilot_cockpit feature flag (admin disables it), the cockpit page redirects to /assistant/:sessionId via a useEffect check.

3. Sidebar Navigation

New top-level rail icon for FlowPilot, with flyout showing both views.

• Rail icon: Sparkles with label "FlowPilot"
• Position: Second item in the rail, right after Home — this is the primary workflow entry point
• Flyout children:
  • "FlowPilot" → /assistant
  • "FlowPilot Cockpit" → /cockpit — only shown if useFeatureFlag('flowpilot_cockpit') returns true
• matchPaths: ['/assistant', '/cockpit'] — both routes highlight this rail icon
• Pinned sidebar sections: Add under the existing "RESOLVE" section with the same gating logic

4. Dashboard Integration

QuickStartPage lets the user choose which view new sessions launch into.

• Default behavior: StartSessionInput continues to launch to /assistant (FlowPilot)
• Cockpit launch option: If the user has the flowpilot_cockpit flag enabled, show a small toggle or dropdown near the submit button — "Open in: FlowPilot | Cockpit" — that controls whether the new session navigates to /assistant/:sessionId or /cockpit/:sessionId
• Preference persistence: Store the user's last choice in userPreferencesStore (persisted to localStorage) so it remembers their preferred launch target across sessions
• Dashboard session cards: ActiveFlowPilotSessions and RecentFlowPilotSessions — clicking a session navigates to the user's stored view preference

5. Shared Logic Extraction

Both pages share significant session management code. Extract into a shared hook to avoid duplication.

useAssistantSession hook (new file: frontend/src/hooks/useAssistantSession.ts):

• Session CRUD (create, load, select, delete)
• Chat message sending + response handling
• File upload handling (pendingUploads, drag-drop)
• Active questions/actions state management
• Branching integration (useBranching)
• Session-switch race condition guard (currentChatRef pattern)
• Conclude/resolve/escalate flows
• Prefill auto-submit logic

FlowPilotPage.tsx — imports useAssistantSession, renders the classic chat layout (ChatMessage, TaskLane sidebar panel)

CockpitPage.tsx — imports useAssistantSession, renders the cockpit layout (IncidentHeader, StepsPanel, FlowPilotAsks, WhatWeKnow, conversation log) plus manages cockpit-specific state (triage metadata, evidence items, drag-resizable split)

This keeps each page focused on layout/rendering (~200-400 lines each) while the ~600+ lines of shared session logic live in one place.

6. Backend Changes

Minimal backend work — most infrastructure already exists.

The triage columns (client_name, asset_name, issue_category, triage_hypothesis, evidence_items) are already on the ai_sessions table. What's needed:

• Verify existing endpoints: Confirm PATCH /ai-sessions/{id}/triage and the triage_update field in ChatMessageResponse are working. If not, implement per the cockpit design spec (docs/cockpit/2026-04-01-msp-assistant-harness-design.md)
• Handoff draft endpoint: POST /ai-sessions/{id}/handoff-draft (streaming) — needed for the cockpit's Conclude modal. Streams a structured JSON object with root_cause, resolution, steps_taken, recommendations
• No new migrations — triage columns already exist on this branch, flowpilot_cockpit flag seeded in migration 072
• No changes to the FlowPilot (chat) page's backend — it uses the same endpoints it always has

7. UI Naming

• Rename "AI Assistant" → "FlowPilot" throughout the UI (sidebar, page titles, breadcrumbs, dashboard)
• The cockpit view is labelled "FlowPilot Cockpit"
• Internal code: FlowPilotPage and CockpitPage

---

Scope Boundary

In scope:

• New FlowPilotPage.tsx (from production AssistantChatPage + backported improvements)
• Rename current AssistantChatPage.tsx to CockpitPage.tsx
• Extract shared session logic into useAssistantSession hook
• Routes: /assistant, /assistant/:sessionId, /cockpit, /cockpit/:sessionId
• ViewToggle component in both page headers (gated by feature flag)
• Sidebar rail entry with flyout (cockpit gated by feature flag)
• Dashboard StartSessionInput launch preference toggle
• Verify/complete triage backend endpoints (PATCH triage, handoff-draft streaming)
• Rename "AI Assistant" to "FlowPilot" in UI labels

Not in scope:

• Changes to the guided flow session page (/pilot) — stays as-is, hidden from sidebar
• New AI model routing or prompt changes
• PSA integration changes
• Real-time flag updates (reload is fine)
• Mobile-specific cockpit layout (responsive basics only)

---

Files Changed

File	Change
frontend/src/pages/AssistantChatPage.tsx	Rename to CockpitPage.tsx
frontend/src/pages/FlowPilotPage.tsx	New — classic chat layout from origin/main + improvements
frontend/src/pages/CockpitPage.tsx	Renamed from AssistantChatPage, refactored to use useAssistantSession
frontend/src/hooks/useAssistantSession.ts	New — shared session logic extracted from both pages
frontend/src/components/assistant/ViewToggle.tsx	New — segmented control for switching views
frontend/src/router.tsx	Add /cockpit routes, update /assistant routes to FlowPilotPage
frontend/src/components/layout/Sidebar.tsx	Add FlowPilot rail entry with cockpit flyout child
frontend/src/pages/QuickStartPage.tsx	Add launch preference toggle for cockpit
frontend/src/store/userPreferencesStore.ts	Add preferredFlowPilotView preference
backend/app/api/endpoints/ai_sessions.py	Verify/add PATCH triage endpoint + handoff-draft streaming endpoint
backend/app/schemas/ai_session.py	Verify/add TriageUpdate, options on QuestionItem
backend/app/services/unified_chat_service.py	Verify/add triage extraction in chat responses