Finalize shell integration sequences

[Tyriar]

This issue tracks cleaning up the shell integration sequences, documenting and encouraging third parties to use the sequences.

Possible users:

• Windows Terminal (cc @zadjii-msft)
• Powershell vscode ext (cc @andschwa, @SeeminglyScience)
• Julia vscode ext (cc @pfitzseb)
• powerlevel10k (cc @romkatv)
• Python vscode ext
• Third party shell integration scripts (eg. if the fish community wanted to create a script Support fish shell integration automatic injection #139400)

Some things to look into:

• The continuation (F, G) and right prompt (H, I) sequences are not thoroughly tested, we should investigate whether we need these at all considering.
• Review and document all known properties (P)?
  • Should we support one of the common cwd properties instead of roll our own? Hostname and different sequences for different operating systems were some of the complications here.
  • How should cwds be treated in ssh where VS Code's shell integration is installed?
  • The Task should should be more generic
• Improve command line (E) serialization of special characters
• Should 633 A-D be removed in favor of 133 A-D? p10k works in a degraded state when sending these, if it also sent E (and P?) would it be fully functional?

The current sequences are lightly documented in code here:

vscode/src/vs/platform/terminal/common/xterm/shellIntegrationAddon.ts

Lines 54 to 118 in f8aeb20

	/**
	* VS Code-specific shell integration sequences. Some of these are based on common alternatives like
	* those pioneered in FinalTerm. The decision to move to entirely custom sequences was to try to
	* improve reliability and prevent the possibility of applications confusing the terminal.
	*/
	const enum VSCodeOscPt {
	/**
	* The start of the prompt, this is expected to always appear at the start of a line.
	* Based on FinalTerm's `OSC 133 ; A ST`.
	*/
	PromptStart = 'A',
	/**
	* The start of a command, ie. where the user inputs their command.
	* Based on FinalTerm's `OSC 133 ; B ST`.
	*/
	CommandStart = 'B',
	/**
	* Sent just before the command output begins.
	* Based on FinalTerm's `OSC 133 ; C ST`.
	*/
	CommandExecuted = 'C',
	/**
	* Sent just after a command has finished. The exit code is optional, when not specified it
	* means no command was run (ie. enter on empty prompt or ctrl+c).
	* Based on FinalTerm's `OSC 133 ; D [; <ExitCode>] ST`.
	*/
	CommandFinished = 'D',
	/**
	* Explicitly set the command line. This helps workaround problems with conpty not having a
	* passthrough mode by providing an option on Windows to send the command that was run. With
	* this sequence there's no need for the guessing based on the unreliable cursor positions that
	* would otherwise be required.
	*/
	CommandLine = 'E',
	/**
	* Similar to prompt start but for line continuations.
	*/
	ContinuationStart = 'F',
	/**
	* Similar to command start but for line continuations.
	*/
	ContinuationEnd = 'G',
	/**
	* The start of the right prompt.
	*/
	RightPromptStart = 'H',
	/**
	* The end of the right prompt.
	*/
	RightPromptEnd = 'I',
	/**
	* Set an arbitrary property: `OSC 633 ; P ; <Property>=<Value> ST`, only known properties will
	* be handled.
	*/
	Property = 'P'
	}

[Tyriar]

PR is out for the VS Code side of this #157571

Here are the answers to the questions above:

• The continuation (F, G) and right prompt (H, I) sequences are not thoroughly tested, we should investigate whether we need these at all considering.
  • These are no being finalized as they're barely used right now
• Review and document all known properties (P)?
  • IsWindows and Cwd will be finalized only
• Should we support one of the common cwd properties instead of roll our own? Hostname and different sequences for different operating systems were some of the complications here.
  • Yes, we should support these in addition to our own (see Finalize VS Code shell integration sequences in code #157571)
• How should cwds be treated in ssh where VS Code's shell integration is installed?
  • This is a problem we can solve in time with backwards compatible changes
• The Task should should be more generic
  • This will not be finalized
• Improve command line (E) serialization of special characters
  • Moving to \xAB hex representation as most developers are aware of
• Should 633 A-D be removed in favor of 133 A-D? p10k works in a degraded state when sending these, if it also sent E (and P?) would it be fully functional?
  • The justification to keep these is in Finalize VS Code shell integration sequences in code #157571

[andyleejordan]

Thanks for doing this @Tyriar!

[pfitzseb]

#15751 makes it sounds like all ASCII chars should be replaced by their char codes, but that's only strictly necessary for '\n' and ';', plus escaping of backslashes. Would it make sense to specify that in the docs?

[Tyriar]

@pfitzseb will clarify 👍

[Tyriar]

With the 2 PRs I'll call this closed, still open to feedback. The website docs will be covered in microsoft/vscode-docs#4809, until then the in code comments are the main documentation.