Please report XTVERSION in response to CSI > 0 q or set TERM to something other than xterm (or both)

[chaosemer]

Description of the new feature

Ideally I think Windows Terminal would set the environment variable TERM to a unique value and also update the existing terminfo databases. However, I understand that the intermediate state that creates where many programs don't recognize the new terminal type is undesirable.

So in the meantime, can Windows Terminal report XTVERSION? From ctlseqs:

CSI > Ps q
            Ps = 0  ⇒  Report xterm name and version (XTVERSION).
          The response is a DSR sequence identifying the version:
            DCS > | text ST

This escape sequence is pretty widely supported to send a unique string that identifies the name and version of a terminal. Off the top of my head, VTE-based terminals (such as GNOME Terminal), Konsole, iTerm2, WezTerm, Contour, and kitty all support this escape sequence.

Context: I am currently drafting up a patch to Emacs that will rely either TERM or XTVERSION to determine if xterm-mouse-mode is safe to be enabled by default. Emacs wants to see support fo OSC52 copy, bracketed paste, DECSET1000, and DECSET1003 at a minimum and checking XTVERSION or TERM is the only way I have to identify if these escape sequences are supported. Also see Emacs discussion thread.

Proposed technical implementation details

No response

[DHowett]

Thanks for the report! Unfortunately, we're not the ones setting TERM...

Even so, we strive for some measure of xterm compatibility. There's a lot of discussion over in #1040 that I won't rehash over here, but suffice it to say that we're in a less-than-ideal situation.

Therefore, we definitely should report something for XTVERSION. 🙂

[chaosemer]

When this gets addressed, please share the format used so I can add Windows Terminal to Emacs' list. Windows Terminal otherwise supports all necessary functionality and as it is becoming the dominant terminal on Windows I would like for it to work by default.

There are two response formats I've seen for the string:

NAME VERSION, like "iTerm2 3.5.10" NAME(VERSION), like "kitty(0.38.1)"

Either is fine for parsing, Emacs is matching a regular expression to extract the terminal program name. I think the second version (with parenthesis) is slightly more often used.

[DHowett]

One interesting wrinkle here is that we have three or more distributions that all offer the same VT support. Ideally we would avoid XTVERSION becoming another User-Agent, but we have:

• The Windows inbox console host, versioned with windows
  • conhost(10.0.19041.0)
• The console host as built out of this repository, versioned with Terminal
  • conhost(1.22.3651.0) or equivalent version conhost(1.22.2412.31001) (bah)
• The terminal application shipped out of this repository, versioned as itself
  • WindowsTerminal(1.22.3651.0) or equivalent above

These are, if I squint, just fine. The Windows version one is annoying because we have not (yet!) documented the effective version equivalence between Windows and Terminal. We can and should. The fourth distribution sucks:

• The reusable Terminal UI control, shipped in Visual Studio or [insert app here], versioned with Terminal
  • TerminalControl(1.22.xyz.abc); however, it may be important for the application hosting the reusable terminal control to indicate what they are, because they can control (to an extent) which terminal features are available.
    • VisualStudio(17.4.3)+TerminalControl(1.22.xyz.abc)

NB: I am not currently signing up for any of these names or semantics; examples above are illustrative.

I wonder how libvte handles this.

@j4james is there prior art you can think of for this report?

[j4james]

I know at one point VTE were considering how this would interact with the terminals that depend on their library, and they discussed potentially having something like VTE 0.78.2 (GNOME Terminal 3.36.0). But as of right now I think they simply report VTE(7802).

Personally I think we should jump straight to something like

Mozilla/5.0 (Windows Terminal 1.22; Win64) XTerm(397) VTE(7820) Konsole iTerm2

Because that's likely what it's going to devolve into in the long term. At the very least we should make it an editable option so users can override it when they need to get the terminal working with some stupid app that is hardcoded to only work with a specific set of XTVERSION responses.

[chaosemer]

You forgot the "(like VTE)" part of the user agent. Clearly it's Mozilla/5.0 (Windows Terminal 1.22 like iTerm2; Win64) Konsole. (The previous sentence is a joke.)

My observation is aligned about VTE. VTE terminals all respond with just "VTE(7592)" and no other details about the wrapping program. So maybe something like WindowsTerminalControl(9001) is sufficient, similar to VTE.

I separately have ideas about creating a probing mode where each escape sequence can get a reply from a terminal if it is supported or not. However for that to be useful it would require multiple terminals to all adopt this escape sequence which will take much longer than just this one feature request. :)

[j4james]

I separately have ideas about creating a probing mode where each escape sequence can get a reply from a terminal if it is supported or not.

Most of the functionality you need to query can already be probed with existing standards. For example, all of the modes you referenced above can already be queried with DECRQM.

The only thing that isn't currently detectable is OSC 52, and that could easily be added to something like the DA report if a few terminals could be persuaded to agree on a number, and perhaps a minimum level of functionality. That's more sensible than you trying to manage a constantly growing list of terminal names and version numbers, and/or expecting new terminals to notify every application that's using XTVERSION of their existence.

Not to mention the fact that XTVERSION isn't a reliable way of determining whether OSC 52 will work anyway. You may know that a particular terminal supports OSC 52 in general, but you can't tell whether a particular user has disabled that sequence for security reasons.

So maybe something like WindowsTerminalControl(9001) is sufficient, similar to VTE.

As @DHowett mentioned above, there are multiple terminals sharing the VT code base used by Windows Terminal. However, they don't all share the same functionality, so if this value were the same for all of them, and you were using the name for feature detection, it's not going to work. The same thing likely also applies to VTE for that matter.

[hzeller]

I am in favor of being specific, so WindowsTerminalControl(9001) sounds good to me, but a response that contains all kinds of terminal flavors just because someone might attempt to match these is not useful at all.

Case in point: In timg, the XTVERSION query is one of the ways to figure out what potential available features there are. Reporting terminal names that support more features than actually available will result in a bad experience (e.g. Konsole supports iterm2, kitty and sixel image formats, iterm2 supports iterm2 but no other - while windows terminal supports Sixel).

So from a 'I am a user of the information' perspective: being specific is good.

[chaosemer]

Most of the functionality you need to query can already be probed with existing standards. For example, all of the modes you referenced above can already be queried with DECRQM.

The only thing that isn't currently detectable is OSC 52, and that could easily be added to something like the DA report if a few terminals could be persuaded to agree on a number, and perhaps a minimum level of functionality. That's more sensible than you trying to manage a constantly growing list of terminal names and version numbers, and/or expecting new terminals to notify every application that's using XTVERSION of their existence.

How do do I query that DECSET 1000 (mouse button reporting), DECSET 1003 (mouse move reporting), or bracketed paste are supported? I did not see any such capabilities in the linked guide.

Not to mention the fact that XTVERSION isn't a reliable way of determining whether OSC 52 will work anyway. You may know that a particular terminal supports OSC 52 in general, but you can't tell whether a particular user has disabled that sequence for security reasons.

Yes, this is a downside. I certainly would prefer a way to determine the actual support if possible. At the moment, I am only making a judgement based on a reasonably available terminal version (sadly, this is subjective) default behavior. This is clearly going to fail for some users. I expect the number of users surprised to be quite small, though.

[j4james]

How do do I query that DECSET 1000 (mouse button reporting), DECSET 1003 (mouse move reporting), or bracketed paste are supported?

The private request format is CSI ? Pd $ p where Pd is the mode number you want to query, so you'd query mouse button reporting with something like this (just using bash syntax here to demonstrate):

echo -en '\033[?1000$p'; read

For mouse move reporting replace 1000 with 1003. For bracketed paste, replace it with 2004.

The expected response from the terminal is described in DECRPM, and for private modes is CSI ? Pd ; Ps $ y where Pd is the mode number you just queried, and Ps is its current state.

If Ps is 0, the mode isn't supported, and you'd see a response like this:

^[[?1000;0$y

If it is supported, then Ps would typically be 1 or 2, depending on whether it's set or reset at that point in time, so you might see something like this:

^[[?1000;2$y

And while unlikely for mouse modes, Ps could potentially also be 3 or 4 to indicate a mode that is locked in a particular state. How you deal with that would depend on what you intend to do with the mode.

Also bear in mind that some terminals may not support DECRQM, so you may not receive a response at all.

[chaosemer]

Thanks, the DECRQM queries seem to be reasonably widely supported. In my experiment, some terminals (such as iTerm2) reply with 4 for modes that it doesn't recognize which is non-standard, but fine for this use case.

That still doesn't eliminate the need for XTVERSION support though, at least until there's a widely supported way to query for OSC52 support.

[krobelus]

On Sun, Jan 12, 2025 at 10:45:39PM -0800, Jared Finder wrote:

That still doesn't eliminate the need for XTVERSION support though, at least until there's a widely supported way to query for OSC52 support.

Not arguing against XTVERSION feature but do you actually need to query for it? You could write OSC52 copy commands unconditionally. fish has been doing that for a couple of years and I haven't heard of any issue. Terminals that don't implement an OSC command should ignore it.

Of course in general being able to query would be great. I'd query the Ms terminfo capability via XTGETTCAP (#17735). That will work across SSH and container boundaries.

(Of course XTGETTCAP doesn't solve the invalidation problem when terminals successively connect to the same tmux instance but that needs a different fix.)

[chaosemer]

XTGETTCAP would be good too. I guess I would like whichever one comes first with a preference for XTGETTCAP as it is more precise.

[j4james]

This is somewhat off topic, but just on the subject of OSC 52 detection, I had an idea which I think would be quite easy for terminals to support, which doesn't require a brand new protocol, and which doesn't require apps to maintain a hardcoded list of supported terminal names and version numbers.

Here is how it works: Terminals that already support both copy and paste don't need to do anything new, but terminals that only support copying would need to be updated to respond to paste requests with a blank OSC 52 report, instead of just ignoring the request.

An app could then detect clipboard support just by sending an OSC 52 sequence to set the clipboard with a unique value, immediately followed by another OSC 52 sequences to read back the clipboard contents. The possible responses are as follows:

1. Terminals that support copy and paste will return the unique value that was copied.
2. Terminals that support copy but not paste will return an empty clipboard response.
3. Terminals that support neither, will not respond at all.

This is a protocol that apps could already start using immediately, and at least detect terminals from the first category. You can't yet tell the difference between case 2 and 3, but over time that would improve if copy-only terminals were to adopt this approach.

The only downside I can think of is that there are some terminals that prompt the user whenever an app tries to paste from the clipboard, so that could be annoying if your app always triggers a paste request on startup. However, I think that could be fixed by the terminal making an exception for a paste request that immediately followed a copy, without making the terminal any less secure.

There may still be other issues that I haven't considered, but it seems to me that this could be an easier proposal to get terminals to adopt than something like XTGETTCAP.

[jerch]

We kinda have a similar issue in xterm.js - since it is more like a terminal lib toolkit meant to be used by integrators for their own customization a hard linked version string may be good enough to at least grasp basic functionality (mostly unaltered usage) or worst case may give apps a totally wrong idea. This gets further complicated by addons, that may or may not have been added (e.g. OSC52 is an addon). And last but not least, users can decide to switch on/off certain functionality.

@j4james Your protocol idea with OSC52 also would not work with xterm.js, as browsers have their own saying about clipboard access and will always ask the user on startup (and will re-ask after some time, which is a major drawback in browsers for clipboard console apps).

We haven't solved this issue at all, not even XTVERSION is implemented. I am really curious, how others would solve this under this highly configurable multilevel setup constraints. To me it seems, that only an active request-response sequence with a clear notion, whether xy is supported, can help here. (e.g. DECRQM for core stuff, putting OSC52 in DA as @j4james already suggested above).

[j4james]

@jerch I only suggested the OSC 52 query idea because nobody seem interested in my DA proposal, but if you're onboard with that I'd be more than happy to push it further. I think there's a good chance we'd be able to get Contour and DomTerm to support it, since they both already report custom DA features. And if all three of you are supporting it, I'll have a good case to argue for Windows Terminal to support it too.

At that point, I think it'll be easier to get a few other to follow: Foot, Mintty, and WezTerm are all likely candidates. I wouldn't expect to convince everyone, but even if it's just four terminals, that ought to be enough to convince apps to make use of it. They're all likely to be querying DA anyway, so it's hardly any effort to throw in an additional extension check.

[jerch]

@j4james Yupp, imho DA is the most appropriate in the standard sequences for OSC52 (I really dont want to get into "lets shape a new sequence" business, as it is kinda always doomed to fail on the adoption side).

Before we can get there, there are a few things to discuss in detail, like which identifier to use etc. Should we make a new issue for that, as it is only loosely coupled to the thread topic here?

[j4james]

@jerch I was thinking it might be best to move this to the Contour tracker, since Christian is always open for discussing things like this, and it feels like more of a neutral ground. 100% agree on not wanting to get into the new sequence business.

[j4james]

@chaosemer Just to followup on the comments above, Windows Terminal now identifies support for copying to the clipboard with the parameter value 52 in its primary device attributes report. This is an extension that is also already supported in nightly builds of Bobcat, Contour, Foot, and WezTerm.

Terminals that have the ability to disable clipboard access will only report the extension when writing to the clipboard is actually allowed (this is something you wouldn't be able to determine with an XTVERSION or XTGETTCAP query).

There's a mini-spec for the extension here: https://github.com/contour-terminal/vt-extensions/blob/master/clipboard-extension.md

Although the adoption state on that page is out of date - there are number of terminals that have recently merged PRs.