Merge remote-tracking branch 'origin/main' into agent-2/issue-33-implement-graceful-shutdown

# Conflicts:
#	src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs
#	src/MxGateway.Worker/Ipc/WorkerPipeClient.cs
#	src/MxGateway.Worker/Ipc/WorkerPipeSession.cs

src/MxGateway.Worker/MxAccess/IWorkerRuntimeSession.cs

@@ -0,0 +1,25 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using MxGateway.Contracts.Proto;
+using MxGateway.Worker.Sta;
+
+namespace MxGateway.Worker.MxAccess;
+
+public interface IWorkerRuntimeSession : IDisposable
+{
+    Task<WorkerReady> StartAsync(
+        string sessionId,
+        int workerProcessId,
+        CancellationToken cancellationToken = default);
+
+    Task<MxCommandReply> DispatchAsync(StaCommand command);
+
+    WorkerRuntimeHeartbeatSnapshot CaptureHeartbeat();
+
+    void RequestShutdown();
+
+    Task<MxAccessShutdownResult> ShutdownGracefullyAsync(
+        TimeSpan timeout,
+        CancellationToken cancellationToken = default);
+}

src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs

@@ -8,7 +8,7 @@ using MxGateway.Worker.Sta;
 
 namespace MxGateway.Worker.MxAccess;
 
-public sealed class MxAccessStaSession : IDisposable
+public sealed class MxAccessStaSession : IWorkerRuntimeSession
 {
     private readonly IMxAccessComObjectFactory factory;
     private readonly IMxAccessEventSink eventSink;
@@ -98,6 +98,30 @@ public sealed class MxAccessStaSession : IDisposable
         return commandDispatcher.DispatchAsync(command);
     }
 
+    public WorkerRuntimeHeartbeatSnapshot CaptureHeartbeat()
+    {
+        uint pendingCommandCount = 0;
+        string currentCommandCorrelationId = string.Empty;
+
+        if (commandDispatcher is not null)
+        {
+            pendingCommandCount = (uint)commandDispatcher.PendingCommandCount;
+            currentCommandCorrelationId = commandDispatcher.CurrentCommandCorrelationId;
+        }
+
+        return new WorkerRuntimeHeartbeatSnapshot(
+            staRuntime.LastActivityUtc,
+            pendingCommandCount,
+            (uint)eventQueue.Count,
+            eventQueue.LastEventSequence,
+            currentCommandCorrelationId);
+    }
+
+    public void RequestShutdown()
+    {
+        commandDispatcher?.RequestShutdown();
+    }
+
     public IReadOnlyList<WorkerEvent> DrainEvents(uint maxEvents)
     {
         return eventQueue.Drain(maxEvents);
@@ -204,7 +228,7 @@ public sealed class MxAccessStaSession : IDisposable
             return;
         }
 
-        commandDispatcher?.RequestShutdown();
+        RequestShutdown();
 
         if (session is not null)
         {

src/MxGateway.Worker/MxAccess/WorkerRuntimeHeartbeatSnapshot.cs

@@ -0,0 +1,30 @@
+using System;
+
+namespace MxGateway.Worker.MxAccess;
+
+public sealed class WorkerRuntimeHeartbeatSnapshot
+{
+    public WorkerRuntimeHeartbeatSnapshot(
+        DateTimeOffset lastStaActivityUtc,
+        uint pendingCommandCount,
+        uint outboundEventQueueDepth,
+        ulong lastEventSequence,
+        string currentCommandCorrelationId)
+    {
+        LastStaActivityUtc = lastStaActivityUtc;
+        PendingCommandCount = pendingCommandCount;
+        OutboundEventQueueDepth = outboundEventQueueDepth;
+        LastEventSequence = lastEventSequence;
+        CurrentCommandCorrelationId = currentCommandCorrelationId ?? string.Empty;
+    }
+
+    public DateTimeOffset LastStaActivityUtc { get; }
+
+    public uint PendingCommandCount { get; }
+
+    public uint OutboundEventQueueDepth { get; }
+
+    public ulong LastEventSequence { get; }
+
+    public string CurrentCommandCorrelationId { get; }
+}