Add DAP server

[rentziass]

This adds a DAP server to the runner to build debugging functionalities. The whole DAP integration is gated by the new EnableDebugger flag on the job message (feature flagged at the API level).

When a job starts, after the job setup we will start the DAP server and allow users to step over to every step in the job, and:

• inspect the scope of the runner
• test evaluating expressions
• run shell commands as if they were run steps in their jobs (full job context, supporting expression expansion, etc.)

Here's an example of what this looks like connecting to the runner from nvim-dap:

[Copilot]

Pull request overview

Adds a Debug Adapter Protocol (DAP) subsystem to the runner (gated by EnableDebugger on the job message) to enable step-level debugging, scope/variable inspection, expression evaluation, and a REPL for running commands in-job context.

Changes:

• Introduces DAP runtime components (TCP server, debug session, variable provider, REPL parser/executor, DAP message models) under src/Runner.Worker/Dap/.
• Plumbs EnableDebugger from AgentJobRequestMessage → ExecutionContext.Global and wires debugger lifecycle into JobRunner and step boundaries into StepsRunner.
• Adds extensive L0 coverage for DAP protocol framing, session flow, masking behavior, REPL parsing/execution helpers, and message serialization.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Sdk/DTPipelines/Pipelines/AgentJobRequestMessage.cs	Adds EnableDebugger to job message contract.
src/Test/L0/Sdk/RSWebApi/AgentJobRequestMessageL0.cs	Validates EnableDebugger JSON deserialization behavior.
src/Runner.Worker/GlobalContext.cs	Stores EnableDebugger on global execution context.
src/Runner.Worker/ExecutionContext.cs	Copies EnableDebugger from job message into GlobalContext.
src/Runner.Worker/JobRunner.cs	Starts/waits/stops DAP debugger based on EnableDebugger; fails job if requested but unavailable.
src/Runner.Worker/StepsRunner.cs	Hooks step-boundary callbacks to debugger (pause/complete/job complete).
src/Runner.Worker/Dap/IDapServer.cs	Introduces DAP server service interface.
src/Runner.Worker/Dap/IDapDebugger.cs	Introduces debugger facade interface used by runner orchestration.
src/Runner.Worker/Dap/IDapDebugSession.cs	Introduces debug session interface + session state enum.
src/Runner.Worker/Dap/DapServer.cs	Implements TCP DAP server with framing + reconnection loop.
src/Runner.Worker/Dap/DapDebugger.cs	Implements lifecycle facade for server/session with env-var overrides.
src/Runner.Worker/Dap/DapDebugSession.cs	Implements DAP command handling + step-level pause/continue/next, evaluate, scopes/variables, reconnection.
src/Runner.Worker/Dap/DapVariableProvider.cs	Maps runner expression contexts into DAP scopes/variables; performs masking/redaction.
src/Runner.Worker/Dap/DapReplParser.cs	Parses help(...) / run(...) REPL DSL commands.
src/Runner.Worker/Dap/DapReplExecutor.cs	Executes run(...) scripts using runner process infrastructure and streams masked output.
src/Runner.Worker/Dap/DapMessages.cs	Adds DAP protocol message models and related DTOs.
src/Test/L0/Worker/DapVariableProviderL0.cs	Tests scopes/variables, masking/redaction, nested expansion, evaluate, and helpers.
src/Test/L0/Worker/DapServerL0.cs	Tests server lifecycle, framing, cancellation, and protocol-metadata preservation.
src/Test/L0/Worker/DapReplParserL0.cs	Tests REPL DSL parsing and error cases.
src/Test/L0/Worker/DapReplExecutorL0.cs	Tests expression expansion, shell resolution, and environment merging helpers.
src/Test/L0/Worker/DapMessagesL0.cs	Tests serialization/deserialization of core DAP models.
src/Test/L0/Worker/DapDebuggerL0.cs	Tests debugger facade lifecycle + env-var overrides + cancellation behavior.
src/Test/L0/Worker/DapDebugSessionL0.cs	Tests end-to-end session flow, stepping behavior, masking, scopes/variables, evaluate, and REPL routing.

---

You can also share your feedback on Copilot code review. Take the survey.

[ChristopherHX]

I like it 👍 , works pretty well in vscode.

• Only the Callstack did not auto focus the active callframe for me so e.g. watch displayed the error ((no execution context available)) until selecting the step where the debugger stopped by hand
• I used this vscode extension stub to attach: vscode-ext-to-attach.zip (generated by AI)
• Expression debug logs end up in the uploaded job log (not debugger log) if you evaluate expressions (ACTIONS_STEP_DEBUG=true)

[ChristopherHX]

Write this to job log as well? So you can actually see why the job does not continue with the next step?

Only the error Failed to start debugger can be seen there.

[rentziass]

Thank you that's a great point, I'm going to add a new "artificial" step after job setup to better show users that the debugger is enabled and we're waiting on them to connect ❤️

[rentziass]

Got a first draft working locally but it's a sizeable change, going to move it to its own PR. Adding a pre/post step might also be a good way to let us inspect state after the last actual job step completed too.

[ChristopherHX]

Indeed much more visible than just a log message in a Job setup and reads really like a much bigger change.

Adding a pre/post step might also be a good way to let us inspect state after the last actual job step completed too.

Sounds like an interesting solution.

[ChristopherHX]

I usually find it useful to be able to inspect variables and run scripts after the last step of a job

Suggested change

	// Pause for DAP debugger before sending job completion
	await dapDebugger?.OnJobCompleteStartingAsync(jobContext.CancellationToken);

[rentziass]

I totally agree with you but we need to figure out the right way for doing this, and it's probably going to come in the next PRs since this one is huge as is already 😄

We need to find a good way to both:

• give users a good way to setup breakpoints looking at source code
• allow users to setup breakpoints at times that can't be referred to from normal source code (pre/post actions steps and job completion come to mind here).

That is to say, we're quite a bit away still from fully releasing this but this is most definitely on our radar!

[ChristopherHX]

• allow users to setup breakpoints at times that can't be referred to from normal source code [...]

job completion

Idk how this works for a DAP Adapter, but some vscode extension debugger have a checkbox for unhandled exception if this would allow a free text JobCompletion could be such a predefined enable/disable breakpoint.
E.g. in my experiment, only step over is a possible way to pause before job completion.

pre/post actions steps

Conditional breakpoints come into my mind: E.g. you make a breakpoint that would by default pause before pre, main and post. Optionally the condition could have a variable that can filter the stage e.g. condition stage == 'main' (using existing actions expressions with custom global variable from debugger)

[ChristopherHX]

RE https://github.com/actions/runner/pull/4298/changes#r2949684913

Suggested change

	Task OnJobCompletedAsync();
	Task OnJobCompleteStartingAsync(CancellationToken cancellationToken);
	Task OnJobCompletedAsync();

[ChristopherHX]

RE https://github.com/actions/runner/pull/4298/changes#r2949684913

Suggested change

	public async Task OnJobCompleteStartingAsync(CancellationToken cancellationToken)
	{
	if (_started)
	{
	try
	{
	bool pauseOnNextStep;
	lock (_stateLock)
	{
	if (_state == DapSessionState.Terminated)
	{
	Trace.Info("Session already terminated, skipping OnJobCompleted events");
	return;
	}
	pauseOnNextStep = _pauseOnNextStep;
	}
	if (pauseOnNextStep)
	{
	var reason = "step";
	var description = "Stopped at job completion";
	Trace.Info("Job completed with debugger pause");
	// Send stopped event to debugger (only if client is connected)
	SendStoppedEvent(reason, description);
	// Wait for debugger command
	await WaitForCommandAsync(cancellationToken);
	}
	}
	catch (Exception ex)
	{
	Trace.Warning($"DAP OnJobCompleteStartingAsync error: {ex.Message}");
	}
	}
	}

[TingluoHuang]

🤷 not sure what is RunContinuationsAsynchronously doing.