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
3.3 KiB
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