# Tool Terminal - Tasks

## Phase 1: Backend Setup

- [x] **Task 1.1**: Install backend dependencies
  - Add `asyncio-subprocess` handling
  - Verify FastAPI WebSocket support

- [x] **Task 1.2**: Create TerminalSession class
  - Create `src/services/terminal_session.py`
  - Manage docker exec subprocess
  - Stream I/O between WebSocket and PTY
  - Handle resize signals
  - Cleanup on disconnect

- [x] **Task 1.3**: Create TerminalManager
  - Create `src/services/terminal_manager.py`
  - Manage active sessions dictionary
  - Create/close session methods
  - Handle resize forwarding
  - Session cleanup on disconnect

## Phase 2: WebSocket Endpoint

- [x] **Task 2.1**: Create WebSocket endpoint
  - Add `GET /ws/tool-instances/{instance_id}/terminal`
  - Authenticate via session cookie
  - Verify instance ownership
  - Establish bidirectional WebSocket
  - Handle connection lifecycle

- [x] **Task 2.2**: Add WebSocket to main app
  - Register WebSocket router in `main.py`
  - Configure WebSocket middleware
  - Handle CORS for WebSocket connections

## Phase 3: Frontend Dependencies

- [x] **Task 3.1**: Install xterm.js
  - `npm install xterm xterm-addon-fit xterm-addon-web-links`
  - Add to package.json

## Phase 4: Frontend Components

- [x] **Task 4.1**: Create TerminalComponent
  - Create `components/terminal.tsx`
  - Initialize xterm.js terminal
  - Manage WebSocket connection
  - Handle terminal resize with xterm-addon-fit
  - Connection status indicator
  - Auto-reconnect on disconnect

- [x] **Task 4.2**: Create TerminalPage
  - Create `pages/terminal.tsx`
  - Full-page terminal layout
  - Instance name in header
  - Back button
  - Connection status badge

## Phase 5: Integration

- [x] **Task 5.1**: Add terminal route
  - Add `/instances/:instanceId/terminal` to router
  - Link from InstanceList component
  - Show terminal button for running instances

- [x] **Task 5.2**: Add terminal button to InstanceList
  - Add terminal icon button to running instances
  - Disable for stopped instances
  - Navigate to terminal page

## Phase 6: Styling

- [x] **Task 6.1**: Add terminal CSS
  - Dark terminal theme matching app
  - Full-height container
  - Proper padding and borders
  - Connection status colors

## Phase 7: Quality Gates

- [x] **Task 7.1**: Backend tests
  - ruff check
  - mypy
  - pytest

- [x] **Task 7.2**: Frontend tests
  - typecheck
  - lint
  - build

- [x] **Task 7.3**: Manual testing
  - Open terminal for running instance
  - Execute commands
  - Test resize
  - Verify access control