# 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 <name> <sdk-type> <base-url> [api-key]`
- `pnpm cli provider ls`
- `pnpm cli provider status <provider-id> <active|inactive>`
- `pnpm cli provider remove <provider-id>`
- `pnpm cli provider probe <provider-id>`

**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
