# Tool Terminal

## Problem

Tool instances (code-server, jupyter-notebook, etc.) run in Docker containers but users have no way to access a shell inside those containers. This limits debugging, running ad-hoc commands, and managing the container environment.

## Solution

Provide browser-based terminal access to running tool containers via WebSocket:

1. **WebSocket terminal sessions** - Real-time bidirectional communication
2. **Pseudo-TTY** - Full terminal emulation with proper shell behavior
3. **xterm.js frontend** - Professional terminal UI in the browser
4. **Session management** - Multiple independent terminals per instance
5. **Access control** - Only instance owners can access terminals

## Key Features

### Terminal Access
- Open terminal from any running tool instance
- Full bash/zsh shell inside the container
- Standard terminal features (colors, cursor, history, etc.)

### Real-time I/O
- Instant character-by-character streaming
- Stdout/stderr combined output
- Support for interactive programs (vim, nano, etc.)

### Terminal Resize
- Dynamic column/row adjustment
- Window resize handled gracefully
- Proper text wrapping and scrolling

### Session Management
- Multiple terminals per instance
- Independent sessions with isolation
- Cleanup on disconnect

## Benefits

- **Debug containers** - Inspect running processes, check logs
- **Run commands** - Execute ad-hoc scripts or tools
- **Manage environment** - Install packages, edit config files
- **No SSH needed** - Browser-based access from anywhere

## Success Criteria

- [ ] Terminal opens for any running instance
- [ ] Commands execute and display output in real-time
- [ ] Terminal resizes with browser window
- [ ] Multiple terminals work independently
- [ ] Sessions clean up on disconnect
- [ ] Unauthorized users cannot access terminals