headquarter/openspec/changes/archive/2026-05-19-tool-terminal/tasks.md

Tool Terminal - Tasks

Phase 1: Backend Setup

• Task 1.1: Install backend dependencies

  • Add asyncio-subprocess handling
  • Verify FastAPI WebSocket support

• 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

• 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

• 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

• 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

• Task 3.1: Install xterm.js
  • npm install xterm xterm-addon-fit xterm-addon-web-links
  • Add to package.json

Phase 4: Frontend Components

• 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

• 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

• Task 5.1: Add terminal route

  • Add /instances/:instanceId/terminal to router
  • Link from InstanceList component
  • Show terminal button for running instances

• 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

• 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

• Task 7.1: Backend tests

  • ruff check
  • mypy
  • pytest

• Task 7.2: Frontend tests

  • typecheck
  • lint
  • build

• Task 7.3: Manual testing

  • Open terminal for running instance
  • Execute commands
  • Test resize
  • Verify access control