Add TerminalView component doc with reconnect behavior

This commit is contained in:
jester 2026-03-10 20:04:30 +00:00
parent 2587b7347c
commit 69f67d2fd3

View File

@ -0,0 +1,46 @@
# TerminalView Component
> Status: ✅ Operational
---
## Overview
The terminal console is implemented using:
- **xterm.js** — frontend terminal renderer
- **WebSocket transport** — connects portal to agent
- **PTY session** — managed by the agent via `creack/pty`
`TerminalView` owns the WebSocket lifecycle. `ServerConsole` owns policy and session gating.
The file panel does not interrupt the console lifecycle.
---
## Reconnect Behavior
The terminal automatically reconnects when the WebSocket closes unexpectedly.
Behavior:
- Reconnect delay: 15 seconds
- Backoff capped at 5 seconds
- Console session recreated automatically
The user no longer needs to refresh the page to regain console access after navigating away from the console tab or after a transient disconnect.
---
## Agent Side
- One PTY read loop per `{vmid, container_type}`
- PTY-backed WebSocket served at `/console/ws`
- Commands sent via `GET /console/command?cmd=<cmd>` to server stdin
---
## Constraints
- Portal never calls the agent directly — all traffic through API
- Console does not enforce real policy — agent enforces