@volter-ai-dev/supercode-terminal

Optional terminal/tmux hosting for Supercode frontends. It complements Supercode's semantic transcript and runtime APIs with the familiar live terminal screen; it does not turn terminal bytes into canonical conversation history.

The server-side TmuxTerminalHost can discover existing tmux sessions, create a session from a structured command, capture its display, prepare a local tmux attach-session launch, open that launch through the trusted local-terminal adapter, and issue a one-use embedded attachment grant. Existing sessions are read-only by default. Control and close are allowed only for sessions bearing this host's ownership mark unless the embedding host explicitly opts into unowned control.

Browser and extension hosts can pair it with TerminalWebSocketBridge, which binds an ephemeral loopback port, requires an exact configured origin on every WebSocket upgrade, and accepts only one-use attachment grants. The embedding product supplies its allowed origin and never handles a tmux socket or target. normalizeTerminalUiState performs the matching untrusted-wire projection before state reaches the reusable terminal components.

Browser code imports @volter-ai-dev/supercode-terminal/client. It contains only the terminal WebSocket client and protocol types; it never imports tmux, node-pty, filesystem, or process APIs.

Frontends that want the default terminal experience can import the optional Preact components from @volter-ai-dev/supercode-terminal/ui and its tokenized stylesheet from @volter-ai-dev/supercode-terminal/ui/styles.css. TerminalPanel, TerminalViewer, and TerminalPath are independently reusable. The panel takes callbacks rather than a transport implementation, so a host can map its own validated intents without exposing native handles. The heavy xterm runtime is a dynamic import and is loaded only when a viewer is actually opened.

Safety properties:

• browser actions use opaque catalog ids rather than tmux targets;
• embedded attachment grants are random, short-lived, and consumed once;
• the tmux socket and session target never appear in an embedded grant;
• detaching disposes the ephemeral PTY/WebSocket resources but cannot stop the durable tmux session;
• closing is a separate explicit operation and checks the ownership mark;
• structured commands and argument arrays are passed without shell-string construction.