feat: add persistent terminal sessions spec

- Add proposal, design, specs, and tasks for persistent terminal sessions - Support reconnection, output buffer replay, reset, and idle timeout Refs: persistent-terminal-sessions
2026-05-24 12:29:29 +00:00
parent 7cb88a3163
commit a919ff8611
5 changed files with 238 additions and 0 deletions
@@ -0,0 +1,70 @@
+## 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