diff --git a/docs/cockpit/2026-04-01-msp-assistant-harness-plan-claude.md b/docs/cockpit/2026-04-01-msp-assistant-harness-plan-claude.md index 821fe5c7..101191ed 100644 --- a/docs/cockpit/2026-04-01-msp-assistant-harness-plan-claude.md +++ b/docs/cockpit/2026-04-01-msp-assistant-harness-plan-claude.md @@ -11,6 +11,17 @@ Reframe `/assistant` from a generic AI chat surface into a **live MSP triage coc The change is a UI and data layer reframe. The existing session, branching, PSA, and conclude architecture is preserved and extended, not rebuilt. +### Key Architectural Choices + +This plan explicitly chooses: + +- **`FlowPilot`** as the primary page/product label (not "Assistant Harness") +- **Backend triage + handoff contracts required in v1** — not deferred to a later phase +- **Desktop-first cockpit layout** with clean mobile degradation +- **Explicit persisted triage fields** on the session model, not purely derived/computed header state +- **Prompt-embedded structured extraction** (`[TRIAGE_UPDATE]` marker) as the primary AI triage path, with post-response model pass only as fallback +- **Sidebar visual demotion** — existing sidebar stays but is visually de-emphasized so the cockpit reads as an operations surface, not a chat app + --- ## What Phase 0 Resolved @@ -272,7 +283,7 @@ Thin handle bar between work zone and conversation log. On drag: update `workZon ### F7 — Compact `ConversationLog` rendering -Replace current full `` bubbles in the log zone with a compact list: `you: ...` / `fp: ...` prefix style, tighter line height, no avatars. `ChatMessage` can still be used for rich content (forks, suggested flows) in a compact variant. +Replace current full `` bubbles in the log zone with a compact list: `you: ...` / `fp: ...` prefix style, tighter line height, no avatars. `ChatMessage` can still be used for rich content (forks, suggested flows) in a compact variant. Individual messages should support click-to-expand for full rendering when the engineer needs to re-read a longer response or review a suggested flow. ### F8 — Redesigned `ConcludeSessionModal.tsx` @@ -283,7 +294,16 @@ On open: 4. Render output destination checkboxes: Post to CW note / Save to KB / Send client summary 5. Confirm → call resolve/escalate/pause with enriched request body including structured fields -### F9 — MSP-native language pass +### F9 — Sidebar visual demotion + +The existing `ChatSidebar` stays functionally unchanged but should be visually softened so the cockpit — not the session list — reads as the primary surface. Specific changes: + +- Reduce sidebar background contrast (use `bg-sidebar` or one step darker) +- Reduce sidebar header prominence (smaller label, no bold "Chat History" heading) +- Rename "Chat History" → "Case History" (part of language pass) +- Default sidebar to collapsed state on first cockpit load (existing collapse toggle + `localStorage`) + +### F10 — MSP-native language pass | Old | New | |-----|-----| @@ -295,14 +315,14 @@ On open: | "Chat history" (sidebar label) | "Case History" | | Compose placeholder | "Describe finding, paste log output, or ask FlowPilot..." | -### F10 — New API methods (`aiSessions.ts`) +### F11 — New API methods (`aiSessions.ts`) ```typescript updateTriage(sessionId: string, fields: Partial): Promise getHandoffDraft(sessionId: string): AsyncGenerator ``` -### F11 — New types (`types/ai-session.ts`) +### F12 — New types (`types/ai-session.ts`) ```typescript interface TriageMeta { @@ -333,6 +353,9 @@ interface QuestionItem { ## Phased Execution Order ### Phase 1 — Backend Foundation + +> Lock backend schema and API changes first so the cockpit can be built against stable session contracts. + 1. Write migration `071` — add 5 columns to `ai_sessions` 2. Run `alembic upgrade head`, verify columns 3. Update `AISession` model with new mapped columns @@ -368,18 +391,19 @@ interface QuestionItem { 25. Implement drag-resizable split with `localStorage` persistence 26. Compact `ConversationLog` rendering -### Phase 6 — Handoff Modal + Language Pass +### Phase 6 — Handoff Modal + Language Pass + Sidebar 27. Redesign `ConcludeSessionModal.tsx` — structured handoff form -28. MSP-native language pass across all assistant components -29. Update `` title +28. Sidebar visual demotion — background, label prominence, default-collapsed +29. MSP-native language pass across all assistant components +30. Update `` title ### Phase 7 — QA + Hardening -30. `npx tsc -b` — fix any TypeScript errors -31. `npm run build` — production build clean -32. Functional regression: all chat flows, session switching, conclude/resume -33. Harness feel test: cockpit within 3 seconds? -34. Mobile viewport check -35. Stress test: 50+ messages, 10+ steps, long outputs +31. `npx tsc -b` — fix any TypeScript errors +32. `npm run build` — production build clean +33. Functional regression: all chat flows, session switching, conclude/resume +34. Harness feel test: cockpit within 3 seconds? +35. Mobile viewport check +36. Stress test: 50+ messages, 10+ steps, long outputs --- @@ -450,6 +474,18 @@ curl -X POST http://localhost:8000/ai-sessions/{id}/handoff-draft \ --- +## Assumptions + +- Desktop is the primary target; mobile must remain usable but does not drive the layout. +- `/assistant` remains the chat-session cockpit; `/pilot` is out of scope. +- New triage fields are **additive** — they do not replace `problem_summary`, `problem_domain`, `ticket_data`, or `conversation_messages`. +- `issue_category` is the operator-facing display field; `problem_domain` remains the internal classifier. Both coexist. +- `evidence_items` is editable by both AI and engineer; engineer edits persist through the triage PATCH endpoint. +- PSA context is optional — every triage header field must degrade gracefully when PSA is absent or session is free-text-only. +- The existing `TaskLane.tsx` component remains in the codebase — `StepsPanel` is a new component that consumes the same props with different rendering. No risky renames during this work. + +--- + ## Critical Files | File | Change |