Integrated Terminal - Embedded shell commands

[circus-chimp]

Add embedded terminal panel supporting:

• Shell command execution
• Docker commands
• Kubectl commands

[circus-chimp]

Triaging this enhancement request. An integrated terminal panel is a substantial feature that will require careful architectural design. Handing off to an architect to assess the implementation approach.

[circus-chimp]

🏗️ Architecture Design: Integrated Terminal Panel

After reviewing the dashboard codebase, here's the implementation plan for this feature.

---

Problem

Operators need to run shell, Docker, and kubectl commands directly from the dashboard without switching to a separate terminal. This is an operator-facing tool for infrastructure management alongside chimp monitoring.

---

Key Architectural Decisions

1. Communication: WebSocket (not SSE)

Interactive terminals need bidirectional, low-latency communication. The existing SSE infrastructure is one-way (server → client) — fine for activity streams but can't handle stdin. Bun.serve supports WebSocket natively alongside the existing HTTP routes and SSE streams. Both can coexist.

2. Process Management: node-pty for full PTY support

For a real terminal experience (ANSI colors, cursor control, interactive programs like vim, top, kubectl exec -it), we need a pseudo-terminal. Options considered:

Approach	Pros	Cons
node-pty	Full PTY support, mature, handles resize/signals	Native compilation dependency
Bun.spawn piped	No extra deps, simple	No TTY — no colors, no interactive programs
script wrapper	Pseudo-TTY without native dep	Hacky, inconsistent across platforms

Recommendation: node-pty. It's the standard for web terminals and gives the best operator experience.

3. Frontend: @xterm/xterm

Industry standard for browser-based terminal emulation. Handles ANSI escape codes, scrollback, selection, search. With addons for auto-fit and clickable links.

4. Panel Placement: Bottom dock (VS Code pattern)

The terminal panel lives outside <Routes> in App.tsx, so it persists across page navigation. It docks to the bottom of the viewport with a drag handle for resizing and a keyboard shortcut to toggle.

---

Component Architecture

Frontend (Browser)
┌─────────────────────────────────────────────────────────┐
│  App.tsx                                                 │
│  ├── Header (nav bar + terminal toggle button)           │
│  ├── <main> Routes (existing pages)                      │
│  │    ├── / → DashboardHome                              │
│  │    ├── /chimps → ChimpsList                           │
│  │    ├── /profiles → Profiles                           │
│  │    └── /chimps/:id/activity → ChimpActivity           │
│  └── TerminalPanel (fixed bottom dock)                   │
│       ├── TabBar (session tabs + "+" button)             │
│       ├── ResizeHandle (drag to resize height)           │
│       └── TerminalView[] (xterm.js instances per tab)    │
│            └── WebSocket ←→ Backend                      │
└─────────────────────────────────────────────────────────┘
              │
              │ WebSocket: ws://host/api/terminal/ws
              ▼
Backend (Bun.serve)
┌─────────────────────────────────────────────────────────┐
│  dashboard.ts                                            │
│  ├── routes: { ...existing, /api/terminal/* }            │
│  ├── fetch: (req, server) → WebSocket upgrade handler    │
│  └── websocket: { open, message, close }                 │
│       └── delegates to TerminalService                   │
│            ├── sessions: Map<sessionId, TerminalSession>  │
│            └── TerminalSession                            │
│                 ├── pty: IPty (node-pty instance)         │
│                 ├── wsSet: Set<ServerWebSocket>           │
│                 └── metadata (shell, created, size)       │
└─────────────────────────────────────────────────────────┘

---

WebSocket Protocol

JSON-encoded messages over a single WebSocket connection (multiplexed by session ID):

// Client → Server
type ClientMessage =
  | { type: "create"; shell?: string }                           // Spawn new terminal session
  | { type: "input"; sessionId: string; data: string }           // Stdin keystrokes
  | { type: "resize"; sessionId: string; cols: number; rows: number }  // Terminal resize
  | { type: "close"; sessionId: string }                         // Kill session

// Server → Client
type ServerMessage =
  | { type: "created"; sessionId: string; shell: string }        // Session spawned
  | { type: "output"; sessionId: string; data: string }          // Stdout/stderr data
  | { type: "exited"; sessionId: string; exitCode: number }      // Process exited
  | { type: "error"; message: string; sessionId?: string }       // Error

Why single multiplexed connection? Opening one WebSocket per terminal tab creates unnecessary connection overhead. A single connection with session IDs is cleaner and matches how the frontend manages tabs.

---

File Plan

New files

File	Purpose
src/lib/terminal-protocol.ts	Zod schemas for WebSocket message types
src/services/terminal-service.ts	Session lifecycle management, PTY creation/destruction
src/routes/terminal.ts	WebSocket message routing + HTTP session list endpoint
src/components/TerminalPanel.tsx	Bottom dock panel with tabs, resize, toggle
src/components/TerminalView.tsx	xterm.js wrapper React component
src/hooks/useTerminal.ts	WebSocket connection management, session state

Modified files

File	Change
src/dashboard.ts	Add fetch handler for WS upgrade, websocket config, wire TerminalService
src/App.tsx	Add <TerminalPanel> below <Routes>, terminal toggle in Header
package.json	Add node-pty, @xterm/xterm, @xterm/addon-fit, @xterm/addon-web-links

---

Backend Design Details

TerminalService

class TerminalService
├── createSession(shell?: string): TerminalSession
├── getSession(id: string): TerminalSession | undefined
├── closeSession(id: string): void
├── listSessions(): SessionInfo[]
├── handleInput(sessionId: string, data: string): void
├── handleResize(sessionId: string, cols: number, rows: number): void
└── cleanup(): void   // Close all sessions on shutdown

Follows the existing service pattern (constructor injection, logger). The Dashboard class owns the TerminalService lifecycle (create in start(), cleanup in stop()).

WebSocket Integration in dashboard.ts

// Bun.serve needs `fetch` for WebSocket upgrade (routes don't receive `server`)
this.server = serve({
  routes: { ...existing routes... },
  fetch: (req, server) => {
    if (new URL(req.url).pathname === "/api/terminal/ws") {
      if (server.upgrade(req, { data: { /* auth context */ } })) return;
      return new Response("Upgrade failed", { status: 400 });
    }
    // Fall through to 404 for non-route, non-WS requests
    return new Response("Not found", { status: 404 });
  },
  websocket: {
    open(ws) { terminalRouter.onOpen(ws); },
    message(ws, msg) { terminalRouter.onMessage(ws, msg); },
    close(ws) { terminalRouter.onClose(ws); },
  },
});

Session Limits & Cleanup

• Max concurrent sessions: configurable (default 10)
• Idle timeout: configurable (default 30 minutes)
• Sessions cleaned up on WebSocket disconnect (with grace period for reconnection)
• All sessions killed on Dashboard.stop()

---

Frontend Design Details

TerminalPanel — Bottom dock component

• Toggle: Button in Header + keyboard shortcut (`Ctrl+``)
• Resize: Drag handle at top edge, min/max height constraints
• Tabs: Each tab = one terminal session. "+" button creates new tab.
• State: Panel open/closed state + height stored in localStorage
• Styling: Dark background (circus-navy), monospace font, matches the circus theme

TerminalView — xterm.js wrapper

• Creates xterm Terminal instance on mount
• Attaches FitAddon for auto-sizing
• Sends keystrokes to WebSocket as { type: "input", sessionId, data }
• Receives { type: "output" } messages and writes to terminal
• Handles resize events → sends { type: "resize" } to backend
• Cleans up on unmount (dispose terminal, remove listeners)

useTerminal hook

• Manages single WebSocket connection lifecycle
• Tracks sessions state: Map<sessionId, { shell, status }>
• Provides createSession(), closeSession(), sendInput(), resize()
• Auto-reconnect with exponential backoff
• Dispatches incoming messages to the correct TerminalView

---

Implementation Phases

Phase 1 — Backend terminal service + WebSocket (can be developed independently)

1. Add node-pty dependency
2. Implement terminal-protocol.ts with Zod schemas
3. Implement TerminalService with session CRUD
4. Implement TerminalRouter WebSocket handlers
5. Wire into dashboard.ts (fetch upgrade + websocket config)
6. Add /api/terminal/sessions HTTP endpoint for debugging

Phase 2 — Frontend terminal component (depends on Phase 1 protocol)

1. Add @xterm/xterm + addon dependencies
2. Implement useTerminal hook
3. Implement TerminalView component
4. Implement TerminalPanel with tabs and resize
5. Integrate into App.tsx

Phase 3 — Polish & UX

1. Keyboard shortcut toggle (`Ctrl+``)
2. Circus theme for xterm.js (gold on navy, crimson accents)
3. Session reconnection (reattach to surviving backend sessions)
4. Panel height persistence in localStorage
5. Quick-action buttons (preset commands: kubectl get pods, docker ps)

---

Security Considerations

The dashboard runs inside a Kubernetes pod — terminal commands execute in that pod's context.

• kubectl access: Governed by the pod's ServiceAccount RBAC. No extra config needed if the SA has permissions.
• Docker access: Requires Docker socket mount (/var/run/docker.sock). May not be available — should gracefully degrade.
• Shell access: Default to /bin/sh, allow configurable shell via env.
• Future: Consider session-level audit logging and configurable command allowlists.

---

Open Questions

1. Should sessions survive dashboard restart? Currently: no. Sessions are in-memory. Could persist session metadata to Redis for reconnection, but adds complexity for v1.
2. Multi-user support? Currently the dashboard has no auth. If auth is added later, terminal sessions should be scoped per user.
3. Remote execution? v1 runs commands locally in the dashboard pod. Future enhancement could exec into chimp pods via kubectl exec, turning this into a cross-pod terminal manager.

---

Ready for implementation handoff once this design is reviewed. Phases 1 and 2 can be developed on a single feature branch — each phase is a natural commit boundary.