Interfaces

SessionContext

Session context for scoping and naming

Properties:

Property	Type	Required	Description
`scopedEntityType`	`"project" \| "milestone" \| "task" \| "codebase" \| "workspace" \| undefined`	No	Entity type this session is scoped to
`scopedEntityId`	`string \| undefined`	No	ID of the scoped entity
`displayName`	`string \| undefined`	No	User-provided display name
`workingDirectory`	`string \| undefined`	No	Working directory for the session
`metadata`	`Record<string, any> \| undefined`	No	Additional metadata
`orgId`	`string \| undefined`	No	Organization ID
`workspaceId`	`string \| undefined`	No	Workspace ID
`projectId`	`string \| undefined`	No	Project ID
`milestoneId`	`string \| undefined`	No	Milestone ID
`taskId`	`string \| undefined`	No	Task ID
`serverUrl`	`string \| undefined`	No	Shell server URL (for multi-server setups)

SessionMetadata

Session metadata stored for persistence

Properties:

Property	Type	Required	Description
`sessionId`	`string`	Yes	Unique session identifier
`pid`	`number`	Yes	Process ID of the PTY process
`createdAt`	`string`	Yes	ISO 8601 timestamp when session was created
`lastActivityAt`	`string`	Yes	ISO 8601 timestamp of last activity
`connectionStatus`	`SessionConnectionStatus`	Yes	Current connection status
`cols`	`number`	Yes	Terminal dimensions
`rows`	`number`	Yes
`shellType`	`ShellType`	Yes	Shell type being used
`context`	`SessionContext`	Yes	Session context for scoping and naming
`displayName`	`string`	Yes	Display name (from context or auto-generated)

SessionInfo

Session info returned to clients (subset of metadata)

Properties:

Property	Type	Required
`sessionId`	`string`	Yes
`displayName`	`string`	Yes
`connectionStatus`	`SessionConnectionStatus`	Yes
`createdAt`	`string`	Yes
`lastActivityAt`	`string`	Yes
`context`	`SessionContext`	Yes

SessionManagerConfig

Configuration for session manager

Properties:

Property	Type	Required	Description
`idleTimeoutMs`	`number \| undefined`	No	Idle timeout in milliseconds (default: 30 minutes)
`maxSessions`	`number \| undefined`	No	Maximum number of sessions (default: 10)
`outputBufferLines`	`number \| undefined`	No	Number of output lines to buffer for reconnection (default: 1000)
`persistencePath`	`string \| undefined`	No	Optional file path for session persistence
`tmuxSocketPath`	`string \| undefined`	No	tmux socket path (optional, let tmux decide if not set)
`tmuxHistoryLimit`	`number \| undefined`	No	tmux scrollback history limit (default: 10000)

SessionRecord

Session record stored in SQLite

Properties:

Property	Type	Required
`session_id`	`string`	Yes
`display_name`	`string`	Yes
`created_at`	`string`	Yes
`last_activity_at`	`string`	Yes
`cols`	`number`	Yes
`rows`	`number`	Yes
`shell_type`	`ShellType`	Yes
`working_directory`	`string \| null`	Yes
`scoped_entity_type`	`string \| null`	Yes
`scoped_entity_id`	`string \| null`	Yes
`org_id`	`string \| null`	Yes
`workspace_id`	`string \| null`	Yes
`project_id`	`string \| null`	Yes
`milestone_id`	`string \| null`	Yes
`task_id`	`string \| null`	Yes
`metadata`	`string \| null`	Yes

BaseMessage

Base message interface

Properties:

Property	Type	Required	Description
`type`	`string`	Yes

ListSessionsMessage

Properties:

Property	Type	Required	Description
`type`	`"list"`	Yes

CreateSessionMessage

Properties:

Property	Type	Required
`type`	`"create"`	Yes
`sessionId`	`string \| undefined`	No
`cols`	`number \| undefined`	No
`rows`	`number \| undefined`	No
`context`	`SessionContext \| undefined`	No

ReconnectSessionMessage

Properties:

Property	Type	Required	Description
`type`	`"reconnect"`	Yes
`sessionId`	`string`	Yes

DataMessage

Properties:

Property	Type	Required
`type`	`"data"`	Yes
`sessionId`	`string`	Yes
`data`	`string`	Yes

ResizeMessage

Properties:

Property	Type	Required
`type`	`"resize"`	Yes
`sessionId`	`string`	Yes
`cols`	`number`	Yes
`rows`	`number`	Yes

DisconnectMessage

Properties:

Property	Type	Required	Description
`type`	`"disconnect"`	Yes
`sessionId`	`string`	Yes

CloseSessionMessage

Properties:

Property	Type	Required	Description
`type`	`"close"`	Yes
`sessionId`	`string`	Yes

RenameSessionMessage

Properties:

Property	Type	Required
`type`	`"rename"`	Yes
`sessionId`	`string`	Yes
`displayName`	`string`	Yes

DeleteSessionMessage

Properties:

Property	Type	Required	Description
`type`	`"delete"`	Yes
`sessionId`	`string`	Yes
`deleteFromDatabase`	`boolean \| undefined`	No	If true, also delete from database (not just server)

UpdateSessionMessage

Properties:

Property	Type	Required	Description
`type`	`"update"`	Yes
`sessionId`	`string`	Yes
`context`	`Partial<SessionContext>`	Yes	Updated context fields (merged with existing)
`displayName`	`string \| undefined`	No	Optional new display name

SessionsListMessage

Properties:

Property	Type	Required	Description
`type`	`"sessions"`	Yes
`sessions`	`SessionInfo[]`	Yes

SessionCreatedMessage

Properties:

Property	Type	Required
`type`	`"created"`	Yes
`sessionId`	`string`	Yes
`displayName`	`string`	Yes

SessionReconnectedMessage

Properties:

Property	Type	Required	Description
`type`	`"reconnected"`	Yes
`sessionId`	`string`	Yes
`displayName`	`string`	Yes
`history`	`string`	Yes	Buffered output history for context restoration

SessionDataMessage

Properties:

Property	Type	Required
`type`	`"data"`	Yes
`sessionId`	`string`	Yes
`data`	`string`	Yes

SessionExitMessage

Properties:

Property	Type	Required
`type`	`"exit"`	Yes
`sessionId`	`string`	Yes
`exitCode`	`number`	Yes

SessionEndedMessage

Properties:

Property	Type	Required
`type`	`"session_ended"`	Yes
`sessionId`	`string`	Yes
`reason`	`"exit" \| "timeout" \| "closed"`	Yes
`exitCode`	`number \| undefined`	No

SessionRenamedMessage

Properties:

Property	Type	Required
`type`	`"renamed"`	Yes
`sessionId`	`string`	Yes
`displayName`	`string`	Yes

SessionDeletedMessage

Properties:

Property	Type	Required	Description
`type`	`"session_deleted"`	Yes
`sessionId`	`string`	Yes
`deletedFromDatabase`	`boolean`	Yes	Whether the session was also deleted from database

SessionUpdatedMessage

Properties:

Property	Type	Required	Description
`type`	`"session_updated"`	Yes
`sessionId`	`string`	Yes
`displayName`	`string`	Yes	Updated display name
`context`	`SessionContext`	Yes	Updated context

ErrorMessage

Properties:

Property	Type	Required
`type`	`"error"`	Yes
`message`	`string`	Yes
`sessionId`	`string \| undefined`	No

ShellServerConfig

Shell server configuration

Properties:

Property	Type	Required
`port`	`number`	Yes
`authToken`	`string \| undefined`	No
`sessionConfig`	`SessionManagerConfig \| undefined`	No

HealthResponse

Health check response

Properties:

Property	Type	Required
`status`	`"error" \| "ok" \| "degraded"`	Yes
`uptime`	`number`	Yes
`sessions`	`number`	Yes
`clients`	`number`	Yes
`port`	`number`	Yes
`version`	`string`	Yes