Support PowerShell intellisense in the terminal

[Tyriar]

No description provided.

[alessandro-newzoo]

@Tyriar How exactly does this work? I have found zero documentation available about this, and if I google terminal.integrated.shellIntegration.suggestEnabled pretty much nothing comes up?

I have enabled both terminal.integrated.shellIntegration.suggestEnabled and terminal.integrated.shellIntegration.enabled - shell integration works fine but I don't get any suggestions at all.

[Tyriar]

@alessandro-newzoo it will only work on the latest insiders build released today, just setting that should make it work. It's triggered by typing - currently.

Here's roughly how it works:

terminal.integrated.shellIntegration.suggestEnabled sets $VSCODE_SUGGEST to 1:

vscode/src/vs/platform/terminal/node/terminalEnvironment.ts

Lines 149 to 151 in faacc5f

	if (options.shellIntegration.suggestEnabled) {
	envMixin['VSCODE_SUGGEST'] = '1';
	}

That's read by shell integration and enabled some special pwsh key handlers, including for the - key:

vscode/src/vs/workbench/contrib/terminal/browser/media/shellIntegration.ps1

Lines 156 to 157 in faacc5f

	# Conditionally enable suggestions
	if ($env:VSCODE_SUGGEST -eq '1') {

Some vscode-side keybindings send custom sequences to pwsh which are understood by the key handlers (this ctrl+space keybinding seems to have broken somehow since I initially added it:

vscode/src/vs/workbench/contrib/terminal/browser/terminal.contribution.ts

Lines 204 to 208 in faacc5f

	registerSendSequenceKeybinding('\x1b[24~e', { // F12,e -> ctrl+space (Native suggest)
	when: ContextKeyExpr.and(TerminalContextKeys.focus, ContextKeyExpr.equals(TerminalContextKeyStrings.ShellType, WindowsShellType.PowerShell), TerminalContextKeys.terminalShellIntegrationEnabled, CONTEXT_ACCESSIBILITY_MODE_ENABLED.negate(), ContextKeyExpr.equals(`config.${TerminalSettingId.ShellIntegrationSuggestEnabled}`, true)),
	primary: KeyMod.CtrlCmd | KeyCode.Space,
	mac: { primary: KeyMod.WinCtrl | KeyCode.Space }
	});

When suggest is triggered, we trigger TabExpansion2 and form a custom vscode escape sequence:

vscode/src/vs/workbench/contrib/terminal/browser/media/shellIntegration.ps1

Lines 183 to 205 in faacc5f

	function Send-Completions {
	$commandLine = ""
	$cursorIndex = 0
	# TODO: Since fuzzy matching exists, should completions be provided only for character after the
	# last space and then filter on the client side? That would let you trigger ctrl+space
	# anywhere on a word and have full completions available
	[Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState([ref]$commandLine, [ref]$cursorIndex)
	$completionPrefix = $commandLine
	# Get completions
	$result = "`e]633;Completions"
	if ($completionPrefix.Length -gt 0) {
	# Get and send completions
	$completions = TabExpansion2 -inputScript $completionPrefix -cursorColumn $cursorIndex
	if ($null -ne $completions.CompletionMatches) {
	$result += ";$($completions.ReplacementIndex);$($completions.ReplacementLength);$($cursorIndex);"
	$result += $completions.CompletionMatches | ConvertTo-Json -Compress
	}
	}
	$result += "`a"
	Write-Host -NoNewLine $result
	}

This is handled by vscode here:

vscode/src/vs/workbench/contrib/terminalContrib/suggest/browser/terminalSuggestAddon.ts

Lines 123 to 125 in faacc5f

	case VSCodeOscPt.Completions:
	this._handleCompletionsSequence(this._terminal, data, command, args);
	return true;

The completions are fed into a suggest widget derived from the editor's intellisense widget.

[alessandro-newzoo]

@alessandro-newzoo it will only work on the latest insiders build released today, just setting that should make it work. It's triggered by typing - currently.

Here's roughly how it works:

terminal.integrated.shellIntegration.suggestEnabled sets $VSCODE_SUGGEST to 1:

vscode/src/vs/platform/terminal/node/terminalEnvironment.ts

Lines 149 to 151 in faacc5f

	if (options.shellIntegration.suggestEnabled) {
	envMixin['VSCODE_SUGGEST'] = '1';
	}

That's read by shell integration and enabled some special pwsh key handlers, including for the - key:

vscode/src/vs/workbench/contrib/terminal/browser/media/shellIntegration.ps1

Lines 156 to 157 in faacc5f

	# Conditionally enable suggestions
	if ($env:VSCODE_SUGGEST -eq '1') {

Some vscode-side keybindings send custom sequences to pwsh which are understood by the key handlers (this ctrl+space keybinding seems to have broken somehow since I initially added it:

vscode/src/vs/workbench/contrib/terminal/browser/terminal.contribution.ts

Lines 204 to 208 in faacc5f

	registerSendSequenceKeybinding('\x1b[24~e', { // F12,e -> ctrl+space (Native suggest)
	when: ContextKeyExpr.and(TerminalContextKeys.focus, ContextKeyExpr.equals(TerminalContextKeyStrings.ShellType, WindowsShellType.PowerShell), TerminalContextKeys.terminalShellIntegrationEnabled, CONTEXT_ACCESSIBILITY_MODE_ENABLED.negate(), ContextKeyExpr.equals(`config.${TerminalSettingId.ShellIntegrationSuggestEnabled}`, true)),
	primary: KeyMod.CtrlCmd | KeyCode.Space,
	mac: { primary: KeyMod.WinCtrl | KeyCode.Space }
	});

When suggest is triggered, we trigger TabExpansion2 and form a custom vscode escape sequence:

vscode/src/vs/workbench/contrib/terminal/browser/media/shellIntegration.ps1

Lines 183 to 205 in faacc5f

	function Send-Completions {
	$commandLine = ""
	$cursorIndex = 0
	# TODO: Since fuzzy matching exists, should completions be provided only for character after the
	# last space and then filter on the client side? That would let you trigger ctrl+space
	# anywhere on a word and have full completions available
	[Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState([ref]$commandLine, [ref]$cursorIndex)
	$completionPrefix = $commandLine
	# Get completions
	$result = "`e]633;Completions"
	if ($completionPrefix.Length -gt 0) {
	# Get and send completions
	$completions = TabExpansion2 -inputScript $completionPrefix -cursorColumn $cursorIndex
	if ($null -ne $completions.CompletionMatches) {
	$result += ";$($completions.ReplacementIndex);$($completions.ReplacementLength);$($cursorIndex);"
	$result += $completions.CompletionMatches | ConvertTo-Json -Compress
	}
	}
	$result += "`a"
	Write-Host -NoNewLine $result
	}

This is handled by vscode here:

vscode/src/vs/workbench/contrib/terminalContrib/suggest/browser/terminalSuggestAddon.ts

Lines 123 to 125 in faacc5f

	case VSCodeOscPt.Completions:
	this._handleCompletionsSequence(this._terminal, data, command, args);
	return true;

The completions are fed into a suggest widget derived from the editor's intellisense widget.

oh okay I see, thank you so much for the thorough explaination!
Weird that this setting terminal.integrated.shellIntegration.suggestEnabled has been there in Stable for so long then, why is it even there?

[cpendery]

Curious if after #210289 we could enable is by default in Insiders? I've been using it for the past few weeks and haven't found any other issues. Thoughts? @Tyriar

[Tyriar]

@alessandro-newzoo sorry about the slow response, but it's been available as an experimental setting for some time but I was pulled off the project to work on some other things. In retrospect it should have remained as an Insiders-only setting back then, but now thanks to @cpendery's work it's becoming more reliable.

@cpendery I switched it on and it still had some problems where it would brick input where you could not interact with the suggest widget or the terminal and not close it. Not sure if that's been fixed yet but that's why it was switched off. I've got it enabled now and I was seeing that problem so hopefully I'll hit it again and be able to diagnose.

It's also not clear if we will have it enabled by default in the future and it might be too disruptive for users to enable it in Insiders. I want suggest to be available as a discoverable option but not necessarily the default experience. The best next step to get more self-hosting will probably be to enable it in the vscode repo, I'll try get some testing in over the next week and we can maybe create a test plan item to get some new eyes on it for this release.

[Tyriar]

Created a test plan item: #210394

[Tyriar]

A lot of good feedback from testing: https://github.com/microsoft/vscode/issues?q=is%3Aopen+is%3Aissue+label%3Aterminal-suggest

[Tyriar]

Closing this as we will be moving away from the pwsh native approach and instead going for the terminal-suggest built-in extension to provide completions. See #226562, https://github.com/microsoft/vscode/issues?q=is%3Aopen+is%3Aissue+label%3Aterminal-suggest