Send welcome message in debugger console on connect (#4419)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

src/Runner.Common/Constants.cs

@@ -179,6 +179,7 @@ namespace GitHub.Runner.Common
                 public static readonly string EmitCompositeMarkers = "actions_runner_emit_composite_markers";
                 public static readonly string BatchActionResolution = "actions_batch_action_resolution";
                 public static readonly string UseBearerTokenForCodeload = "actions_use_bearer_token_for_codeload";
+                public static readonly string OverrideDebuggerWelcomeMessage = "actions_runner_override_debugger_welcome_message";
             }
 
             // Node version migration related constants

src/Runner.Worker/Dap/DapDebugger.cs

@@ -63,6 +63,7 @@ namespace GitHub.Runner.Worker.Dap
         private volatile DapSessionState _state = DapSessionState.NotStarted;
         private CancellationTokenRegistration? _cancellationRegistration;
         private bool _isFirstStep = true;
+        private bool _welcomeMessageSent;
 
         // Dev Tunnel relay host for remote debugging
         private TunnelRelayTunnelHost _tunnelRelayHost;
@@ -490,6 +491,11 @@ namespace GitHub.Runner.Worker.Dap
                     });
                     Trace.Info("Sent initialized event");
                 }
+
+                if (request.Command == "configurationDone")
+                {
+                    SendWelcomeMessage();
+                }
             }
             catch (Exception ex)
             {
@@ -508,6 +514,7 @@ namespace GitHub.Runner.Worker.Dap
         internal void HandleClientConnected()
         {
             _isClientConnected = true;
+            _welcomeMessageSent = false;
             Trace.Info("Client connected to debug session");
 
             // If we're paused, re-send the stopped event so the new client
@@ -818,6 +825,34 @@ namespace GitHub.Runner.Worker.Dap
             });
         }
 
+        internal void SendWelcomeMessage()
+        {
+            if (_welcomeMessageSent)
+            {
+                return;
+            }
+            _welcomeMessageSent = true;
+
+            var debuggerConfig = _jobContext?.Global?.Debugger;
+            if (debuggerConfig?.OverrideWelcomeMessage == true)
+            {
+                if (!string.IsNullOrEmpty(debuggerConfig.WelcomeMessage))
+                {
+                    SendOutput("console", debuggerConfig.WelcomeMessage);
+                    Trace.Info("Sent custom welcome message");
+                }
+                else
+                {
+                    Trace.Info("Welcome message suppressed by override");
+                }
+            }
+            else
+            {
+                SendOutput("console", DapReplParser.GetGeneralHelp());
+                Trace.Info("Sent default welcome message");
+            }
+        }
+
         internal async Task OnStepStartingAsync(IStep step, bool isFirstStep)
         {
             bool pauseOnNextStep;

src/Runner.Worker/Dap/DebuggerConfig.cs

@@ -1,4 +1,4 @@
-using GitHub.DistributedTask.Pipelines;
+using GitHub.DistributedTask.Pipelines;
 
 namespace GitHub.Runner.Worker.Dap
 {
@@ -8,10 +8,12 @@ namespace GitHub.Runner.Worker.Dap
     /// </summary>
     public sealed class DebuggerConfig
     {
-        public DebuggerConfig(bool enabled, DebuggerTunnelInfo tunnel)
+        public DebuggerConfig(bool enabled, DebuggerTunnelInfo tunnel, bool overrideWelcomeMessage = false, string welcomeMessage = null)
         {
             Enabled = enabled;
             Tunnel = tunnel;
+            OverrideWelcomeMessage = overrideWelcomeMessage;
+            WelcomeMessage = welcomeMessage;
         }
 
         /// <summary>Whether the debugger is enabled for this job.</summary>
@@ -23,6 +25,19 @@ namespace GitHub.Runner.Worker.Dap
         /// </summary>
         public DebuggerTunnelInfo Tunnel { get; }
 
+        /// <summary>
+        /// When true, the runner overrides the default welcome message with
+        /// <see cref="WelcomeMessage"/>. A null or empty <see cref="WelcomeMessage"/>
+        /// suppresses the message entirely. When false, the default help text is shown.
+        /// </summary>
+        public bool OverrideWelcomeMessage { get; }
+
+        /// <summary>
+        /// Optional welcome message content for the debugger console. Only used when
+        /// <see cref="OverrideWelcomeMessage"/> is true.
+        /// </summary>
+        public string WelcomeMessage { get; }
+
         /// <summary>Whether the tunnel configuration is complete and valid.</summary>
         public bool HasValidTunnel => Tunnel != null
             && !string.IsNullOrEmpty(Tunnel.TunnelId)

src/Runner.Worker/ExecutionContext.cs

@@ -970,7 +970,8 @@ namespace GitHub.Runner.Worker
             Global.WriteDebug = Global.Variables.Step_Debug ?? false;
 
             // Debugger enabled flag (from acquire response).
-            Global.Debugger = new Dap.DebuggerConfig(message.EnableDebugger, message.DebuggerTunnel);
+            var overrideDebuggerWelcomeMessage = Global.Variables.GetBoolean(Constants.Runner.Features.OverrideDebuggerWelcomeMessage) ?? false;
+            Global.Debugger = new Dap.DebuggerConfig(message.EnableDebugger, message.DebuggerTunnel, overrideDebuggerWelcomeMessage, message.DebuggerWelcomeMessage);
 
             // Hook up JobServerQueueThrottling event, we will log warning on server tarpit.
             _jobServerQueue.JobServerQueueThrottling += JobServerQueueThrottling_EventReceived;

src/Sdk/DTPipelines/Pipelines/AgentJobRequestMessage.cs

@@ -267,6 +267,21 @@ namespace GitHub.DistributedTask.Pipelines
             set;
         }
 
+        /// <summary>
+        /// Optional welcome message shown in the debugger console when a client connects.
+        /// Only used when the <c>actions_runner_override_debugger_welcome_message</c>
+        /// feature flag is set to <c>true</c> in the job variables. With the flag set,
+        /// a non-empty value is shown as-is and a null or empty value suppresses the
+        /// default welcome message. When the flag is not set, the runner shows its
+        /// built-in help text and this field is ignored.
+        /// </summary>
+        [DataMember(EmitDefaultValue = false)]
+        public string DebuggerWelcomeMessage
+        {
+            get;
+            set;
+        }
+
         /// <summary>
         /// Gets the workflow-level action dependencies (lockfile entries)
         /// </summary>

src/Test/L0/Sdk/RSWebApi/AgentJobRequestMessageL0.cs

@@ -1,4 +1,4 @@
-using System.Collections.Generic;
+using System.Collections.Generic;
 using System.IO;
 using System.Runtime.Serialization.Json;
 using System.Text;
@@ -161,6 +161,26 @@ public sealed class AgentJobRequestMessageL0
         Assert.Empty(recoveredMessage.ActionsDependencies);
     }
 
+    [Fact]
+    [Trait("Level", "L0")]
+    [Trait("Category", "Common")]
+    public void VerifyDebuggerWelcomeMessageRoundTrips()
+    {
+        // Arrange
+        var serializer = new DataContractJsonSerializer(typeof(AgentJobRequestMessage));
+        string json = DoubleQuotify("{'DebuggerWelcomeMessage': 'Welcome to debugging!'}");
+
+        // Act
+        using var stream = new MemoryStream();
+        stream.Write(Encoding.UTF8.GetBytes(json));
+        stream.Position = 0;
+        var recoveredMessage = serializer.ReadObject(stream) as AgentJobRequestMessage;
+
+        // Assert
+        Assert.NotNull(recoveredMessage);
+        Assert.Equal("Welcome to debugging!", recoveredMessage.DebuggerWelcomeMessage);
+    }
+
     private static string DoubleQuotify(string text)
     {
         return text.Replace('\'', '"');

src/Test/L0/Worker/DapDebuggerL0.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.IO;
 using System.Net;
 using System.Net.Sockets;
@@ -236,7 +236,7 @@ namespace GitHub.Runner.Common.Tests.Worker
             }
         }
 
-        private static Mock<IExecutionContext> CreateJobContextWithTunnel(CancellationToken cancellationToken, ushort port, string jobName = null)
+        private static Mock<IExecutionContext> CreateJobContextWithTunnel(CancellationToken cancellationToken, ushort port, string jobName = null, bool overrideWelcomeMessage = false, string welcomeMessage = null)
         {
             var tunnel = new GitHub.DistributedTask.Pipelines.DebuggerTunnelInfo
             {
@@ -245,7 +245,7 @@ namespace GitHub.Runner.Common.Tests.Worker
                 HostToken = "test-token",
                 Port = port
             };
-            var debuggerConfig = new DebuggerConfig(true, tunnel);
+            var debuggerConfig = new DebuggerConfig(true, tunnel, overrideWelcomeMessage, welcomeMessage);
             var jobContext = new Mock<IExecutionContext>();
             jobContext.Setup(x => x.CancellationToken).Returns(cancellationToken);
             jobContext.Setup(x => x.Global).Returns(new GlobalContext { Debugger = debuggerConfig });
@@ -742,6 +742,8 @@ namespace GitHub.Runner.Common.Tests.Worker
 
                 // Read the configurationDone response
                 await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                // Read the welcome message output event
+                await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
                 await waitTask;
 
                 // Complete the job — OnJobCompletedAsync pauses when stepping,
@@ -849,6 +851,8 @@ namespace GitHub.Runner.Common.Tests.Worker
                     Command = "configurationDone"
                 });
 
+                await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                // Read the welcome message output event
                 await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
                 await waitTask;
 
@@ -867,5 +871,224 @@ namespace GitHub.Runner.Common.Tests.Worker
                 Assert.Equal(completedTask, finished);
             }
         }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Worker")]
+        public async Task WelcomeMessageSendsDefaultHelpWhenOverrideDisabled()
+        {
+            using (CreateTestContext())
+            {
+                var port = GetFreePort();
+                using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
+                var jobContext = CreateJobContextWithTunnel(cts.Token, port);
+                await _debugger.StartAsync(jobContext.Object);
+
+                using var client = await ConnectClientAsync(port);
+                var stream = client.GetStream();
+
+                await SendRequestAsync(stream, new Request
+                {
+                    Seq = 1,
+                    Type = "request",
+                    Command = "configurationDone"
+                });
+
+                // First message: configurationDone response
+                var configDoneResponse = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"command\":\"configurationDone\"", configDoneResponse);
+
+                // Second message: welcome output event with default help text
+                var welcomeMsg = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"event\":\"output\"", welcomeMsg);
+                Assert.Contains("\"category\":\"console\"", welcomeMsg);
+                Assert.Contains("Actions Debug Console", welcomeMsg);
+                Assert.Contains("help", welcomeMsg);
+
+                await _debugger.StopAsync();
+            }
+        }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Worker")]
+        public async Task WelcomeMessageShowsCustomMessageWhenOverrideEnabled()
+        {
+            using (CreateTestContext())
+            {
+                var port = GetFreePort();
+                using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
+                var jobContext = CreateJobContextWithTunnel(cts.Token, port,
+                    overrideWelcomeMessage: true,
+                    welcomeMessage: "Welcome to debugging!");
+                await _debugger.StartAsync(jobContext.Object);
+
+                using var client = await ConnectClientAsync(port);
+                var stream = client.GetStream();
+
+                await SendRequestAsync(stream, new Request
+                {
+                    Seq = 1,
+                    Type = "request",
+                    Command = "configurationDone"
+                });
+
+                // First: configurationDone response
+                var configDoneResponse = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"command\":\"configurationDone\"", configDoneResponse);
+
+                // Second: custom welcome message
+                var welcomeMsg = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"event\":\"output\"", welcomeMsg);
+                Assert.Contains("Welcome to debugging!", welcomeMsg);
+
+                await _debugger.StopAsync();
+            }
+        }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Worker")]
+        public async Task WelcomeMessageSuppressedWhenOverrideEnabledWithEmptyMessage()
+        {
+            using (CreateTestContext())
+            {
+                var port = GetFreePort();
+                using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
+                var jobContext = CreateJobContextWithTunnel(cts.Token, port,
+                    overrideWelcomeMessage: true,
+                    welcomeMessage: "");
+                await _debugger.StartAsync(jobContext.Object);
+
+                using var client = await ConnectClientAsync(port);
+                var stream = client.GetStream();
+
+                await SendRequestAsync(stream, new Request
+                {
+                    Seq = 1,
+                    Type = "request",
+                    Command = "configurationDone"
+                });
+
+                // Read configurationDone response
+                var configDoneResponse = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"command\":\"configurationDone\"", configDoneResponse);
+
+                // Send threads request — if welcome message was suppressed, this
+                // should be the next response (no output event in between)
+                await SendRequestAsync(stream, new Request
+                {
+                    Seq = 2,
+                    Type = "request",
+                    Command = "threads"
+                });
+
+                var threadsResponse = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"command\":\"threads\"", threadsResponse);
+
+                await _debugger.StopAsync();
+            }
+        }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Worker")]
+        public async Task WelcomeMessageSuppressedWhenOverrideEnabledWithNullMessage()
+        {
+            using (CreateTestContext())
+            {
+                var port = GetFreePort();
+                using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
+                var jobContext = CreateJobContextWithTunnel(cts.Token, port,
+                    overrideWelcomeMessage: true,
+                    welcomeMessage: null);
+                await _debugger.StartAsync(jobContext.Object);
+
+                using var client = await ConnectClientAsync(port);
+                var stream = client.GetStream();
+
+                await SendRequestAsync(stream, new Request
+                {
+                    Seq = 1,
+                    Type = "request",
+                    Command = "configurationDone"
+                });
+
+                // Read configurationDone response
+                var configDoneResponse = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"command\":\"configurationDone\"", configDoneResponse);
+
+                // Send threads request — if welcome message was suppressed, this
+                // should be the next response (no output event in between)
+                await SendRequestAsync(stream, new Request
+                {
+                    Seq = 2,
+                    Type = "request",
+                    Command = "threads"
+                });
+
+                var threadsResponse = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"command\":\"threads\"", threadsResponse);
+
+                await _debugger.StopAsync();
+            }
+        }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Worker")]
+        public async Task WelcomeMessageSentOnlyOnce()
+        {
+            using (CreateTestContext())
+            {
+                var port = GetFreePort();
+                using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
+                var jobContext = CreateJobContextWithTunnel(cts.Token, port);
+                await _debugger.StartAsync(jobContext.Object);
+
+                using var client = await ConnectClientAsync(port);
+                var stream = client.GetStream();
+
+                // First configurationDone
+                await SendRequestAsync(stream, new Request
+                {
+                    Seq = 1,
+                    Type = "request",
+                    Command = "configurationDone"
+                });
+
+                var configDoneResponse = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"command\":\"configurationDone\"", configDoneResponse);
+
+                // Welcome message should appear
+                var welcomeMsg = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"event\":\"output\"", welcomeMsg);
+                Assert.Contains("Actions Debug Console", welcomeMsg);
+
+                // Second configurationDone — should NOT produce another welcome message
+                await SendRequestAsync(stream, new Request
+                {
+                    Seq = 2,
+                    Type = "request",
+                    Command = "configurationDone"
+                });
+
+                var secondResponse = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"command\":\"configurationDone\"", secondResponse);
+
+                // Next message should be threads response, not another welcome output
+                await SendRequestAsync(stream, new Request
+                {
+                    Seq = 3,
+                    Type = "request",
+                    Command = "threads"
+                });
+
+                var threadsResponse = await ReadDapMessageAsync(stream, TimeSpan.FromSeconds(5));
+                Assert.Contains("\"command\":\"threads\"", threadsResponse);
+
+                await _debugger.StopAsync();
+            }
+        }
     }
 }