fix(debug): support shell expansion for debug adapter launch args (#17200) by ankitsharma101 · Pull Request #17224 · eclipse-theia/theia

ankitsharma101 · 2026-03-25T19:50:06Z

What it does

This PR resolves an issue where adapters like debugpy block debug execution when passed shell-expanded arguments (e.g., "args": "${command:pickArgs}").

The fix requires two steps to achieve VS Code parity:

DAP Initialization: Added the supportsArgsCanBeInterpretedByShell: true capability to the client initialize payload. Without this, adapters strictly enforcing DAP capabilities reject the launch request with Invalid message: Shell expansion in "args" is not supported by the client.
Terminal Execution: Updated the runInTerminal implementation in debug-session.tsx. When argsCanBeInterpretedByShell is true, Theia now joins the arguments into a single raw command string (sendText) instead of passing the array to executeCommand. This prevents Theia from automatically wrapping the variables in single quotes, allowing the underlying shell (like bash) to natively evaluate expansions (like $USER or > output.txt) before passing them to the debugger.

How to test

Install the ms-python.python and ms-python.debugpy extensions in a local Theia browser environment.
Create a Python file (e.g., test.py) that prints sys.argv.
Create a launch.json configuration for debugpy that includes: "args": "${command:pickArgs}"
Start the debug session. When prompted for arguments, test the following:
- Standard args: hello world -> script should receive ['hello', 'world']
- Shell variables: $USER -> script should receive your actual environment username, proving the shell expanded it before passing to Python.
- Redirection: > output.txt -> script output should be redirected to a file, proving the shell intercepted the command.

Follow-ups

None at this time. This aligns Theia's terminal execution for debuggers with VS Code's expected behavior.

Breaking changes

This PR introduces breaking changes and requires careful review. If yes, the breaking changes section in the changelog has been updated.

Attribution

Review checklist

As an author, I have thoroughly tested my changes and carefully followed the review guidelines
User-facing text is internationalized using the nls service (for details, please see the Internationalization/Localization section in the Coding Guidelines)

Reminder for reviewers

As a reviewer, I agree to behave in accordance with the review guidelines

eneufeld

Thank you for the fix. It works in general. It is missing some points though we should fix before merging it, see inline comments.

eneufeld · 2026-04-08T14:35:27Z

+        // we join the arguments into a single raw command string and send it directly.
+        // This prevents Theia from automatically wrapping the variables in single quotes.
+        if (argsCanBeInterpretedByShell) {
+            const rawCommand = args.join(' ') + '\r';


we should use OS.backend.EOL instead of \r.
I would also reduce the amount of comments.

eneufeld · 2026-04-08T14:37:34Z

+        // This prevents Theia from automatically wrapping the variables in single quotes.
+        if (argsCanBeInterpretedByShell) {
+            const rawCommand = args.join(' ') + '\r';
+            await terminal.sendText(rawCommand);


This has a bug at the moment. The main issue is the missing cwd.
Check how executeCommand creates the text that is send to the terminal.
So it should be something like: use ShellCommandBuilder to construct the cd && env KEY=VAL ... prefix with proper escaping, then append the raw unquoted args, and send the whole thing via sendText with OS.backend.EOL.

we should also call resetCommandOutputMarker after the sendText.

Basically it is the same follow more how executeCommand is implemented.

…on for pickArgs - Use ShellCommandBuilder to construct cd+env+executable prefix with proper escaping - Append remaining args raw so shell can expand variables and handle redirections - Use OS.backend.EOL instead of \r - Reduce verbose comments - Fix DebuggerDescription to include variables field so command variables like pickArgs resolve correctly - Pass variables through plugin debug registration chain (debug-ext.ts, debug-main.ts) - Inject ShellCommandBuilder into DefaultDebugSessionFactory and PluginDebugSessionFactory

ankitsharma101 · 2026-04-18T19:10:29Z

Thank you for the detailed review! I've addressed all the feedback:

Addressed review comments:

Replaced \r with OS.backend.EOL
Reduced comments to just one concise explanation
Fixed the missing cwd by using ShellCommandBuilder to construct the cd && env && executable prefix with proper escaping, then appending the remaining args raw for shell expansion

Regarding resetCommandOutputMarker — I searched the codebase and couldn't find this method on TerminalWidget. Could you point me to where this should come from, or is this something that needs to be added?

Additional fix included in this PR:
While testing, I discovered that ${command:pickArgs} was being passed as a literal string rather than being resolved. The root cause was that DebuggerDescription didn't include the variables field, so provideDebuggerVariables always returned an empty map and the command variable resolver never mapped pickArgs → debugpy.pickArgs. I've fixed this by:

Adding variables to DebuggerDescription
Passing variables through the plugin debug registration chain (debug-ext.ts → debug-main.ts)
Calling registerDebugger with the full contribution including variables

All three test cases now pass:

hello world → ['hello', 'world'] ✅
$USER → actual username (shell expansion) ✅
> output.txt → output redirected to file ✅

Signed-off-by: Ankit Sharma <ankitsharmaeclipse@gmail.com>

…service

eneufeld

I think we are nearly there, but we should use the injected builder otherwise there is no benefit in injecting it. But as it can be extended, the injection is the right choice

eneufeld · 2026-04-20T20:21:50Z

        protected readonly workspaceService: WorkspaceService,
        protected readonly debugPreferences: DebugPreferences,
        protected readonly commandService: CommandService,
+        protected readonly shellCommandBuilder: ShellCommandBuilder,


this needs to be documented in the changelog as this is a breaking change for anybody subclassing this

eneufeld · 2026-04-20T20:22:15Z

-        await terminal.executeCommand({ cwd, args, env });
+
+        if (argsCanBeInterpretedByShell) {
+            const builder = new ShellCommandBuilder();


why are we not using the injected builder?

eneufeld · 2026-04-20T20:22:37Z

            // `multer` handles `multipart/form-data` containing our file to upload.
-            multer({ dest }).single('file'),
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (multer({ dest }).single('file') as any),


can't we just not touch this file at all?

… changelog

ankitsharma101 · 2026-04-21T11:33:02Z

Thanks for the review! Here's what I've done:

Switched to this.shellCommandBuilder instead of creating a new instance
Added the breaking change and feature entries to the changelog

For node-file-upload-service.ts — I'd love to leave it untouched, but adding @theia/process to plugin-ext causes a type conflict with a duplicate @types/express-serve-static-core in the monorepo, which breaks the build in that file. The eslint-disable + as any is the minimal fix I found. Happy to explore a different approach if you have one in mind.

Also, regarding resetCommandOutputMarker from the earlier review — I couldn't find that method anywhere in the terminal package. Is it something that already exists somewhere, or would it need to be added?

style: remove trailing spaces

3cb1f96

github-project-automation Bot added this to PR Backlog Mar 25, 2026

github-project-automation Bot moved this to Waiting on reviewers in PR Backlog Mar 25, 2026

ankitsharma101 mentioned this pull request Mar 25, 2026

"${command:pickArgs}" is not supported for debug launch #17200

Open

ndoschek requested a review from eneufeld April 8, 2026 09:58

eneufeld reviewed Apr 8, 2026

View reviewed changes

eneufeld requested changes Apr 8, 2026

View reviewed changes

github-project-automation Bot moved this from Waiting on reviewers to Waiting on author in PR Backlog Apr 8, 2026

ankitsharma101 and others added 4 commits April 19, 2026 00:51

Merge branch 'master' into fix-17200-debug-shell-expansion

1c56b81

chore: add @theia/process dependency to plugin-ext

5c148f0

Signed-off-by: Ankit Sharma <ankitsharmaeclipse@gmail.com>

fix: update @theia/process version to 1.70.0 to fix workspace build

ae210bd

Signed-off-by: Ankit Sharma <ankitsharmaeclipse@gmail.com>

fix: resolve lint error and multer type mismatch in node-file-upload-…

dbab37e

…service

eneufeld requested changes Apr 20, 2026

View reviewed changes

fix: use injected shellCommandBuilder and document breaking change in…

42f7024

… changelog

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(debug): support shell expansion for debug adapter launch args (#17200)#17224

fix(debug): support shell expansion for debug adapter launch args (#17200)#17224
ankitsharma101 wants to merge 7 commits intoeclipse-theia:masterfrom
ankitsharma101:fix-17200-debug-shell-expansion

ankitsharma101 commented Mar 25, 2026

Uh oh!

eneufeld left a comment

Uh oh!

eneufeld Apr 8, 2026

Uh oh!

eneufeld Apr 8, 2026

Uh oh!

eneufeld Apr 8, 2026

Uh oh!

ankitsharma101 commented Apr 18, 2026

Uh oh!

eneufeld left a comment

Uh oh!

eneufeld Apr 20, 2026

Uh oh!

eneufeld Apr 20, 2026

Uh oh!

eneufeld Apr 20, 2026

Uh oh!

ankitsharma101 commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

ankitsharma101 commented Mar 25, 2026

What it does

How to test

Follow-ups

Breaking changes

Attribution

Review checklist

Reminder for reviewers

Uh oh!

eneufeld left a comment

Choose a reason for hiding this comment

Uh oh!

eneufeld Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

eneufeld Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

eneufeld Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

ankitsharma101 commented Apr 18, 2026

Uh oh!

eneufeld left a comment

Choose a reason for hiding this comment

Uh oh!

eneufeld Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

eneufeld Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

eneufeld Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

ankitsharma101 commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants