alex
fc873e2d6b
- Add docs/api/terminal.md with WebSocket protocol and reset endpoint - Add docs/features/terminal.md with user guide for persistent sessions - Add docs/features/terminal-troubleshooting.md with diagnostic steps - Mark tasks 8.1-8.3 complete Refs: persistent-terminal-sessions tasks 8.x
135 lines
3.2 KiB
Markdown
135 lines
3.2 KiB
Markdown
# 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.
|