Skip to content

perf(sessions): move the session host (node-pty, headless terminals, parsers, transcript tailing) to a utilityProcess #764

Open

Description

@Juliusolsson05

Motivation

Everything runs on the Electron main thread today: headless xterm parse of every PTY byte for ~35 sessions, 3 cell walks + 2 grid walks + 5 detectors per screen snapshot, JSONL tailing (100 ms fs.watchFile stat polls per session ≈ 350 stat/s, JSON.parse of 10–500 KB entries, interning, semantic derivation), structured clone for every outbound message, recorder/perf/feed-debug writes, session index and history loads (p95 0.9–1.2 s, max 4.6 s), the synchronous heap snapshot. Main event-loop delay mean 21 ms, max 1.65 s. The only utilityProcess in the tree is the workflow MCP worker (src/main/workflows/ElectronWorkflowWorkerLauncher.ts:26); no worker_threads, no MessageChannelMain.

Portability is real: claude-code-headless depends only on @xterm/headless + chokidar; nothing under packages/*/src or src/providers imports electron; provider runtimes import only @main/storage/paths, @main/setup/runtimeTools, @main/setup/toolchain (injectable). The coupling is SessionManager (4,656 lines).

Intended behaviour

  • A session-host utilityProcess (VS Code "pty host" model) owns node-pty + headless terminals + parsers + JsonlTailer + semantic derivation. SessionManager stays in main and talks to each AgentSession through a proxy exposing the same event surface over MessagePortMain.
  • Step 2: the renderer gets a direct MessagePort for agent-pty-data / screen / semantic-event / jsonl-entries, bypassing main entirely.
  • Synchronous fences (isDeliveryInFlight, throwIfSpawnCancelled) become request/response.
  • Per provider, opencode JSON runtime or the shell TerminalSession first.

Acceptance criteria

  • Main event-loop delay mean ≤ 2 ms with 20 live sessions; main heap no longer holds xterm buffers or transcripts.
  • All provider runtime tests pass against the proxy; a host crash restarts the host and re-attaches sessions.

Do NOT put @xterm/headless in worker_threads while node-pty stays in main (copies every byte, keeps the PTY storm on main).
Refs #103, #390. Source: architecture audit 2026-09-03 (scratchpad/arch-perf-audit.md).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    class:C7-new-featureBug cluster of a recently shipped featuretype:perfPerformance or resource use

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions