Skip to content

feat: per-instance terminal sessions for multi-instance switching#24

Merged
linletian merged 2 commits intodevelopfrom
fix/copilot-cli-input
Mar 20, 2026
Merged

feat: per-instance terminal sessions for multi-instance switching#24
linletian merged 2 commits intodevelopfrom
fix/copilot-cli-input

Conversation

@linletian
Copy link
Copy Markdown
Owner

Overview

Refactor the frontend terminal from a single shared xterm.js instance to a per-instance terminal session model. Each running instance now owns its own terminal, transport state, timers, and reconnect logic.

Key Changes

Frontend Architecture

  • Per-instance sessions: terminalSessions = {} stores independent session state for each instance
  • Session lifecycle: New functions for create/destroy/reconcile session management
  • Connection preservation: Switching tabs hides inactive terminals instead of tearing down healthy PTY connections
  • TUI program protection: Long-lived TUI programs (Copilot CLI, vim, etc.) remain connected when switching away

New Functions

  • createTerminalSession(id) - Create new session with dedicated xterm instance
  • destroyTerminalSession(id) - Complete cleanup including termDataDisposable
  • maybeDestroyInactiveStoppedSession(id) - Cleanup stopped non-active sessions
  • reconcileTerminalSessions() - Sync sessions with instance state on refresh
  • reconnectRunningTerminalSessions() - Auto-reconnect running sessions after network recovery
  • renderTerminalSessions() - Show/hide session containers based on active selection
  • reportSessionError(session, prefix, err) - Unified per-session error handling

Documentation Updates

  • docs/API.md: Added frontend session model description
  • docs/ARCHITECTURE.md: Updated §5.3 Instance Switch Protocol with 3 scenarios (stopped, running+healthy, running+unhealthy)
  • docs/PRD.md: Added per-instance session behavior note

Tests

  • TestIndexHTMLCoversMultiInstanceSwitching - Verify switching hooks
  • TestIndexHTMLCoversSessionLifecycle - Verify create/destroy hooks
  • TestIndexHTMLCoversReconcileLogic - Verify sync logic
  • TestIndexHTMLCoversPerSessionConnectionManagement - Verify WebSocket management

Benefits

  1. No more TUI disruption: Copilot CLI and other TUI programs stay connected when switching instances
  2. Better resource management: Explicit disposable cleanup for onData subscriptions
  3. Faster switching: Healthy sessions don't need full reconnect
  4. Isolated state: Each instance has independent logCursor, ttyState, and terminal buffer

Testing

  • All existing tests pass
  • New tests verify session lifecycle and connection management
  • Manual testing recommended for:
    • Switching between multiple running TUI instances
    • Network reconnection scenarios
    • Memory usage with many sessions

Checklist

  • Code formatted with gofmt
  • All tests pass
  • Documentation updated
  • Commit message follows conventions

linletian and others added 2 commits March 20, 2026 22:08
- Refactor frontend terminal from single shared instance to per-instance
  sessions, each owning its own xterm.js instance, transport state,
  timers, and reconnect logic.
- Switching between running instances now hides inactive terminal
  containers instead of tearing down their PTY attachment, preventing
  disruption of long-lived TUI programs like Copilot CLI.
- Add session lifecycle management: createTerminalSession,
  destroyTerminalSession, maybeDestroyInactiveStoppedSession,
  reconcileTerminalSessions, reconnectRunningTerminalSessions.
- Add reportSessionError for unified per-session error handling.
- Update docs/API.md, docs/ARCHITECTURE.md, and docs/PRD.md to
  document the new frontend session model and instance switch protocol.
- Add comprehensive tests covering multi-instance switching, session
  lifecycle, reconcile logic, and per-session connection management.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
@linletian linletian merged commit 132bf58 into develop Mar 20, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant