NOTICE TO DEVELOPERS:

The Terminal classes are very sensitive to change, partially because of the complicated way that shell integration works with VSCE, and partially because of the way that Cline interacts with the Terminal* class abstractions that make VSCE shell integration easier to work with.

At the point that PR #1365 is merged, it is unlikely that any Terminal* classes will need to be modified substantially. Generally speaking, we should think of this as a stable interface and minimize changes.

TerminalProcess class is particularly critical because it provides all input handling and event notifications related to terminal output to send it to the rest of the program. User interfaces for working with data from terminals should only be as follows:

1. By listening to the events:

   • this.on("completed", fullOutput) - provides full output upon completion
   • this.on("line") - provides new lines, probably more than one

2. By calling this.getUnretrievedOutput()

This implementation intentionally returns all terminal output to the user interfaces listed above. Any throttling or other stream modification must be implemented outside of this class.

All other interfaces are private.

Warning: Modifying the TerminalProcess class without fully understanding VSCE shell integration architecture may affect the reliability or performance of reading terminal output.

TerminalProcess was carefully designed for performance and accuracy:

Performance is obtained by: - Throttling event output on 100ms intervals - Using only indexes to access the output array - Maintaining a zero-copy implementation with a fullOutput string for storage - The fullOutput array is never split on carriage returns as this was found to be very slow - Allowing multi-line chunks - Minimizing regular expression calls, as they have been tested to be 500x slower than the use of string parsing functions for large outputs in this implementation

Accuracy is obtained by: - Using only indexes against fullOutput - Paying close attention to off-by-one errors when indexing any content - Always returning exactly the content that was printed by the terminal, including all carriage returns which may (or may not) have been in the input stream

Additional resources:

• This implementation was rigorously tested using:

  • https://github.com/KJ7LNW/vsce-test-terminal-integration

• There was a serious upstream bug that may not be fully solved, or that may resurface in future VSCE releases, simply due to the complexity of reliably handling terminal-provided escape sequences across multiple shell implementations. This implementation attempts to work around the problems and provide backwards compatibility for VSCE releases that may not have the fix in upstream bug #237208, but there still may be some unhandled corner cases. See this ticket for more detail:

  • microsoft/vscode#237208

• The original Cline PR has quite a bit of information:

  • cline/cline#1089

Contact me if you have any questions: - GitHub: KJ7LNW - Discord: kj7lnw - [roo-cline at z.ewheeler.org]

Cheers, -Eric, KJ7LNW