feat(web): single-socket — multiplex terminals + sessions over one WebSocket

[fastestdevalive]

Summary

Replaces three separate real-time channels with a single persistent multiplexed WebSocket at /mux.

Before:

• One WebSocket per terminal (:14801/ws?session=<id>, spawned per tab)
• SSE stream for session status (/api/events)
• Legacy ttyd server on port 14800 (dead code, never used by UI)

After:

• One persistent /mux WebSocket per browser tab (owned by MuxProvider)
• Terminal I/O, resize, open/close all flow over mux protocol channels
• Session patches delivered via a shared SSE relay: mux server subscribes once to Next.js /api/events and broadcasts to all connected clients — no per-client polling

Architecture

Browser  ←── WS /mux ──→  Mux Server (:14801)  ←── SSE /api/events ──  Next.js (:3000)
          (bidirectional)     TerminalManager         (event-driven push,
          terminal + sessions  node-pty per session    1 shared connection)

Key changes

• MuxProvider — React context at app root owning the single WebSocket; DirectTerminal uses hooks instead of managing its own WS
• SessionBroadcaster — server-side class maintaining one SSE connection to Next.js, lazily connecting on first subscriber and disconnecting when the last one leaves
• Manual WS upgrade routing — works around a ws library limitation where two WebSocketServer instances with different path options on the same HTTP server don't work correctly
• useSessionEvents — extended to accept mux session patches, skipping SSE when mux is available
• Removed terminal-websocket.ts — entire legacy ttyd-based server deleted (port 14800, ~450 lines)

Test plan

• Open dashboard — terminals connect and show output
• Resize browser window — terminal resizes correctly
• Multiple terminals open simultaneously — all receive independent I/O
• Session status cards update in real time as agent state changes
• Disconnect/reconnect network — MuxProvider reconnects with backoff, terminals reattach automatically
• pnpm --filter @composio/ao-web test — 453 tests passing
• pnpm --filter @composio/ao-web typecheck — clean

🤖 Generated with Claude Code

[cursor]

Server open handler sends buffer then subscribes, risking duplicate data

Medium Severity

When handling a terminal open message, the server calls terminalManager.open(id) (line 481) which internally calls subscribe() adding its own subscriber, then the handler separately calls terminalManager.subscribe(id, ...) (line 501) adding a second subscriber. The first open() call alone already subscribes data delivery through the onData handler. Wait — actually, open() only spawns the PTY and sets up internal onData/onExit that push to terminal.subscribers. It doesn't add to terminal.subscribers by itself. The subscribe() call does. So the flow is: open() → buffer sent → opened sent → subscribe() adds the callback. This is correct within a single connection.

However, the real issue: subscribe() calls this.open(id) internally (line 367), which is redundant since the handler already called open(). More importantly, subscribe()'s unsubscribe closure captures the terminal local variable from subscribe(), while open()'s onData/onExit closures capture the terminal local variable from open(). Both point to the same map entry, so this works. No actual bug here after deeper analysis.

Let me re-examine...

Actually — the real bug I see: the opened confirmation is sent (line 496-497) BEFORE the subscription is created (line 500-521). On the client side in MuxProvider, receiving opened triggers openedTerminalsRef.current.add(msg.id). The client considers the terminal "open" and may immediately start writing. This is fine since writeTerminal works independently. Not a bug.

I'll withdraw this and look more carefully.

Additional Locations (1)

• packages/web/server/mux-websocket.ts#L364-L390

 

[fastestdevalive]

No action needed — the bot concluded its own analysis with 'No actual bug here after deeper analysis' and self-withdrew. The ordering (open → buffer → subscribe) is correct: since everything runs synchronously in a single event-loop tick (no await), node-pty's onData cannot fire between getBuffer() and subscribe().

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[illegalcall]

@fastestdevalive Have you performed e2e testing for this? Can you attach screenshots/anything how this improves the operation.
A before/after would really help

[fastestdevalive]

@fastestdevalive Have you performed e2e testing for this? Can you attach screenshots/anything how this improves the operation. A before/after would really help

Yes, I have tested it end-to-end on my local machine. TO give context, the problem was the small delay seen when switching between sessions. Its not very evident in the AO's default UI but in my heavily customized fork which is a full blown IDE, the problem manifests as I have multiple session / sub-session selectors in the sidebar. And quickly selecting through them opens/clsoes socket connections which feels slower.
The goal with this is to maintain one websocket and multiplex it for every terminal/session related usage. Similar to how even VSCode does it internally.

I will try to get a before and after video.