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

TerminalShellIntegrationState

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

Bounded, protocol-neutral terminal projection of shell commands and prompts.

This model intentionally lives outside terminal core. Core owns bytes already committed to the terminal grid; shell commands and prompts 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. One selected shell integration owns publication to this model; it may interpret terminal protocols or adapt a host's existing shell model. Readers never need to know which integration produced the records.

All methods are thread-safe. The producer must serialize its publications, including synchronous listener delivery, to preserve lifecycle event order. Concurrent producers retain storage safety but have no notification ordering guarantee. Observers and revision collectors run outside the storage lock.

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

Unix epoch-millisecond source sampled for command metadata, including abandonment. Hosts may supply their metadata clock domain; these wall-clock timestamps do not measure elapsed duration.

Constructors

TerminalShellIntegrationState

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

Properties

revision

open override val revision: StateFlow<Long>

Invalidation signal for prompt, command, and current-directory metadata.

Functions

addCommandFinishedListener

open override fun addCommandFinishedListener(listener: (TerminalShellIntegrationCommandMetadata) -> Unit): AutoCloseable

Observes future explicit command completions without replay or conflation.

addCurrentWorkingDirectoryListener

open override fun addCurrentWorkingDirectoryListener(listener: (String) -> Unit): AutoCloseable

Observes future changed directory URIs synchronously, without replay.

clear

fun clear()

Clears all stored prompt and command timeline records.

commandAnchorLineId

open override fun commandAnchorLineId(recordId: Int): Long

Returns the preferred navigation anchor line for recordId.

commandMetadata

open override fun commandMetadata(recordId: Int): TerminalShellIntegrationCommandMetadata?

Returns an immutable metadata snapshot for recordId.

commandRecordIdAtLine

open override fun commandRecordIdAtLine(lineId: Long): Int

Returns the retained command record that owns lineId.

commandText

open override fun commandText(recordId: Int): String?

Returns the retained command text for recordId.

commandWorkingDirectoryUri

open override fun commandWorkingDirectoryUri(recordId: Int): String?

Returns the working-directory URI snapshotted when recordId began.

copyCommandBlockRange

open override fun copyCommandBlockRange(recordId: Int, destination: LongArray, destinationOffset: Int = 0): Boolean

Copies the selectable prompt/input-and-output line range for recordId.

copyCommandOutputRange

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

Copies the command-output line range for recordId.

copyRecords

open override 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

open override 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