Classes

SessionStore

SessionStore - SQLite persistence for session metadata

Constructor

constructor(dbPath: string)

Parameters:

Methods

initialize

Initialize database and create tables

initialize(): void

saveSession

Save a new session

saveSession(session: SessionRecord): void

Parameters:

getSession

Get a session by ID

getSession(sessionId: string): SessionRecord | null

Parameters:

Returns:

SessionRecord \| null -

getAllSessions

Get all sessions

getAllSessions(): SessionRecord[]

Returns:

SessionRecord[] -

updateSession

Update a session

updateSession(sessionId: string, updates: Partial<SessionRecord>): void

Parameters:

deleteSession

Delete a session

deleteSession(sessionId: string): void

Parameters:

close

Close database connection

close(): void

TerminalSessionManager

TerminalSessionManager - Manages persistent terminal sessions with tmux

Features:

• Sessions persist across WebSocket disconnections AND server restarts
• Output captured via tmux pipe-pane
• Session metadata persisted to SQLite
• Idle timeout for cleanup
• Startup reconciliation between DB and live tmux sessions

Constructor

constructor(config?: SessionManagerConfig | undefined)

Parameters:

Methods

initialize

Initialize the session manager Must be called before any other operations

initialize(): Promise<void>

Returns:

Promise<void> -

createSession

Create a new terminal session using tmux

createSession(options?: { sessionId?: string; cols?: number; rows?: number; context?: SessionContext; }): Promise<{ sessionId: string; metadata: SessionMetadata; }>

Parameters:

Returns:

Promise<{ sessionId: string; metadata: SessionMetadata; }> -

getSession

Get session metadata

getSession(sessionId: string): SessionMetadata | undefined

Parameters:

Returns:

SessionMetadata \| undefined -

listSessions

Get all sessions as SessionInfo for clients

listSessions(): SessionInfo[]

Returns:

SessionInfo[] -

hasSession

Check if session exists

hasSession(sessionId: string): boolean

Parameters:

Returns:

boolean -

connectSession

Connect to a session (mark as connected, clear idle timer, attach to tmux)

connectSession(sessionId: string): Promise<string>

Parameters:

Returns:

Promise<string> -

disconnectSession

Disconnect from a session (mark as disconnected, start idle timer)

disconnectSession(sessionId: string): void

Parameters:

closeSession

Close a session (kill tmux session and cleanup)

closeSession(sessionId: string): Promise<void>

Parameters:

Returns:

Promise<void> -

closeAll

Close all sessions (kills tmux sessions)

closeAll(): Promise<void>

Returns:

Promise<void> -

detachAll

Detach from all sessions without killing them Used during server shutdown to preserve sessions for restart

detachAll(): Promise<void>

Returns:

Promise<void> -

write

Write data to a session via tmux

write(sessionId: string, data: string): Promise<void>

Parameters:

Returns:

Promise<void> -

resize

Resize a session's terminal

resize(sessionId: string, cols: number, rows: number): Promise<void>

Parameters:

Returns:

Promise<void> -

rename

Rename a session

rename(sessionId: string, displayName: string): void

Parameters:

updateContext

Update session context and optionally display name Returns the updated metadata if successful, undefined otherwise

updateContext(sessionId: string, context: Partial<SessionContext>, displayName?: string | undefined): SessionMetadata | undefined

Parameters:

Returns:

SessionMetadata \| undefined -

onData

Subscribe to session data events

onData(sessionId: string, callback: (data: string) => void): () => void

Parameters:

Returns:

() => void -

onExit

Subscribe to session exit events

onExit(sessionId: string, callback: (exitCode: number) => void): () => void

Parameters:

Returns:

() => void -

getTmuxAdapter

Get the TmuxAdapter instance (for testing)

getTmuxAdapter(): TmuxAdapter

Returns:

TmuxAdapter -

getSessionStore

Get the SessionStore instance (for testing)

getSessionStore(): SessionStore

Returns:

SessionStore -

isInitialized

Check if initialized

isInitialized(): boolean

Returns:

boolean -

close

Close the session store (for cleanup)

close(): void

TmuxAdapter

TmuxAdapter - Wraps tmux commands for session persistence

Each FlowState shell session runs inside a tmux session named fs-shell-{sessionId}. This allows the PTY to survive server restarts.

Constructor

constructor(options?: { socketPath?: string; historyLimit?: number; })

Parameters:

Methods

verifyTmuxInstalled

Verify tmux is installed and return version

verifyTmuxInstalled(): Promise<string>

Returns:

Promise<string> -

createSession

Create a new tmux session

createSession(sessionId: string, options: { cols: number; rows: number; cwd?: string; shell?: string; }): Promise<void>

Parameters:

Returns:

Promise<void> -

sessionExists

Check if a tmux session exists

sessionExists(sessionId: string): Promise<boolean>

Parameters:

Returns:

Promise<boolean> -

killSession

Kill a tmux session

killSession(sessionId: string): Promise<void>

Parameters:

Returns:

Promise<void> -

listSessions

List all fs-shell-* session IDs (without prefix)

listSessions(): Promise<string[]>

Returns:

Promise<string[]> -

sendInput

Send input to a tmux session

sendInput(sessionId: string, data: string): Promise<void>

Parameters:

Returns:

Promise<void> -

resize

Resize a tmux session pane

resize(sessionId: string, cols: number, rows: number): Promise<void>

Parameters:

Returns:

Promise<void> -

capturePane

Capture pane content (scrollback buffer)

capturePane(sessionId: string, lines?: number | undefined): Promise<string>

Parameters:

Returns:

Promise<string> -

attachSession

Attach to a session and stream output data

attachSession(sessionId: string, onData: (data: string) => void): Promise<() => void>

Parameters:

Returns:

Promise<() => void> - Cleanup function to stop streaming

detachSession

Detach from a session (stop streaming)

detachSession(sessionId: string): Promise<void>

Parameters:

Returns:

Promise<void> -

ShellWebSocketServer

Constructor

constructor(config: ShellServerConfig)

Parameters:

Methods

start

start(): Promise<void>

Returns:

Promise<void> -

stop

stop(): Promise<void>

Returns:

Promise<void> -

getHealth

Get health status

getHealth(): HealthResponse

Returns:

HealthResponse -