Auto close sessions on IDLE timeouts

Author: CapulusCodeNinja

Directory.Build.props

@@ -36,7 +36,7 @@
   <PropertyGroup Label="Default Versioning">
     <!-- Default version for all projects (can be overridden per project) -->
     <VersionPrefix>1.1.0</VersionPrefix>
-        <VersionSuffix>61</VersionSuffix>
+        <VersionSuffix>62</VersionSuffix>
 
     <!-- Calculated version -->
     <Version Condition="'$(Version)' == ''">$(VersionPrefix).$(VersionSuffix)</Version>

README.md

@@ -224,7 +224,8 @@ MCP Nexus intelligently batches commands for improved throughput:
     "SessionManagement": {
       "MaxConcurrentSessions": 10,
       "SessionTimeoutMinutes": 30,
-      "DefaultCommandTimeoutSeconds": 300
+      "CleanupIntervalSeconds": 300,
+      "DefaultCommandTimeoutMinutes": 10
     }
   }
 }

nexus_config/Models/SharedConfiguration.cs

@@ -246,17 +246,17 @@ public class SessionManagementSettings
     public int SessionTimeoutMinutes { get; set; } = 30;
 
     /// <summary>
-    /// Gets or sets the cleanup interval in minutes.
+    /// Gets or sets the cleanup interval in seconds.
     /// </summary>
-    public int CleanupIntervalMinutes { get; set; } = 5;
+    public int CleanupIntervalSeconds { get; set; } = 5;
 
     /// <summary>
     /// Gets the cleanup interval as a TimeSpan.
     /// </summary>
     /// <returns>The cleanup interval.</returns>
     public TimeSpan GetCleanupInterval()
     {
-        return TimeSpan.FromMinutes(CleanupIntervalMinutes);
+        return TimeSpan.FromSeconds(CleanupIntervalSeconds);
     }
 
     /// <summary>

nexus_config/appsettings.json

@@ -37,8 +37,8 @@
     },
     "SessionManagement": {
       "MaxConcurrentSessions": 1000,
-      "SessionTimeoutMinutes": 30,
-      "CleanupIntervalMinutes": 5,
+      "SessionTimeoutMinutes": 10,
+      "CleanupIntervalSeconds": 30,
       "DisposalTimeoutSeconds": 30,
       "DefaultCommandTimeoutMinutes": 10,
       "MemoryCleanupThresholdMB": 1024

nexus_engine/nexus_engine/DebugEngine.cs

@@ -49,6 +49,11 @@ public class DebugEngine : IDebugEngine
     /// </summary>
     private readonly ConcurrentDictionary<string, DateTime> m_SessionCreationTimes = new();
 
+    /// <summary>
+    /// Periodic timer that checks for idle sessions and closes them when they exceed the configured timeout.
+    /// </summary>
+    private readonly System.Threading.Timer m_SessionCleanupTimer;
+
     /// <summary>
     /// Indicates whether this instance has been disposed.
     /// </summary>
@@ -81,6 +86,9 @@ internal DebugEngine(IFileSystem fileSystem, IProcessManager processManager)
 
         m_Logger = LogManager.GetCurrentClassLogger();
         m_Logger.Info("DebugEngine initialized with max {MaxSessions} concurrent sessions", Settings.Instance.Get().McpNexus.SessionManagement.MaxConcurrentSessions);
+
+        var cleanupInterval = Settings.Instance.Get().McpNexus.SessionManagement.GetCleanupInterval();
+        m_SessionCleanupTimer = new System.Threading.Timer(_ => CleanupIdleSessions(), null, cleanupInterval, cleanupInterval);
     }
 
     /// <summary>
@@ -159,9 +167,10 @@ public async Task<string> CreateSessionAsync(string dumpFilePath, string? symbol
     /// Closes a debug session and cleans up resources.
     /// </summary>
     /// <param name="sessionId">The session ID to close.</param>
+    /// <param name="closeReason">Optional reason for session closure (e.g., "IdleTimeout", "UserRequest").</param>
     /// <returns>A task that represents the asynchronous operation.</returns>
     /// <exception cref="ArgumentException">Thrown when sessionId is null or empty.</exception>
-    public async Task CloseSessionAsync(string sessionId)
+    public async Task CloseSessionAsync(string sessionId, string? closeReason = null)
     {
         ThrowIfDisposed();
         ValidateSessionId(sessionId, nameof(sessionId));
@@ -237,7 +246,8 @@ public async Task CloseSessionAsync(string sessionId)
                             cancelledCount,
                             timedOutCount,
                             allCommands,
-                            commandIdToBatchId);
+                            commandIdToBatchId,
+                            closeReason);
                     }
                     catch (Exception ex)
                     {
@@ -257,7 +267,7 @@ public async Task CloseSessionAsync(string sessionId)
                 // Remove session creation time tracking
                 _ = m_SessionCreationTimes.TryRemove(sessionId, out _);
 
-                m_Logger.Info("Debug session {SessionId} closed successfully", sessionId);
+                m_Logger.Info("Debug session {SessionId} closed successfully{ReasonSuffix}", sessionId, string.IsNullOrWhiteSpace(closeReason) ? string.Empty : $" (Reason: {closeReason})");
             }
             catch (Exception ex)
             {
@@ -353,6 +363,12 @@ public async Task<string> EnqueueExtensionScriptAsync(string sessionId, string e
             Command = $"Extension: {extensionName}"
         });
 
+        // Register session activity for extension command enqueue
+        if (m_Sessions.TryGetValue(sessionId, out var extSession))
+        {
+            extSession.RegisterActivity();
+        }
+
         return commandId;
     }
 
@@ -525,6 +541,9 @@ public void Dispose()
 
         m_Logger.Info("Disposing DebugEngine with {SessionCount} active sessions", m_Sessions.Count);
 
+        // Stop cleanup timer
+        m_SessionCleanupTimer?.Dispose();
+
         using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
         var failedSessions = new List<string>();
 
@@ -593,6 +612,65 @@ protected void OnSessionStateChanged(object? sender, SessionStateChangedEventArg
     }
 
 
+    /// <summary>
+    /// Scans active sessions and automatically closes those that have been idle beyond the configured timeout.
+    /// Sessions with queued or executing commands are never closed by this cleanup.
+    /// </summary>
+    protected void CleanupIdleSessions()
+    {
+        if (m_Disposed)
+        {
+            return;
+        }
+
+        var now = DateTime.Now;
+        var sessionTimeout = TimeSpan.FromMinutes(Settings.Instance.Get().McpNexus.SessionManagement.SessionTimeoutMinutes);
+
+        foreach (var kvp in m_Sessions)
+        {
+            var sessionId = kvp.Key;
+            var session = kvp.Value;
+
+            try
+            {
+                var lastActivity = session.LastActivityTime;
+
+                // If within timeout, skip
+                if (now - lastActivity < sessionTimeout)
+                {
+                    continue;
+                }
+
+                // Skip if there are any active (queued/executing) commands
+                var anyActive = session
+                    .GetAllCommandInfos()
+                    .Values
+                    .Any(ci => ci.State == CommandState.Queued || ci.State == CommandState.Executing);
+
+                if (anyActive)
+                {
+                    continue;
+                }
+
+                // Close idle session synchronously for determinism
+                try
+                {
+                    m_Logger.Info("Auto-closing idle session {SessionId} after {Minutes} minutes of inactivity", sessionId, sessionTimeout.TotalMinutes);
+                    CloseSessionAsync(sessionId, "IdleTimeout").GetAwaiter().GetResult();
+                }
+                catch (Exception ex)
+                {
+                    m_Logger.Error(ex, "Error auto-closing idle session {SessionId}", sessionId);
+                }
+            }
+            catch (Exception ex)
+            {
+                m_Logger.Warn(ex, "Cleanup check failed for session {SessionId}", sessionId);
+            }
+        }
+    }
+
+
     /// <summary>
     /// Validates that a session ID is not null or empty.
     /// </summary>

nexus_engine/nexus_engine/Internal/DebugSession.cs

@@ -21,6 +21,11 @@ internal class DebugSession : IDisposable
     private readonly ReaderWriterLockSlim m_StateLock = new();
     private SessionState m_State = SessionState.Initializing;
     private volatile bool m_Disposed = false;
+    
+    /// <summary>
+    /// Stores the last activity timestamp for this session as ticks, updated lock-free for performance.
+    /// </summary>
+    private long m_LastActivityTicks;
 
     /// <summary>
     /// Gets the session identifier.
@@ -96,6 +101,9 @@ public DebugSession(
 
         // Subscribe to command queue events
         m_CommandQueue.CommandStateChanged += OnCommandStateChanged;
+
+        // Seed last activity to now
+        m_LastActivityTicks = DateTime.Now.Ticks;
     }
 
     /// <summary>
@@ -117,6 +125,9 @@ public async Task InitializeAsync(CancellationToken cancellationToken = default)
             await m_CommandQueue.StartAsync(m_CdbSession, cancellationToken);
 
             SetState(SessionState.Active);
+
+            UpdateLastActivity();
+            
             m_Logger.Info("Debug session {SessionId} initialized successfully", SessionId);
         }
         catch (Exception ex)
@@ -136,6 +147,8 @@ public string EnqueueCommand(string command)
     {
         ThrowIfDisposed();
         ThrowIfNotActive();
+        
+        UpdateLastActivity();
 
         return m_CommandQueue.EnqueueCommand(command);
     }
@@ -269,6 +282,9 @@ public void Dispose()
     /// <param name="e">The event arguments.</param>
     protected void OnCommandStateChanged(object? sender, CommandStateChangedEventArgs e)
     {
+        // Update last activity whenever a command state changes
+        UpdateLastActivity();
+        
         // Forward the event with session context
         var args = new CommandStateChangedEventArgs
         {
@@ -315,6 +331,33 @@ protected void SetState(SessionState newState)
         }
     }
 
+    /// <summary>
+    /// Gets the last activity time for this session.
+    /// </summary>
+    public DateTime LastActivityTime
+    {
+        get
+        {
+            return new DateTime(Volatile.Read(ref m_LastActivityTicks));
+        }
+    }
+
+    /// <summary>
+    /// Registers an activity on this session by updating the last activity timestamp.
+    /// </summary>
+    internal void RegisterActivity()
+    {
+        UpdateLastActivity();
+    }
+
+    /// <summary>
+    /// Updates the last activity timestamp to the current local time in a lock-free manner.
+    /// </summary>
+    protected void UpdateLastActivity()
+    {
+        _ = Interlocked.Exchange(ref m_LastActivityTicks, DateTime.Now.Ticks);
+    }
+
     /// <summary>
     /// Throws an exception if the session has been disposed.
     /// </summary>

nexus_engine/nexus_engine_share/IDebugEngine.cs

@@ -24,9 +24,10 @@ public interface IDebugEngine : IDisposable
     /// Closes a debug session and cleans up resources.
     /// </summary>
     /// <param name="sessionId">The session ID to close.</param>
+    /// <param name="closeReason">Optional reason for session closure (e.g., "IdleTimeout", "UserRequest").</param>
     /// <returns>A task that represents the asynchronous operation.</returns>
     /// <exception cref="ArgumentException">Thrown when sessionId is null or empty.</exception>
-    Task CloseSessionAsync(string sessionId);
+    Task CloseSessionAsync(string sessionId, string? closeReason = null);
 
     /// <summary>
     /// Checks if a session is currently active.

nexus_engine/nexus_engine_share/Statistics.cs

@@ -114,6 +114,7 @@ public static void EmitCommandStats(
     /// <param name="timedOutCommands">Number of timed out commands.</param>
     /// <param name="commands">Collection of all commands in the session.</param>
     /// <param name="commandIdToBatchId">Optional mapping of individual command IDs to batch command IDs for summary metrics.</param>
+    /// <param name="closeReason">Optional reason for session closure (e.g., IdleTimeout, UserRequest).</param>
     public static void EmitSessionStats(
         Logger logger,
         string sessionId,
@@ -126,7 +127,8 @@ public static void EmitSessionStats(
         int cancelledCommands,
         int timedOutCommands,
         IEnumerable<CommandInfo> commands,
-        IDictionary<string, string?>? commandIdToBatchId = null)
+        IDictionary<string, string?>? commandIdToBatchId = null,
+        string? closeReason = null)
     {
         var sb = new StringBuilder();
         _ = sb.AppendLine();
@@ -135,6 +137,10 @@ public static void EmitSessionStats(
         _ = sb.AppendLine($"    ║ OpenedAt: {openedAt:yyyy-MM-dd HH:mm:ss.fff}");
         _ = sb.AppendLine($"    ║ ClosedAt: {closedAt:yyyy-MM-dd HH:mm:ss.fff}");
         _ = sb.AppendLine($"    ║ TotalDuration: {totalDuration}");
+        if (!string.IsNullOrWhiteSpace(closeReason))
+        {
+            _ = sb.AppendLine($"    ║ CloseReason: {closeReason}");
+        }
         _ = sb.AppendLine("    ║ ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────");
         _ = sb.AppendLine($"    ║ TotalCommands: {totalCommands}");
         _ = sb.AppendLine($"    ║ CompletedCommands: {completedCommands}");

unittests/nexus_config_unittests/Models/SharedConfigurationTests.cs

@@ -228,7 +228,7 @@ public void SessionManagementSettings_DefaultValues_ShouldBeCorrect()
         // Assert
         _ = settings.MaxConcurrentSessions.Should().Be(1000);
         _ = settings.SessionTimeoutMinutes.Should().Be(30);
-        _ = settings.CleanupIntervalMinutes.Should().Be(5);
+        _ = settings.CleanupIntervalSeconds.Should().Be(5);
         _ = settings.DisposalTimeoutSeconds.Should().Be(30);
         _ = settings.DefaultCommandTimeoutMinutes.Should().Be(10);
         _ = settings.MemoryCleanupThresholdMB.Should().Be(1024);
@@ -395,7 +395,7 @@ public void SessionManagementSettings_CanBeModified()
         {
             MaxConcurrentSessions = 50,
             SessionTimeoutMinutes = 60,
-            CleanupIntervalMinutes = 10,
+            CleanupIntervalSeconds = 10,
             DisposalTimeoutSeconds = 60,
             DefaultCommandTimeoutMinutes = 20,
             MemoryCleanupThresholdMB = 2048
@@ -404,7 +404,7 @@ public void SessionManagementSettings_CanBeModified()
         // Assert
         _ = settings.MaxConcurrentSessions.Should().Be(50);
         _ = settings.SessionTimeoutMinutes.Should().Be(60);
-        _ = settings.CleanupIntervalMinutes.Should().Be(10);
+        _ = settings.CleanupIntervalSeconds.Should().Be(10);
         _ = settings.DisposalTimeoutSeconds.Should().Be(60);
         _ = settings.DefaultCommandTimeoutMinutes.Should().Be(20);
         _ = settings.MemoryCleanupThresholdMB.Should().Be(2048);

unittests/nexus_engine/nexus_engine_unittests/DebugEngineTestAccessor.cs

@@ -57,5 +57,13 @@ public DebugEngineTestAccessor(IFileSystem fileSystem, IProcessManager processMa
     {
         base.ThrowIfDisposed();
     }
+
+    /// <summary>
+    /// Invokes the protected idle session cleanup for testing.
+    /// </summary>
+    public void InvokeCleanupIdleSessions()
+    {
+        base.CleanupIdleSessions();
+    }
 }