ketraterm-session/io.github.ketraterm.session/TerminalSession

TerminalSession

class TerminalSession(val terminal: TerminalBuffer, val renderPublisher: TerminalRenderPublisher, renderReader: TerminalRenderFrameReader, responseReader: TerminalHostResponseReader, connector: TerminalConnector, parser: TerminalOutputParser, inputEncoder: TerminalInputEncoder, hyperlinkResolver: TerminalHyperlinkResolver = TerminalHyperlinkResolver.NONE, outboundWriteLock: Any = Any(), val shellIntegrationState: TerminalShellIntegrationState = TerminalShellIntegrationState(), hostCommandAdapter: HostCommandAdapter? = null, inputPolicy: TerminalInputPolicy = TerminalInputPolicy(), workerDispatcher: CoroutineDispatcher = Dispatchers.Default) : TerminalConnectorListener, TerminalInputEncoder, TerminalRenderFrameReader, AutoCloseable

Runtime terminal session that binds core, parser, input encoding, and a transport connector.

The connector owns transport threads. This session owns parser/core mutation serialization and all host-bound write ordering.

A session publishes one active render viewport. Two independently scrolling renderers must use separate sessions so their viewport requests do not race.

Constructors

TerminalSession

constructor(terminal: TerminalBuffer, renderPublisher: TerminalRenderPublisher, renderReader: TerminalRenderFrameReader, responseReader: TerminalHostResponseReader, connector: TerminalConnector, parser: TerminalOutputParser, inputEncoder: TerminalInputEncoder, hyperlinkResolver: TerminalHyperlinkResolver = TerminalHyperlinkResolver.NONE, outboundWriteLock: Any = Any(), shellIntegrationState: TerminalShellIntegrationState = TerminalShellIntegrationState(), hostCommandAdapter: HostCommandAdapter? = null, inputPolicy: TerminalInputPolicy = TerminalInputPolicy(), workerDispatcher: CoroutineDispatcher = Dispatchers.Default)

Types

Companion

object Companion

Properties

activeShellCommandLineRevision

val activeShellCommandLineRevision: StateFlow<Long>

Revision of the active shell command line, tracked only while collected.

exitCode

val exitCode: Int?

Remote process exit code after onClosed receives one.

failure

val failure: Throwable?

Transport failure reported by onError, or null when the remote closed normally or the session was locally closed.

isClosed

val isClosed: Boolean

Returns true after either local shutdown, remote closure, or transport failure has made the session unable to accept more input.

renderGeneration

val renderGeneration: StateFlow<Long>

Latest successfully published render generation, or -1 before the first frame is available.

renderPublisher

val renderPublisher: TerminalRenderPublisher

the render publisher responsible for frame updates.

shellIntegrationState

val shellIntegrationState: TerminalShellIntegrationState

shared host-side prompt and command marker state.

state

val state: StateFlow<TerminalSessionState>

Lifecycle state retained for current and future collectors.

terminal

val terminal: TerminalBuffer

public terminal buffer mutated by host output.

Functions

activeShellCommandLine

fun activeShellCommandLine(): TerminalShellCommandLineSnapshot?

Returns the active shell command-line snapshot, when OSC 133 prompt markers provide a trustworthy visible range.

open override fun close()

Requests local connector shutdown and closes parser input exactly once.

currentWorkingDirectoryUri

fun currentWorkingDirectoryUri(): String?

Returns the latest valid OSC 7 current-working-directory URI.

encodeFocus

open override fun encodeFocus(event: TerminalFocusEvent)

Encodes a focus event and writes it to the connector unless closed.

encodeKey

open override fun encodeKey(event: TerminalKeyEvent)

encodeMouse

open override fun encodeMouse(event: TerminalMouseEvent)

Encodes a mouse event and writes it to the connector unless closed.

encodePaste

open override fun encodePaste(event: TerminalPasteEvent)

Encodes a paste event and writes it to the connector unless closed.

encodeTextReplacement

open override fun encodeTextReplacement(event: TerminalTextReplacementEvent)

Encodes a complete text replacement under one outbound lock acquisition.

hyperlinkUri

fun hyperlinkUri(hyperlinkId: Int): String?

Resolves a primitive render-frame hyperlink id to a target URI.

onBytes

open override fun onBytes(bytes: ByteArray, offset: Int, length: Int)

Consumes host bytes synchronously, mutating parser/core before returning.

onClosed

open override fun onClosed(exitCode: Int?)

Records remote closure and closes the parser exactly once.

onError

open override fun onError(error: Throwable)

Records transport failure and treats it as remote closure without a process exit code.

readRenderFrame

open override fun readRenderFrame(consumer: TerminalRenderFrameConsumer)

Reads a short-lived render frame while holding the terminal mutation lock.

open override fun readRenderFrame(scrollbackOffset: Int, consumer: TerminalRenderFrameConsumer)

Reads a render frame with a specified scrollback offset.

open override fun readRenderFrame(scrollbackOffset: Int, viewportRows: Int, consumer: TerminalRenderFrameConsumer)

Reads a render frame with a specified scrollback offset and viewport rows limit.

readRenderFrameForAbsoluteRange

open override fun readRenderFrameForAbsoluteRange(startAbsoluteRow: Long, endAbsoluteRow: Long, consumer: TerminalRenderFrameConsumer)

Reads an absolute terminal row range while holding the mutation lock.

requestRender

fun requestRender(scrollbackOffset: Int)

Requests a render-cache publication for a caller-owned scrollback viewport.

fun requestRender(scrollbackOffset: Int, viewportRows: Int)

Requests a render-cache publication with optional render-only viewport overscan rows.

resize

fun resize(columns: Int, rows: Int, oldScrollbackOffset: Int = 0): Pair<Int, Int>

Resizes core and the active connector, then requests a new published frame.

resizeViewport

fun resizeViewport(columns: Int, rows: Int, oldScrollbackOffset: Int = 0): TerminalViewportResizeResult

Resizes the terminal and captures its viewport anchor and history baseline under the same mutation lock before notifying the connector.

setCursorShape

fun setCursorShape(shape: TerminalRenderCursorShape)

Updates the current and default cursor shape for the session.

setHostPolicy

fun setHostPolicy(policy: HostPolicy)

Updates the active host security policy dynamically.

setInputPolicy

open override fun setInputPolicy(policy: TerminalInputPolicy)

Updates the active terminal input policy dynamically.

setPasteSanitizationPolicy

fun setPasteSanitizationPolicy(policy: PasteSanitizationPolicy)

Updates only the active paste sanitization policy.

setThemePalette

fun setThemePalette(palette: TerminalColorPalette)

Sets the theme-configured color palette for the session.

setTreatAmbiguousAsWide

fun setTreatAmbiguousAsWide(enabled: Boolean)

Applies the host's East Asian Ambiguous width policy for future writes.

start

fun start(columns: Int, rows: Int)

Starts the connector after resizing core and transport to columns x rows.