Expose an indicator on terminals indicating whether they've been interacted with

[connor4312]

This came to mind as something I was talking about with Kai a while ago. Currently when you create a debug terminal, users can get a debug "flash" when the terminal opens: this comes from nvm executing an npm script in its initialization. While we could try to do some targeting based on the command and how it's invoked in the debug terminal, this is pretty fragile.

Instead, now that we have "interacted" detection, it would be helpful to expose that on the API so that can we can skip attaching before the user has run anything -- which should solve the generalized case of .*rc scripts nicely.

[Tyriar]

@connor4312 thoughts?

export interface Terminal {
  /**
   * Whether the terminal has received any input from the user. This value persists across window
   * reloads in the case of terminal reconnection.
   */
  readonly hadFirstInteraction: boolean;
}

namespace window {
  /**
   * An event which fires when a terminal has received input from the user for the first time.
   */
  onDidTriggerTerminalFirstInteraction: Event<Terminal>;
}

[connor4312]

I think the event should be named onDidTriggerFirstTerminalInteraction, since it's on the window. Looks good to me

[Tyriar]

Updated, I put Terminal before First

[Tyriar]

Feedback responses from last week:

Do we have something like this already?

What we do have is data written to the terminal which is different and that’s stuck in proposed for live share

People wondered what interaction means - clicking on the terminal, typing in it?

It may mean clicking, it depends on the terminal mode. We can clarify this in the comment.

terminal states?

Wonder what the other states would be though, we already have exitStatus which is also kind of a state (with additional info in exitCode)

[Tyriar]

After discussing in this API sync I like the state idea, there are 4 states we could potentially start with: opened (process not yet created), connected (process created), interacted (some input was sent to the pty) and exited.

[Tyriar]

API proposal:

	//#region Terminal state event https://github.com/microsoft/vscode/issues/127717

	export enum TerminalState {
		/**
		 * The terminal is created and has starting to connecting to the process. This state is
		 * followed by either Opened or Closed depending on whether the process is successfully
		 * connected to.
		 */
		Opening = 0,
		/**
		 * The terminal has connected to a valid process.
		 */
		Opened = 1,
		/**
		 * The terminal has connected to a valid process and has been interacted with. Interaction
		 * means that the terminal has sent data to the process which depending on the terminal's
		 * _mode_. By default input is sent when a key is pressed but based on the terminal's mode
		 * it can also happen on:
		 *
		 * - a pointer click event
		 * - a pointer scroll event
		 * - a pointer move event
		 * - terminal focus in/out
		 *
		 * For more information on events that can send data see "DEC Private Mode Set (DECSET)" on
		 * https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
		 */
		InteractedWith = 2,
		/**
		 * The terminal has closed, if it had a process it is no longer connected.
		 */
		Closed = 3,
	}

	export interface Terminal {
		state: TerminalState;
	}

	export interface TerminalStateChangeEvent {
		terminal: Terminal;
		state: TerminalState;
	}

	export namespace window {
		export const onDidChangeTerminalState: Event<TerminalStateChangeEvent>;
	}

	//#endregion

[mjbvz]

• InteractedWith -> OpenedAndInteractedWith
• { state: Opened, interactedWith: bool }?
• readonly Terminal .state

[Tyriar]

Thinking about this a little more, we could just strip out the opened/opening/closed states as it's not part of this. If wanted in the future we could add if TerminalState is extensible, but there is already onDidCloseTerminal and Terminal.exitStatus to cover closed/opened and that is not part of this request.

New proposal:

	//#region Terminal state event https://github.com/microsoft/vscode/issues/127717

	/**
	 * Represents the state of a {@link Terminal}.
	 */
	export interface TerminalState {
		/**
		 * Whether the {@link Terminal} has been interacted with. Interaction means that the
		 * terminal has sent data to the process which depending on the terminal's _mode_. By
		 * default input is sent when a key is pressed but based on the terminal's mode it can also
		 * happen on:
		 *
		 * - a pointer click event
		 * - a pointer scroll event
		 * - a pointer move event
		 * - terminal focus in/out
		 *
		 * For more information on events that can send data see "DEC Private Mode Set (DECSET)" on
		 * https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
		 */
		readonly interactedWith: boolean;
	}

	export interface Terminal {
		/**
		 * The current state of the {@link Terminal}.
		 */
		readonly state: TerminalState;
	}

	/**
	 * An event representing a change in a {@link Terminal.state terminal's state}.
	 */
	export interface TerminalStateChangeEvent {
		/**
		 * The {@link Terminal} this event occurred on.
		 */
		readonly terminal: Terminal;
		/**
		 * The {@link Terminal.state current state} of the {@link Terminal}.
		 */
		readonly state: TerminalState;
	}

	export namespace window {
		/**
		 * An {@link Event} which fires when a {@link Terminal.state terminal's state} has changed.
		 */
		export const onDidChangeTerminalState: Event<TerminalStateChangeEvent>;
	}

	//#endregion

[Tyriar]

TPI created #130775, moving to September for finalization

@connor4312 ready for trying out in js-debug

[Tyriar]

Feedback:

• isInteractedWith/hasBeenInteractedWith as it's a boolean
• Remove TerminalStateChangeEvent as there is now a state object: onDidChangeTerminalState: Event<Terminal>

[Tyriar]

Feedback:

• Should we have a Event<TerminalStateChangeEvent> or just use Event<Terminal>? TerminalStateChangeEvent not used #131496

[meganrogge]

@connor4312 any feedback on API?

[Tyriar]

If we move on #133084 there will be more things we could expose on state such as:

• cwd: string | undefined
• acceptingInput: boolean | undefined

[Tyriar]

Good to finalize after making it isInteractedWith, not has as we use is prefix everywhere in API.

[connor4312]

sorry I'm catsitting and she walked on my laptop keyboard.

Adopted the rename in js-debug 👍