ketraterm-session/io.github.ketraterm.session/TerminalShellIntegrationState

TerminalShellIntegrationState

class TerminalShellIntegrationState(capacity: Int = DEFAULT_CAPACITY, maxCommandTextLength: Int = DEFAULT_SHELL_INTEGRATION_COMMAND_TEXT_LENGTH, epochMillis: () -> Long = System::currentTimeMillis)

Session-owned OSC 133 shell command timeline.

This model intentionally lives outside terminal core. Core owns bytes already committed to the terminal grid; shell integration markers are host metadata about prompt and command lifecycle. Records are anchored to stable core line identities, not absolute row numbers, so scrollback movement and resize reflow do not detach decorations from the content they describe.

Storage is data-oriented: each command field is a primitive column, records are append-only until bounded eviction, and paint paths consume only projected primitive arrays. All methods are thread-safe. Writers are normally invoked from the serialized session parser path; readers are UI threads that snapshot visible rows before painting.

Parameters

capacity

maximum retained command records before oldest-record eviction.

maxCommandTextLength

maximum retained UTF-16 command-text length per record; longer extracted text is stored as unknown.

epochMillis

wall-clock source used for command metadata timestamps.

Constructors

TerminalShellIntegrationState

constructor(capacity: Int = DEFAULT_CAPACITY, maxCommandTextLength: Int = DEFAULT_SHELL_INTEGRATION_COMMAND_TEXT_LENGTH, epochMillis: () -> Long = System::currentTimeMillis)

Functions

clear

fun clear()

Clears all stored prompt and command timeline records.

commandAnchorLineId

fun commandAnchorLineId(recordId: Int): Long

Returns the preferred navigation anchor line for recordId.

commandMetadata

fun commandMetadata(recordId: Int): TerminalShellIntegrationCommandMetadata?

Returns an immutable metadata snapshot for recordId.

commandRecordIdAtLine

fun commandRecordIdAtLine(lineId: Long): Int

Returns the retained command record that owns lineId.

commandText

fun commandText(recordId: Int): String?

Returns the retained command text for recordId.

commandWorkingDirectoryUri

fun commandWorkingDirectoryUri(recordId: Int): String?

Returns the OSC 7 working-directory URI snapshotted when recordId began.

copyCommandOutputRange

fun copyCommandOutputRange(recordId: Int, destination: LongArray, destinationOffset: Int = 0): Boolean

Copies the command-output line range for recordId.

copyRecords

fun copyRecords(recordIds: IntArray, lifecycleStates: IntArray, promptStartLineIds: LongArray, promptEndLineIds: LongArray, commandStartLineIds: LongArray, commandEndLineIds: LongArray, exitCodes: IntArray, destinationOffset: Int, maxRecords: Int): Int

Copies retained shell command records into caller-owned primitive arrays.

copyViewport

fun copyViewport(lineIds: LongArray, rowCount: Int, promptStarts: BooleanArray, commandStarts: BooleanArray, commandEnds: BooleanArray, commandRecordIds: IntArray, commandLifecycleStates: IntArray, failedCommandRails: BooleanArray? = null, destinationOffset: Int = 0)

Copies projected shell decorations for a visible viewport.

currentWorkingDirectoryUri

fun currentWorkingDirectoryUri(): String?

Returns the latest accepted OSC 7 URI, or null before one is received.