docs: add MSP assistant harness cockpit design spec
Design spec for evolving /assistant into a live triage cockpit. Covers layout decisions (stacked zones, drag-resizable split), incident header (labelled fields, AI-inferred + editable), work zone (steps checklist + FlowPilot Asks + What We Know), conclude modal redesign, and all required backend changes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
chihlasm
363
docs/cockpit/2026-04-01-msp-assistant-harness-design.md
Normal file
363
docs/cockpit/2026-04-01-msp-assistant-harness-design.md
Normal file
@@ -0,0 +1,363 @@
|
|||||||
|
# MSP Assistant Harness — Design Spec
|
||||||
|
**Date:** 2026-04-01
|
||||||
|
**Status:** Draft — pending user review
|
||||||
|
**Source:** MSP_Assistant_Harness_Implementation_Plan.docx (v2.0, March 2026) + brainstorming session
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
The `/assistant` page currently works as a generic AI chat surface with a task lane side panel and a chat sidebar for session history. It functions well but reads as "AI chat with extras" rather than an MSP engineer's operational tool.
|
||||||
|
|
||||||
|
The goal is to reframe the page as a **live triage cockpit** — the place where an engineer opens a ticket, works through it from intake to resolution, and closes with a structured handoff artifact. The underlying session, branching, and chat architecture is preserved. What changes is layout hierarchy, information density, field labelling, and the conclude output.
|
||||||
|
|
||||||
|
Scope is broader than the original docx: includes all required backend changes to support the frontend properly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Design Decisions
|
||||||
|
|
||||||
|
### 1. Overall Layout — Stacked Zones
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ Incident Header (labelled fields, 1 row) │
|
||||||
|
├────────────────────────┬────────────────────┤
|
||||||
|
│ │ FlowPilot Asks │
|
||||||
|
│ Steps Checklist │ (quick replies) │
|
||||||
|
│ (left, ~55%) ├────────────────────┤
|
||||||
|
│ │ What We Know │
|
||||||
|
│ │ (evidence list) │
|
||||||
|
├────────────────────────┴────────────────────┤ ← drag handle
|
||||||
|
│ Conversation Log (muted, darker bg) │
|
||||||
|
├─────────────────────────────────────────────┤
|
||||||
|
│ Compose area │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
- Work zone (top) and conversation log (bottom) are **drag-resizable** via a handle
|
||||||
|
- Default split: ~55% work zone, ~45% chat
|
||||||
|
- Existing left sidebar (session history) unchanged
|
||||||
|
- Compose area is always pinned to bottom, spans full width
|
||||||
|
- `workZoneHeight` persisted to `localStorage` so split survives refresh
|
||||||
|
|
||||||
|
### 2. Incident Header
|
||||||
|
|
||||||
|
Single row with explicit micro-labels above each field:
|
||||||
|
|
||||||
|
```
|
||||||
|
CLIENT DEVICE CATEGORY HYPOTHESIS
|
||||||
|
Contoso Ltd ✏ jsmith-desktop ✏ DNS / Network ✏ Corrupted DNS cache on NIC ✏
|
||||||
|
[CW #48291] [Resolve ▾] [⋯]
|
||||||
|
```
|
||||||
|
|
||||||
|
- Each field has its own `✏` icon (visible on hover) that opens an inline edit popover
|
||||||
|
- Fields populate from: (a) intake form on session create, (b) AI-inferred updates mid-session via `triage_update`, (c) manual engineer edits via `PATCH /ai-sessions/{id}/triage`
|
||||||
|
- PSA ticket number shown if linked; action buttons (Resolve, overflow menu) on the right
|
||||||
|
- Empty fields show muted placeholder text — never blank
|
||||||
|
|
||||||
|
### 3. Work Zone — Steps + FlowPilot Asks + What We Know
|
||||||
|
|
||||||
|
**Left panel (~55%): ordered step checklist**
|
||||||
|
- Steps displayed as a vertical list: `✓` completed, `→` active (blue border, white text), `○` pending
|
||||||
|
- Active step is visually distinct
|
||||||
|
- "Generate Script" CTA appears at the bottom when a script-generation step is active
|
||||||
|
|
||||||
|
**Right panel (~45%): two stacked mini-panels**
|
||||||
|
- **FlowPilot Asks** (top, amber label): current question from AI. When `options` are provided, renders as quick-reply buttons — clicking a button submits that answer as a chat message. When no `options`, renders a compact free-text input. Panel is empty/hidden when no pending question.
|
||||||
|
- **What We Know** (bottom, muted label): running evidence list. Each entry: `✓ confirmed` / `✗ ruled out` / `? pending`. AI appends via `triage_update.evidence_items`; engineer can manually add or edit entries.
|
||||||
|
|
||||||
|
### 4. Conversation Log Zone
|
||||||
|
|
||||||
|
- Lives below the work zone, separated by a **drag handle**
|
||||||
|
- Background: `#13151c` (one step darker than page) — visually recedes
|
||||||
|
- Label: "CONVERSATION LOG" in muted colour (`text-muted`)
|
||||||
|
- Messages are compact: `you:` / `fp:` prefixes instead of full name/avatar bubbles
|
||||||
|
- Scrolls independently
|
||||||
|
- Not collapsible — drag handle gives control
|
||||||
|
|
||||||
|
### 5. Conclude / Handoff Modal (redesigned)
|
||||||
|
|
||||||
|
On opening "Close Case":
|
||||||
|
|
||||||
|
1. **Header**: "Close Case — [Client Name]" + outcome selector (Resolved / Escalated / Parked)
|
||||||
|
2. **Structured fields** — pre-filled by streaming `/handoff-draft`, all editable:
|
||||||
|
- **Root Cause** (short text input)
|
||||||
|
- **Resolution** (what fixed it)
|
||||||
|
- **Steps Taken** (list, auto-populated from step checklist)
|
||||||
|
- **Recommendations** (next steps / preventive actions)
|
||||||
|
3. **Output destinations** (checkboxes): Post to CW ticket note / Save to Knowledge Base / Send client summary
|
||||||
|
4. **Confirm** button — triggers resolve/escalate/pause and passes structured fields into `ResolutionOutputGenerator`
|
||||||
|
|
||||||
|
The existing `SessionResolutionOutput` model and `ResolutionOutputGenerator` service are reused. The `/handoff-draft` stream starts immediately on modal open — the engineer can begin editing while fields fill in.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Backend Changes Required
|
||||||
|
|
||||||
|
### 1. New AISession columns (Alembic migration)
|
||||||
|
|
||||||
|
Add to `ai_sessions` table:
|
||||||
|
|
||||||
|
| Column | Type | Purpose |
|
||||||
|
|--------|------|---------|
|
||||||
|
| `client_name` | `VARCHAR(255)` | MSP client name for incident header |
|
||||||
|
| `asset_name` | `VARCHAR(255)` | Device / asset / user being worked on |
|
||||||
|
| `issue_category` | `VARCHAR(100)` | Human-readable category (e.g. "DNS / Networking") |
|
||||||
|
| `triage_hypothesis` | `TEXT` | Current working hypothesis — AI-updated + engineer-editable |
|
||||||
|
| `evidence_items` | `JSONB` | "What We Know" list — persisted for session resume |
|
||||||
|
|
||||||
|
`evidence_items` format: `[{ "text": str, "status": "confirmed" | "ruled_out" | "pending" }]`
|
||||||
|
|
||||||
|
Note: `problem_domain` (existing) is an internal classifier slug. `issue_category` is the human-readable display label for the header. Both coexist.
|
||||||
|
|
||||||
|
### 2. New PATCH endpoint — triage metadata
|
||||||
|
|
||||||
|
```
|
||||||
|
PATCH /ai-sessions/{session_id}/triage
|
||||||
|
Auth: require_engineer_or_admin
|
||||||
|
Body: { client_name?, asset_name?, issue_category?, triage_hypothesis?, evidence_items? }
|
||||||
|
Response: { id, client_name, asset_name, issue_category, triage_hypothesis, evidence_items }
|
||||||
|
```
|
||||||
|
|
||||||
|
Used when the engineer edits any header field or evidence list manually.
|
||||||
|
|
||||||
|
### 3. Updated schemas — TriageUpdate and QuestionItem.options
|
||||||
|
|
||||||
|
**New `TriageUpdate` model** (returned in chat response when AI infers session context):
|
||||||
|
|
||||||
|
```python
|
||||||
|
class TriageUpdate(BaseModel):
|
||||||
|
client_name: str | None = None
|
||||||
|
asset_name: str | None = None
|
||||||
|
issue_category: str | None = None
|
||||||
|
triage_hypothesis: str | None = None
|
||||||
|
evidence_items: list[dict] | None = None # appends to existing list
|
||||||
|
```
|
||||||
|
|
||||||
|
**Updated `ChatMessageResponse`:**
|
||||||
|
```python
|
||||||
|
class ChatMessageResponse(BaseModel):
|
||||||
|
# existing fields unchanged...
|
||||||
|
triage_update: TriageUpdate | None = None
|
||||||
|
```
|
||||||
|
|
||||||
|
**Updated `QuestionItem`** — add `options` for quick-reply buttons:
|
||||||
|
```python
|
||||||
|
class QuestionItem(BaseModel):
|
||||||
|
text: str
|
||||||
|
context: str = ""
|
||||||
|
options: list[str] | None = None # quick-reply labels; null = free-text fallback
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. unified_chat_service.py — triage extraction
|
||||||
|
|
||||||
|
After generating each AI response, run a lightweight extraction to populate `triage_update`. Implementation options (pick one during implementation):
|
||||||
|
|
||||||
|
- **Option A (recommended):** Embed structured extraction in the system prompt using an `[TRIAGE_UPDATE]` marker, similar to existing `[QUESTIONS]` / `[ACTIONS]` markers. AI emits the block if it has new triage signals; service parses it.
|
||||||
|
- **Option B:** Post-response extraction pass using a fast model (`claude-haiku-4-5`) with the last 3 messages as context.
|
||||||
|
|
||||||
|
When `triage_update` contains non-null fields, the service auto-PATCHes the session record (so fields are persisted) AND returns `triage_update` in the response for the frontend to update the header immediately.
|
||||||
|
|
||||||
|
### 5. New streaming endpoint — handoff draft
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /ai-sessions/{session_id}/handoff-draft
|
||||||
|
Auth: require_engineer_or_admin
|
||||||
|
Response: StreamingResponse (text/event-stream)
|
||||||
|
```
|
||||||
|
|
||||||
|
Streams a structured handoff JSON object:
|
||||||
|
```json
|
||||||
|
{ "root_cause": "...", "resolution": "...", "steps_taken": ["..."], "recommendations": "..." }
|
||||||
|
```
|
||||||
|
|
||||||
|
Built from session context: `problem_summary`, `triage_hypothesis`, `evidence_items`, `conversation_messages` (last 20), step checklist from saved task lane state.
|
||||||
|
|
||||||
|
### 6. Updated conclude schemas
|
||||||
|
|
||||||
|
Add optional structured fields to `ResolveSessionRequest` and `EscalateSessionRequest`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
root_cause: str | None = None
|
||||||
|
steps_taken: list[str] | None = None
|
||||||
|
recommendations: str | None = None
|
||||||
|
```
|
||||||
|
|
||||||
|
Pass these into `ResolutionOutputGenerator._build_session_context()` to enrich `psa_ticket_notes` and `client_summary` outputs.
|
||||||
|
|
||||||
|
### 7. Session read endpoint — include new triage fields
|
||||||
|
|
||||||
|
Ensure the session detail response (`GET /ai-sessions/{id}`) returns the new fields so the frontend can restore header state on session resume.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Frontend Changes Required
|
||||||
|
|
||||||
|
### 1. AssistantChatPage layout refactor
|
||||||
|
|
||||||
|
Replace current layout (sidebar + chat column + TaskLane side panel) with the stacked cockpit layout described above.
|
||||||
|
|
||||||
|
**New state:**
|
||||||
|
- `triageMeta: TriageMeta` — `{ client_name, asset_name, issue_category, triage_hypothesis, evidence_items }`
|
||||||
|
- `workZoneHeight: number` — persisted to `localStorage('rf-assistant-work-zone-height')`
|
||||||
|
|
||||||
|
**On session load / resume:** populate `triageMeta` from the session response (new fields).
|
||||||
|
|
||||||
|
**On AI response:** if `response.triage_update` is non-null, merge into `triageMeta` (partial update, preserve existing non-null values unless AI overwrites).
|
||||||
|
|
||||||
|
### 2. New component: `IncidentHeader`
|
||||||
|
|
||||||
|
```
|
||||||
|
frontend/src/components/assistant/IncidentHeader.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
Props: `triageMeta`, `psaTicketId`, `sessionId`, `onFieldSave(field, value)`, `onResolve`, `onOverflow`
|
||||||
|
|
||||||
|
- Renders labelled single-row header
|
||||||
|
- Each field: micro-label + value + `✏` icon (visible on hover)
|
||||||
|
- `✏` opens an `EditPopover` (small popover with text input + Save/Cancel)
|
||||||
|
- On Save: calls `aiSessionsApi.updateTriage(sessionId, { [field]: value })`
|
||||||
|
- Empty field shows muted placeholder (e.g. "Unknown client")
|
||||||
|
|
||||||
|
### 3. Refactored component: `StepsPanel` (from TaskLane)
|
||||||
|
|
||||||
|
```
|
||||||
|
frontend/src/components/assistant/StepsPanel.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
Same `activeActions` data source. Renders as ordered checklist:
|
||||||
|
- Completed: `✓` + strikethrough label, muted
|
||||||
|
- Active: `→` + blue left border, white text, full opacity
|
||||||
|
- Pending: `○` + muted text
|
||||||
|
|
||||||
|
Script generation CTA: shown at bottom when the active step has `command` containing "script" or when AI has flagged it.
|
||||||
|
|
||||||
|
### 4. New component: `FlowPilotAsks`
|
||||||
|
|
||||||
|
```
|
||||||
|
frontend/src/components/assistant/FlowPilotAsks.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
Props: `questions: QuestionItem[]`, `onAnswer(answer: string)`
|
||||||
|
|
||||||
|
- Shows first unanswered question (or empty/hidden state if none)
|
||||||
|
- When `question.options` is non-null: renders as button row, clicking calls `onAnswer(option)`
|
||||||
|
- When `question.options` is null: renders compact text input with Send button
|
||||||
|
- `onAnswer` calls `handleSend` in the parent page with the answer text
|
||||||
|
|
||||||
|
### 5. New component: `WhatWeKnow`
|
||||||
|
|
||||||
|
```
|
||||||
|
frontend/src/components/assistant/WhatWeKnow.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
Props: `items: EvidenceItem[]`, `onAdd(text, status)`, `onEdit(index, text, status)`
|
||||||
|
|
||||||
|
- Renders evidence list with status icons: `✓` (confirmed, green), `✗` (ruled out, red), `?` (pending, muted)
|
||||||
|
- "+ Add finding" link at bottom opens an inline input row
|
||||||
|
- Items are editable inline (click to edit)
|
||||||
|
- State lives in `AssistantChatPage` as part of `triageMeta.evidence_items`, synced to backend via `PATCH /triage`
|
||||||
|
|
||||||
|
### 6. Drag handle — resizable split
|
||||||
|
|
||||||
|
Implement as a thin handle bar between work zone and conversation log. On drag:
|
||||||
|
- Update `workZoneHeight` in state
|
||||||
|
- Persist to `localStorage`
|
||||||
|
|
||||||
|
On mount: restore from `localStorage`, default to `55%` of available height.
|
||||||
|
|
||||||
|
### 7. Compact conversation log
|
||||||
|
|
||||||
|
Replace current `<ChatMessage>` bubble rendering in the log zone with a compact list:
|
||||||
|
|
||||||
|
```
|
||||||
|
you: Can't resolve external DNS, internal fine
|
||||||
|
fp: Ping passed — layer 3 OK. Run nslookup google.com.
|
||||||
|
you: Timed out on 1.1.1.1 too.
|
||||||
|
```
|
||||||
|
|
||||||
|
`ChatMessage` component still used for rich rendering (suggested flows, forks) but in a more compact variant. Full bubble rendering available on hover/expand if needed.
|
||||||
|
|
||||||
|
### 8. Redesigned `ConcludeSessionModal`
|
||||||
|
|
||||||
|
Replaces current simple textarea with the structured handoff form. On open:
|
||||||
|
1. Call `aiSessionsApi.getHandoffDraft(sessionId)` — streaming — populate fields as stream arrives
|
||||||
|
2. Render outcome selector + 4 structured fields (all `<textarea>` with labels)
|
||||||
|
3. Render output destination checkboxes
|
||||||
|
4. On Confirm: call resolve/escalate/pause with enriched request body
|
||||||
|
|
||||||
|
### 9. MSP-native language pass
|
||||||
|
|
||||||
|
| Old | New |
|
||||||
|
|-----|-----|
|
||||||
|
| "AI Assistant" | "FlowPilot" |
|
||||||
|
| "New Chat" | "New Case" |
|
||||||
|
| "Messages" | "Conversation Log" |
|
||||||
|
| "Task Lane" (panel header) | "Steps" |
|
||||||
|
| "Conclude" | "Close Case" |
|
||||||
|
| "Chat history" (sidebar label) | "Case History" |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What This Is NOT
|
||||||
|
|
||||||
|
- Not a redesign of the FlowPilot session page (`/pilot`) — separate page, untouched
|
||||||
|
- Not a rebuild of session, branching, or PSA architecture
|
||||||
|
- Not a new data model for conversations — `conversation_messages` JSONB is unchanged
|
||||||
|
- Not a mobile-first redesign — mobile degrades cleanly but desktop is primary
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
### Harness Feel Test (primary — subjective)
|
||||||
|
- Open `/assistant`, start a new case: does the page read as an MSP triage cockpit within 3 seconds without reading labels?
|
||||||
|
- Is the current active step obvious without scrolling through chat?
|
||||||
|
- Do FlowPilot Asks quick-reply buttons submit answers and update the steps list?
|
||||||
|
- Does the incident header update mid-session as the AI infers context?
|
||||||
|
- Drag the handle, refresh: does the split restore correctly?
|
||||||
|
|
||||||
|
### Functional Regression
|
||||||
|
- Free-text chat, image paste, suggested flows, forks, branching: all work
|
||||||
|
- Session pause, resume, and handoff end-to-end: works
|
||||||
|
- ConcludeSessionModal resolves / escalates / parks correctly
|
||||||
|
- Handoff draft streams and pre-fills the modal fields
|
||||||
|
- Manual header edit saves and persists across reload
|
||||||
|
|
||||||
|
### MSP Scenario Coverage (from docx)
|
||||||
|
Run end-to-end: single-user endpoint issue · M365/tenant-wide issue · network/VPN outage · escalation and resume after handoff.
|
||||||
|
|
||||||
|
### Backend Checks
|
||||||
|
```bash
|
||||||
|
# Migration
|
||||||
|
alembic upgrade head
|
||||||
|
|
||||||
|
# Verify new columns
|
||||||
|
psql -U postgres -d resolutionflow -c "\d ai_sessions" | grep -E "client_name|asset_name|issue_category|triage_hypothesis|evidence_items"
|
||||||
|
|
||||||
|
# Smoke test endpoints (with valid token)
|
||||||
|
curl -X PATCH .../ai-sessions/{id}/triage -d '{"client_name":"Test"}'
|
||||||
|
curl -X POST .../ai-sessions/{id}/handoff-draft # should stream JSON
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Critical Files
|
||||||
|
|
||||||
|
| File | Change |
|
||||||
|
|------|--------|
|
||||||
|
| `backend/app/models/ai_session.py` | Add 5 new columns |
|
||||||
|
| `backend/app/schemas/ai_session.py` | Add `TriageUpdate`, extend `QuestionItem`, update request/response schemas |
|
||||||
|
| `backend/app/api/endpoints/ai_sessions.py` | Add `PATCH /{id}/triage`, `POST /{id}/handoff-draft` |
|
||||||
|
| `backend/app/services/unified_chat_service.py` | Extract and return `triage_update` per AI response |
|
||||||
|
| `backend/app/services/resolution_output_generator.py` | Accept structured handoff fields in context builder |
|
||||||
|
| `backend/alembic/versions/NNN_add_triage_fields_to_ai_sessions.py` | Sequential migration (check `ls backend/alembic/versions/ \| sort \| tail -1` for NNN) |
|
||||||
|
| `frontend/src/pages/AssistantChatPage.tsx` | Full layout refactor — cockpit structure |
|
||||||
|
| `frontend/src/components/assistant/IncidentHeader.tsx` | New component |
|
||||||
|
| `frontend/src/components/assistant/StepsPanel.tsx` | Refactored from `TaskLane` |
|
||||||
|
| `frontend/src/components/assistant/FlowPilotAsks.tsx` | New component |
|
||||||
|
| `frontend/src/components/assistant/WhatWeKnow.tsx` | New component |
|
||||||
|
| `frontend/src/components/assistant/ConcludeSessionModal.tsx` | Redesigned |
|
||||||
|
| `frontend/src/api/aiSessions.ts` | Add `updateTriage()`, `getHandoffDraft()` |
|
||||||
|
| `frontend/src/types/ai-session.ts` | Add `TriageUpdate`, `TriageMeta`, `EvidenceItem`; extend `QuestionItem` |
|
||||||
Reference in New Issue
Block a user