# Terminal API

The Terminal API provides WebSocket-based terminal access to running tool instances.

## WebSocket Endpoint

### Connect to Terminal

```
GET /ws/tool-instances/{instance_id}/terminal
```

Establishes a WebSocket connection to an interactive terminal session inside a running tool instance container.

**Authentication:** Requires valid session cookie.

**Path Parameters:**
- `instance_id` (string, UUID): The tool instance ID

**Connection Flow:**
1. Client connects to WebSocket endpoint
2. Server authenticates user and verifies instance ownership
3. Server creates or reattaches to existing terminal session
4. Server sends `{"type": "status", "status": "connected"}` message
5. Bidirectional communication begins

**Message Types:**

#### Client to Server

**Terminal Input (bytes or string)**
- Send raw bytes for terminal input (key presses)
- Send text for terminal input (will be encoded as UTF-8)

**Resize Command (JSON)**
```json
{
  "type": "resize",
  "cols": 80,
  "rows": 24
}
```

**Reset Command (JSON)**
```json
{
  "type": "reset"
}
```
Kills the current terminal session and starts a fresh one.

**Pong Response (JSON)**
```json
{
  "type": "pong"
}
```
Sent automatically in response to server ping messages.

#### Server to Client

**Terminal Output (bytes)**
Raw terminal output as binary data (Blob in browser).

**Status Messages (JSON)**
```json
{"type": "status", "status": "connected"}
{"type": "status", "status": "resetting"}
```

**Ping Messages (JSON)**
```json
{"type": "ping"}
```
Sent every 30 seconds to detect disconnections. Client should respond with `{"type": "pong"}`.

### Session Persistence

Terminal sessions persist across WebSocket disconnections:
- When a client disconnects, the terminal session remains active
- On reconnection, the client reattaches to the existing session
- Buffered output is replayed to the client on reconnection
- Sessions are cleaned up after 30 minutes of inactivity

### Concurrent Connections

Only one WebSocket connection is allowed per terminal session:
- New connections close existing connections with code 4000
- Previous client receives "New connection established" reason

## HTTP Endpoints

### Reset Terminal Session

```
POST /api/projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/terminal/reset
```

Resets the terminal session for a tool instance, killing the current shell and starting fresh.

**Authentication:** Required

**Path Parameters:**
- `project_id` (string, UUID): Project ID
- `repo_id` (string, UUID): Repository ID
- `instance_id` (string, UUID): Instance ID

**Response:**
```json
{
  "status": "success",
  "message": "Terminal session reset successfully",
  "instance_id": "...",
  "session_id": "..."
}
```

**Error Responses:**
- `404 Not Found`: Instance not found
- `400 Bad Request`: Instance is not running
- `500 Internal Server Error`: Failed to reset terminal session

## Error Codes

WebSocket close codes:
- `1000`: Normal closure
- `4000`: Error/reset
- `4001`: Invalid instance ID
- `4003`: Unauthorized/Forbidden
- `4004`: Instance not found or not running

## Heartbeat

The server sends ping messages every 30 seconds. If no ping is received for 60 seconds, the client should assume the connection is dead and reconnect.