# Foundation TODO — Chat Session Implementation **Date:** April 29, 2026 (updated) **Goal:** Complete the User journey from Project Manager → Chat Session view with full prompt submission, streaming responses, and model selection. All functionality tested with E2E tests. --- ## Phase 1-5: Foundation Core ✅ COMPLETE All foundation work is complete and tested: - ✅ Type conflicts resolved (Phases 1.1-1.5) - ✅ Prompt submission flow implemented (Phases 2.1-2.4) - ✅ Event routing Drone→IDE implemented (Phases 3.1-3.5) - ✅ AWL emits streaming events (Phases 4.1-4.4) - ✅ Workspace persistence with crash recovery (Phases 5.1-5.7) **Unit Tests:** 21 tests passing (CodeSession + DroneSession) --- ## Phase 6: Chat Session Implementation (Current Turn) ### 6.1 AI Provider CLI Commands ⬜ PENDING **File:** `gadget-code/src/web-cli.ts` **Commands:** - `pnpm cli provider add [api-key]` - `pnpm cli provider ls` - `pnpm cli provider status ` - `pnpm cli provider remove ` - `pnpm cli provider probe ` **Implementation Details:** - SDK type: "ollama" or "openai" - `provider add` auto-probes for models - `provider probe` discovers models + capabilities, updates in-place - Model updates preserve `_id` (don't delete/recreate) - Mark unavailable models as "removed" instead of deleting **Acceptance Criteria:** - [ ] Can add Ollama provider (no API key required) - [ ] Can add OpenAI provider (API key required) - [ ] Probe discovers models and capabilities - [ ] List shows all providers with model counts - [ ] Status command enables/disables providers - [ ] Remove command deletes provider --- ### 6.2 Chat Session REST API ⬜ PENDING **Files to Create:** - `gadget-code/src/controllers/api/v1/chat-session.ts` - `gadget-code/src/services/chat-session.ts` **Endpoints:** - `GET /api/v1/chat-sessions?projectId=:projectId` - `POST /api/v1/chat-sessions` - `GET /api/v1/chat-sessions/:id` - `PUT /api/v1/chat-sessions/:id` - `DELETE /api/v1/chat-sessions/:id` - `GET /api/v1/chat-sessions/:id/turns` **Features:** - Auto-generate session name from first prompt - Support `/rename` slash command (handled in AWL) - Track provider + model selection per session **Acceptance Criteria:** - [ ] Create session with provider + model - [ ] List sessions by project - [ ] Update session (provider/model/mode) - [ ] Delete session - [ ] Get turns for session --- ### 6.3 Frontend API Client ⬜ PENDING **File:** `gadget-code/frontend/src/lib/api.ts` **Interfaces:** - `AiProvider` with models array - `AiModel` with capabilities - `ChatSession` with stats - `ChatTurn` with prompts/thinking/response/toolCalls **API Clients:** - `providerApi` (getAll, get) - `chatSessionApi` (getAll, get, create, update, delete, getTurns) **Acceptance Criteria:** - [ ] TypeScript interfaces match backend - [ ] API methods work with REST endpoints - [ ] Error handling for failed requests --- ### 6.4 Project Manager Integration ⬜ PENDING **File:** `gadget-code/frontend/src/pages/ProjectManager.tsx` **Components to Add:** - `DroneSelector` - shows available drones (filter: online, user-owned) - `ChatSessionList` - lists project's chat sessions - `NewChatSessionForm` - modal with provider/model/mode selection **UI Layout:** ``` +---------------------------+------------------------------------+ | [New Project] | Project Inspector | |---------------------------| | | Projects (2) | Name: project-one | | [project-one ●] | Slug: project-one | | [project-two ] | ... | | | | | | [Delete Project] | | +------------------------------------+ | | Available Drones | | | - drone-alpha ● [Select] | | | - drone-beta ○ | | +------------------------------------+ | | Chat Sessions | | | - Session 1 [Open] | | | - Session 2 [Open] | | | [New Chat Session] | +---------------------------+------------------------------------+ ``` **Flow:** 1. User selects project → loads details 2. Fetch available drones (status != 'offline', user-owned) 3. User selects drone → stores in state 4. Fetch chat sessions for project 5. "New Chat Session" → modal with provider/model/mode 6. Create session → navigate to `/projects/:projectId/chat-session/:sessionId` **Acceptance Criteria:** - [ ] Drone list shows online drones only - [ ] Can select drone for session - [ ] Chat session list displays - [ ] New session form with provider/model/mode - [ ] Navigate to chat session view --- ### 6.5 Chat Session View UI ⬜ PENDING **Files to Create:** - `gadget-code/frontend/src/pages/ChatSessionView.tsx` - `gadget-code/frontend/src/components/ChatMessages.tsx` - `gadget-code/frontend/src/components/PromptInput.tsx` - `gadget-code/frontend/src/components/SessionSidebar.tsx` - `gadget-code/frontend/src/components/FileBrowser.tsx` (stub) - `gadget-code/frontend/src/components/ToolCallInspector.tsx` - `gadget-code/frontend/src/components/SessionSettings.tsx` **Route:** `/projects/:projectId/chat-session/:sessionId` **Layout (per ui-design-guide.md):** ``` Work Area | Session Status ----------------------------------------------|--------------- Chat Messages | Chat: name | ID: ... | Model: llama3.2 (Ollama) [▼] | Mode: BUILD [▼] ----------------------------------------------|--------------- [Prompt input ][Expand][Send]| TC | FO | SA ----------------------------------------------|--------------- Log | Files | ``` **Chat Messages Display:** - User prompts clearly highlighted - Assistant responses as natural language flow - Thinking content (collapsible) - Tool calls: one-line summary in chat (name + success/fail) - Clickable tool calls open inspector panel - Auto-scroll to bottom - Loading indicator while processing **Tool Call Inspector (tabbed in Session panel):** - Tool name - Input parameters (expandable) - Response preview (if large) - Full response view - Success/fail status **Session Sidebar:** - Chat name (editable via cog/settings) - Session ID (truncated) - Model selector: "Model Name (Provider Name)" with dropdown - Mode selector (Plan/Build/Test/Ship/Dev) - Stats: TC (tool calls), FO (file ops), SA (subagents) - Cog icon → Session Settings modal **Session Settings Modal:** - Edit session name - View/change provider + model - View/change mode - View stats - Delete session **Socket Events:** ```typescript socket.on('thinking', (content: string) => { ... }) socket.on('response', (content: string) => { ... }) socket.on('toolCall', (callId: string, name: string, params: string, response: string) => { ... }) socket.on('workOrderComplete', (turnId: string, success: boolean, message?: string) => { ... }) ``` **Acceptance Criteria:** - [ ] Chat messages display user prompts + assistant responses - [ ] Thinking content collapsible - [ ] Tool calls show one-line summary in chat - [ ] Click tool call → opens inspector with full details - [ ] Prompt input with Send button - [ ] Session sidebar with model/mode selectors - [ ] Model dropdown groups by provider - [ ] Changing model updates ChatSession for next prompt - [ ] Session Settings modal (cog icon) - [ ] File browser stub --- ### 6.6 Model Selection in Session Sidebar ⬜ PENDING **Implementation:** 1. Click model dropdown in sidebar 2. Fetch all providers via `providerApi.getAll()` 3. Show grouped dropdown: ``` Ollama ├─ llama3.2 ├─ llama3.1 └─ mistral OpenAI ├─ gpt-4o └─ gpt-4-turbo ``` 4. User selects provider + model 5. Call `chatSessionApi.update(sessionId, { provider: providerId, selectedModel: modelId })` 6. Update UI to show new selection 7. **Next prompt** uses new settings (current turn unaffected) **Acceptance Criteria:** - [ ] Provider + model dropdown works - [ ] Selection updates ChatSession - [ ] Next prompt uses new model - [ ] UI reflects current selection --- ### 6.7 End-to-End Tests ⬜ PENDING **File:** `gadget-code/tests/e2e/chat-session.test.ts` **Test Strategy:** - Full mock of AI service (no external dependencies) - Mock returns deterministic responses for testing - Test positive and negative paths - Validate business logic, not AI behavior **Test Scenarios:** 1. **Complete Chat Session Flow:** - Sign in - Navigate to project - Select available drone - Create chat session with provider/model - Submit prompt - Verify user prompt appears in chat - Verify ChatTurn created in database - Verify mock response displayed 2. **Model Selection:** - Open chat session - Change provider/model in sidebar - Submit prompt - Verify new model used in ChatTurn 3. **Tool Call Display:** - Submit prompt that triggers tool calls (mocked) - Verify tool call summary in chat - Click tool call → inspector opens - Verify full details in inspector 4. **Session Settings:** - Open session settings (cog icon) - Change session name - Save → verify name updates - Change mode - Save → verify mode updates **Acceptance Criteria:** - [ ] All E2E tests pass - [ ] Tests use mocked AI service - [ ] Tests are deterministic and repeatable - [ ] No external API dependencies --- ### 6.8 Unit Tests ⬜ PENDING **Files to Create:** - `gadget-code/tests/cli-provider.test.ts` - CLI provider commands - `gadget-code/tests/chat-session-service.test.ts` - Service layer - `gadget-code/tests/chat-session-api.test.ts` - REST controller **Test Coverage:** - Provider CRUD operations - Model discovery and caching - Chat session CRUD - Model selection updates - Turn retrieval **Acceptance Criteria:** - [ ] All unit tests pass - [ ] Mock external dependencies - [ ] Test positive and negative paths --- ## Phase 7: Deferred Items ### 7.1 Error Handling & Concurrency ⬜ DEFERRED - Error propagation from drone - Concurrency control (reject multiple work orders) - Timeout & heartbeat mechanism **Rationale:** Can be added after basic flow is working and tested ### 7.2 Documentation Cleanup ⬜ DEFERRED - Remove Bull queue references from docs - Update AWL documentation - Document Socket.IO-only approach **Rationale:** Focus on implementation first, docs after validation --- ## Acceptance Criteria for This Turn By end of this turn, the User can: - [x] Load a Project in Project Manager - [ ] Select a registered gadget-drone instance (online, available) - [ ] Create a new Chat Session with provider + model selection - [ ] Enter the Chat Session view correctly configured - [ ] Submit a prompt for processing - [ ] See streaming responses (thinking, response, tool calls) - [ ] View tool call details in inspector - [ ] Change model/provider for next prompt - [ ] Edit session settings (name, mode) **Tests:** - [ ] Unit tests for CLI provider commands - [ ] Unit tests for Chat Session service + API - [ ] E2E test for complete flow (sign in → submit prompt) - [ ] All tests pass with mocked AI service (no external deps) --- ## Design Decisions 1. **AI Provider CLI:** All provider management via CLI (no admin UI) 2. **Model Discovery:** Probe on add, update in-place (preserve _id) 3. **Session Naming:** Auto-generate from first prompt 4. **Drone Filtering:** Show online drones only (filter offline) 5. **Test Strategy:** Full mock, deterministic, no external services 6. **Chat Display:** Natural language flow, tool calls as one-line summaries 7. **Tool Inspectors:** Tabbed panel in Session sidebar for details 8. **Model Selection:** Always available in Session sidebar, affects next prompt --- ## Notes - Follow existing code conventions - All code must include tests - Prefer more status/data, not less (observability) - Ask for help when stuck (no workarounds/shortcuts) - Commit frequently with descriptive messages - Keep this document updated as work progresses