terminal_helpers.ts

Formats a command and its args as the line typed into the terminal's shell. Each arg follows a space, except one that starts with whitespace, which carries its own separator — how parse_terminal_command keeps a typed line verbatim.

Splits a typed command line, trimmed, into its first whitespace-delimited word — the command, used for display and a preset's default name — and the rest of the line verbatim, whitespace separator included, as the one arg. The terminal types the line into sh (see format_terminal_command), so nothing is parsed here: quotes, comments, and unterminated lines are the shell's to interpret, and the line it gets is exactly the trimmed line that was typed.

How long (ms) consumed output under the threshold waits to be acked.

How long (ms) before a failed ack is sent again.

Consumed output a terminal acks at once rather than after TERMINAL_ACK_DELAY — see TerminalOutputAcker.

It must not exceed the backend's low-water mark (256 KiB, the unacked output at or under which a paused terminal reads again). While the backend holds a terminal paused, more than that mark is unacked; so a client that has consumed everything it was sent has at least this much waiting, and acks at once instead of leaving the process blocked for the delay. The cross-backend terminal suite pins the relation against the backend.

Max characters of input queued per terminal while a send is in flight or waiting to retry. Input past this is refused and surfaced, not queued.

Why a terminal is lost when a session snapshot from a restarted backend lacks it.

Why a terminal is lost when a session snapshot from the same backend lacks it — it exited, or was closed from another tab, while the connection was down.

Why a terminal is lost when the backend answers not_found for it.

Max characters of output kept per terminal for replay into a (re)mounted view. Counted in UTF-16 code units — about 1-2 MB of memory. The oldest output is dropped first.

How a terminal_ack ended: ok, retry (it failed and is worth sending again), or stop (the backend no longer has the terminal).

Batches one terminal's output acks. The backend stops reading a terminal whose output runs too far ahead of what this client has acked, so acks must keep up with consumption without doubling the message rate.

Counts are the backend's: each terminal_data carries sent_bytes, the terminal's running output total, and an ack echoes the sent_bytes of the last chunk consumed. Acks are cumulative, so a lost one is covered by the next.

An ack is sent at once when threshold_bytes of consumed output are waiting, and after delay when fewer are — so the last of a burst is always acked. At most one ack is in flight: output consumed meanwhile waits for it to return and is then acked by the same rule, so under a flood acks go out per threshold_bytes consumed, not per round trip (each ack is a request the backend runs in a transaction).

Acks can't stall a terminal the backend has paused, as long as threshold_bytes is at most the backend's low-water mark (see TERMINAL_ACK_THRESHOLD_BYTES): once everything sent is consumed, at least the threshold is waiting, and the ack goes out at once or as soon as the one in flight returns. delay bounds every other case. Not reactive.

Bounded buffer of terminal output chunks — keeps about the most recent max_length characters, dropping the oldest first. Not reactive.

Trimming cuts after a newline where the oldest chunk has one past the trim point, and otherwise drops that whole chunk, so a replay starts at a line or chunk boundary rather than at an arbitrary character. Backend chunk boundaries are arbitrary too, so a replay can still start inside an escape sequence — xterm's parser starts in its ground state and prints the tail of the sequence as text.