docs: add terminal API and user documentation

- 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
2026-05-24 12:48:36 +00:00
parent 0a8f1419a6
commit fc873e2d6b
4 changed files with 392 additions and 3 deletions
@@ -0,0 +1,134 @@
+# 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.