391 lines
12 KiB
Markdown
391 lines
12 KiB
Markdown
# 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
|