alex
a919ff8611
- Add proposal, design, specs, and tasks for persistent terminal sessions - Support reconnection, output buffer replay, reset, and idle timeout Refs: persistent-terminal-sessions
71 lines
3.3 KiB
Markdown
71 lines
3.3 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Terminal sessions persist across reconnections
|
|
The system SHALL maintain a terminal session for a tool instance even when the WebSocket connection is closed. When a new WebSocket connection is established for the same instance, the system SHALL reattach to the existing terminal session instead of creating a new one.
|
|
|
|
#### Scenario: Reconnect to existing session
|
|
- **WHEN** a user disconnects from a terminal session
|
|
- **THEN** the underlying docker exec process continues running
|
|
- **AND** when the user reconnects to the same instance
|
|
- **THEN** they are attached to the same shell process
|
|
|
|
#### Scenario: New connection creates session
|
|
- **WHEN** a user connects to an instance with no existing terminal session
|
|
- **THEN** a new terminal session is created
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: Terminal session output buffer
|
|
The system SHALL maintain a circular buffer of recent terminal output (minimum 10KB) for each persistent session. When a WebSocket reconnects, the system SHALL replay the buffered output to bring the client up to date.
|
|
|
|
#### Scenario: Output replay on reconnect
|
|
- **WHEN** a user reconnects to an existing terminal session
|
|
- **THEN** the recent output buffer is sent to the WebSocket
|
|
- **AND** the user sees the terminal state as it was before disconnect
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: Terminal session reset
|
|
The system SHALL support resetting a terminal session. When a reset is requested, the system SHALL kill the existing docker exec process, clean up the session, and create a new one.
|
|
|
|
#### Scenario: Reset terminal session
|
|
- **WHEN** a user sends a reset command via WebSocket
|
|
- **THEN** the existing terminal session is terminated
|
|
- **AND** a new terminal session is created
|
|
- **AND** the user is connected to the fresh session
|
|
|
|
#### Scenario: Reset from API
|
|
- **WHEN** a user sends a POST request to reset a terminal session
|
|
- **THEN** the existing terminal session is terminated
|
|
- **AND** a new terminal session is created
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: Terminal session idle timeout
|
|
The system SHALL automatically clean up terminal sessions that have had no active WebSocket connections for 30 minutes. This prevents resource leaks from abandoned sessions.
|
|
|
|
#### Scenario: Idle session cleanup
|
|
- **WHEN** a terminal session has no WebSocket connections for 30 minutes
|
|
- **THEN** the session is terminated and cleaned up
|
|
|
|
#### Scenario: Active session not cleaned up
|
|
- **WHEN** a terminal session has an active WebSocket connection
|
|
- **THEN** it is not cleaned up regardless of duration
|
|
|
|
## MODIFIED Requirements
|
|
|
|
### Requirement: Terminal session creation
|
|
The system SHALL create a terminal session when a WebSocket connects to a tool instance. The session SHALL be associated with the instance and SHALL persist until explicitly reset, the instance stops, or an idle timeout occurs.
|
|
|
|
#### Scenario: Create persistent session
|
|
- **WHEN** a user connects to a running instance via WebSocket
|
|
- **THEN** if no session exists for that instance, a new session is created
|
|
- **AND** if a session already exists, the WebSocket is attached to it
|
|
- **AND** recent output is replayed
|
|
|
|
## REMOVED Requirements
|
|
|
|
### Requirement: Terminal session cleanup on disconnect
|
|
**Reason**: Sessions now persist across disconnections
|
|
**Migration**: Sessions are cleaned up on idle timeout or explicit reset instead
|