# Web Terminal Specification

## Purpose

Provide browser-based terminal access to running tool containers.

## Requirements

### Requirement: WebSocket Terminal

The system SHALL provide terminal sessions via WebSocket.

#### Scenario: Open terminal
- GIVEN a running tool instance
- WHEN the user opens the terminal
- THEN a WebSocket connection is established
- AND a shell is spawned in the container via `docker exec`

#### Scenario: Open terminal with startup command
- GIVEN a running tool instance with a tool type that has `startup_command` set
- WHEN the user opens the terminal
- THEN a WebSocket connection is established
- AND the startup command is executed before the interactive shell
- AND the shell is spawned in the container via `docker exec`

#### Scenario: Open terminal without startup command
- GIVEN a running tool instance with a tool type that has no `startup_command`
- WHEN the user opens the terminal
- THEN a WebSocket connection is established
- AND the shell spawns directly without any startup execution

### Requirement: Terminal I/O

The system SHALL stream terminal I/O via WebSocket.

#### Scenario: Command execution
- GIVEN an active terminal session
- WHEN the user types a command
- THEN stdin is forwarded to the container shell
- AND stdout/stderr is streamed back to the browser

### Requirement: Terminal Resize

The system SHALL support terminal resize events.

#### Scenario: Resize terminal
- GIVEN an active terminal session
- WHEN the browser window is resized
- THEN the terminal dimensions (COLS, ROWS) are updated
- AND the shell receives the new size

### Requirement: Session Management

The system SHALL manage terminal sessions.

#### Scenario: Multiple sessions
- GIVEN a running tool instance
- WHEN multiple terminals are opened
- THEN each has an independent session

#### Scenario: Cleanup
- GIVEN an active terminal session
- WHEN the user disconnects
- THEN the session is cleaned up
- AND the shell process is terminated

#### Scenario: Reset terminal session runs startup command
- GIVEN an active terminal session
- WHEN the user resets the session
- THEN a new shell is spawned
- AND the startup command executes before the new interactive shell

### Requirement: Access Control

The system SHALL restrict terminal access.

#### Scenario: Unauthorized access
- GIVEN a tool instance owned by user A
- WHEN user B tries to access the terminal
- THEN the connection is rejected with 403

## Dependencies

- tool-instances (running containers)
- auth-oauth (authentication)
- xterm.js frontend library
- ptyprocess for pseudo-TTY

## Quality Gates

- `pytest` must pass
- `mypy .` must pass
- `ruff check .` must pass
- `npm run typecheck` must pass
- `npm run lint` must pass