feat(api): add terminal WebSocket gateway with PTY session management #515

jason.woltje · 2026-02-26T02:27:19Z

jason.woltje commented

2026-02-26 02:27:19 +00:00

Summary

NestJS WebSocket gateway on namespace with node-pty PTY session management
Real shell process spawning (bash/zsh) with full stdin/stdout/stderr streaming
Workspace-scoped session isolation with per-workspace limit (10 concurrent)
Authentication via handshake token (same pattern as speech gateway)
Class-validator DTOs for all WebSocket events
48 unit tests covering gateway and service

Implementation

: WebSocket gateway handling connect/disconnect, create/input/resize/close events
: PTY lifecycle management with session tracking per workspace
: Validated DTOs (CreateTerminalDto, TerminalInputDto, TerminalResizeDto, CloseTerminalDto)
: NestJS module importing AuthModule and PrismaModule

Test plan

25 gateway tests (auth, events, error handling)
23 service tests (session lifecycle, workspace isolation, limits)
TypeScript typecheck clean
Lint clean

Relates to #508

## Summary - NestJS WebSocket gateway on namespace with node-pty PTY session management - Real shell process spawning (bash/zsh) with full stdin/stdout/stderr streaming - Workspace-scoped session isolation with per-workspace limit (10 concurrent) - Authentication via handshake token (same pattern as speech gateway) - Class-validator DTOs for all WebSocket events - 48 unit tests covering gateway and service ## Implementation - : WebSocket gateway handling connect/disconnect, create/input/resize/close events - : PTY lifecycle management with session tracking per workspace - : Validated DTOs (CreateTerminalDto, TerminalInputDto, TerminalResizeDto, CloseTerminalDto) - : NestJS module importing AuthModule and PrismaModule ## Test plan - [x] 25 gateway tests (auth, events, error handling) - [x] 23 service tests (session lifecycle, workspace isolation, limits) - [x] TypeScript typecheck clean - [x] Lint clean Relates to #508

jason.woltje added the api api labels 2026-02-26 02:27:19 +00:00

jason.woltje added 1 commit 2026-02-26 02:27:20 +00:00

feat(api): add terminal WebSocket gateway with PTY session management

ci/woodpecker/push/orchestrator Pipeline failed

Details

ci/woodpecker/push/web Pipeline failed

Details

ci/woodpecker/push/api Pipeline failed

Details

fd38fc94d0

Implements CT-TERM-001: WebSocket-based terminal service that spawns real
shell sessions via node-pty and streams I/O to connected clients.

- Add node-pty dependency and configure pnpm build permissions
- Create TerminalModule with Gateway, Service, and DTOs
- TerminalGateway: /terminal namespace, auth via handshake token,
  workspace-scoped rooms, handles terminal:create/input/resize/close events
- TerminalService: manages IPty sessions per workspace with max 10 session
  limit, cleanup on disconnect
- DTOs: CreateTerminalDto, TerminalInputDto, TerminalResizeDto, CloseTerminalDto
  with class-validator decorators
- Unit tests: 25 gateway tests + 23 service tests (all passing)
- Register TerminalModule in AppModule

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jason.woltje merged commit 6290fc3d53 into main

2026-02-26 02:27:30 +00:00

jason.woltje referenced this issue from a commit

2026-02-26 02:27:30 +00:00

feat(api): add terminal WebSocket gateway with PTY session management (#515)

jason.woltje deleted branch feat/ms19-terminal-gateway

2026-02-26 02:27:30 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaic/stack#515