kaval-tui — a CLI terminal client for kolu-server

A terminal-side client of kolu-server’s pty-host. kolu-server owns its PTYs in-process today; kaval-tui connects to that same in-process pty-host over a local unix socket (speaking ptyHostSurface) and gives you list / create / snapshot / send / attach / kill from the terminal — no browser, no daemon. It is the CLI face of kolu and the seed of a tmux/zmx replacement (#671), shipped in phases as a beta.

Scoped to kaval-tui-on-the-in-process-server. The parent plan’s Phase R2 — moving the pty-host into a surviving daemon — is a separate plan this later dovetails with (see Later). Ancestry: child of the pty-daemon plan; cf. Ghostex vs. kolu remote-terminals.

Architecture — everything stays in-process

No new process. kolu-server keeps owning the PTYs exactly as it does now; it just exposes the same in-process router over an additional local socket so a second client — the CLI — can reach it. The web path is byte-identical.

The split by richness. The browser is the rich client — it speaks kolu-server’s public contract and gets the whole world (PTY plus the provider DAG: git context, agent state, PR status, session grouping). kaval-tui is the raw client — it speaks ptyHostSurface directly and gets the bare multiplexer (PTY plus the VT taps), exactly the tmux altitude. Both attach to the one in-process pty-host.

Why a second client at all

Two reasons, both standing on their own without any reference to daemons.

• It’s a feature. A persistent-while-the-server-runs terminal you drive from the shell — the CLI face of kolu, the start of the tmux replacement #671 has always pointed at.
• It proves the contract is consumer-agnostic. A1 (#1055) asserts ptyHostSurface is a clean seam — kolu-server talks to the pty-host through a contract, not through node-pty internals. The only real proof of that is a second, independent consumer. If writing a terminal client against the surface is clean, the seam is at the right altitude (the “framework needs an end-to-end demo, not just unit tests” lesson — parent plan, lesson #3). If it’s awkward, that’s a finding worth having early.

The surface — ~850 LOC in packages/kaval-tui

A small node CLI in its own package, packages/kaval-tui, that dials the unix socket through unixSocketLink (the local-IPC member of @kolu/surface’s link family — same base64+newline framing the daemon’s ssh stdio path uses later) and gets a typed ptyHostSurface client. No new wire, no new framing — each accepted connection is pumped through the already-tested serveOverStdio.

Of the taps, attach consumes exit — stream-end discrimination plus the real exit code, which tombstones server-side so it’s retrievable even after the deltas end. The metadata taps (cwd / title / foreground) feed no persistent status line: that early sketch contradicted the raw-passthrough decision and was dropped (see the Phase 2 decisions below); they stay on the contract for a later richer UX. --json makes list machine-readable; --socket <path> points at a non-default server.

Decisions recorded here (to be echoed in code comments)

Phasing — three beta increments, all in-process

Phases 1–3 build kaval-tui on the in-process server — each leaves Kolu working, ships on its own, and changes nothing in the web path. They’re preceded by a Phase 0 that lives outside kolu: a surface example that rehearses the whole “interactive TUI over oRPC stdio” pattern.

Phase 1 alone is the smallest honest first ship of kaval-tui — a one-shot RPC, no raw-tty mode, the “hello world” that proves serveOverUnixSocket + unixSocketLink + the contract round-trip, at near-zero risk.

Phase 0 — a minimal CI-runner TUI (the 3rd surface example) shipped #1073

Before touching kolu, prove the pattern in @kolu/surface’s examples — the falsifiability test of lesson #3 applied to “interactive TUI over oRPC stdio,” the way the worker demo and the remote-process-monitor (which became drishti) validated the earlier patterns. The candidate: a minimal CI runner — justci-flavoured but self-contained, deliberately not the real justci. Just a small DAG of shell commands, runnable locally or on a single remote host.

It’s a clean structural twin of kaval-tui: a long-lived runner owns the DAG + each node’s process + its log buffer, and streams to ephemeral TUI clients over stdio. The plan’s nodes.list() / node.log(id) / node.rerun(id) map onto the framework-idiomatic spelling — a nodes cell (surface.nodes.get({})) ↔ kaval-tui’s list; a nodeLog stream (snapshot-then-delta) ↔ attach; a node.rerun procedure ↔ input. That this was clean to write against the surface primitives is the finding: the seam is at the right altitude for kaval-tui to inherit. The example is now kaval-tui’s copy-paste skeleton and a permanent regression test for the pattern.

Remote mode ships the runner the drishti way: a prebuilt mini-ci-runner nix closure is nix copy’d to the host, realised, then run as ssh host mini-ci-runner --stdio with the TUI attached over stdio-over-ssh via @kolu/surface-nix-host’s getHostSession({ host, binary, resolveDrvPath }) (which owns ref-count, reconnect, watchdog, and a copying → connecting → connected state cell). localhost skips the nix copy and runs the realised binary directly — the same HostSession, only the transport differs.

Phase 2 — the attach loop shipped #1255

Recon verdict before implementation, borne out by the ship: no contract bump, no server change — terminalAttach / write / resize / exit all exist at contract 2.1 (and the web path already consumes the same host.attach as just another subscriber on the per-PTY broadcast channel, so a CLI attach violates no exclusivity). Attach is a pure consumer; no drishti-mirror PR. The whole phase is ~300–400 LOC in packages/kaval-tui plus tests. One delivery note: the reply filter first shipped as a move of the browser’s terminalResponseFilter into kolu-common; a blocking structural review then promoted the whole protocol policy — grammars + stripper, the headless forward/drop rule, the answered/silent device-query matrix, paste delimiters, and the snapshot-reciprocal TTY reset — into a dedicated zero-dep leaf, @kolu/terminal-protocol, that the browser, the pty-host, and kaval-tui all import. The pty-host’s staleKey hashes it (a protocol change is observable daemon behaviour), and its device-query matrix is executed as contract tests against a real headless.

The sequence: connect → version gate (both shipped in Phase 1) → attach carrying the local grid → raw mode → one-shot ↻ snapshot restored… notice → paint snapshot → pump until detach or stream end. Five decisions carry the design weight (echoed as code comments at their sites, per this note’s convention):

The escape machine’s fine print: it runs on bytes, decoding via string_decoder only at the write boundary so multibyte characters split across stdin chunks survive; session start counts as line-start (ssh behaviour); recognition is suspended inside bracketed-paste brackets so a pasted \n~. cannot detach; in raw mode Ctrl+C arrives as byte 0x03 and is forwarded like everything else — only external SIGTERM/SIGHUP trigger the restore-and-exit path.

Testing. The escape machine, reply filter, and reset emission are pure functions — unit-tested with no tty (the render.test.ts pattern). The loop itself is factored over read/write streams plus a tty-ish interface and integration-tested against the real-socket harness (the serveOverSocket.test.ts pattern: in-process pty-host + unixSocketLink on a temp socket). The home-manager VM test keeps its list smoke — attach is infeasible headless.

The user flow

The interactive loop a user walks, then the same loop scripted as a headless test. The running example: a PTY 3f9a…c21 in ~/code/kolu that becomes a Claude Code session.

Interactive session

Is the server’s pty-host reachable? — an unreachable pty-host is a clear, immediate error, never a silent empty hang:

$ kaval-tui list
kaval-tui: no pty-host socket at /run/user/1000/kolu/pty-host.sock (ECONNREFUSED)
          is kolu-server running? the socket appears once it boots.

The inventory — list from another shell, one row per live PTY (the status line reports the in-process pty-host):

Birth → work → detach → re-attach (Phase 2/3). create mints a PTY and prints its id; attach <id> takes it over — everything passes through raw, the CLI owns no pixels while attached; a line-start ~. detaches (the server keeps the PTY); re-attach repaints the full scrollback snapshot instantly because the first yield of the attach stream is the snapshot, serialized at the local tty’s dimensions because the attach request carries them.

This is client-side detach — distinct from server survival. If kolu-server itself restarts, the in-process PTY dies; that persistence is the separate daemon plan.

Headless test — client-death detach/reattach, no browser

The detach/reattach loop scripted: it asserts that the CLI client can die and a fresh one re-joins the same PTY (the server runs throughout) — fast, no browser.

#!/usr/bin/env bash
set -euo pipefail

# 1 · create a PTY with a unique marker in its scrollback (create never attaches)
id=$(kaval-tui create --json -- bash -c 'echo "MARK-$$"; exec sleep 1d' | jq -r .id)
pid_before=$(kaval-tui list --json | jq -r ".[] | select(.id==\"$id\").pid")

# 2 · (no kaval-tui process is attached — simulating client death)

# 3 · a fresh client re-attaches by id and asserts the state is intact
kaval-tui snapshot "$id" | grep -q "MARK-"            # scrollback preserved
pid_after=$(kaval-tui list --json | jq -r ".[] | select(.id==\"$id\").pid")
[ "$pid_before" = "$pid_after" ]                     # same PTY, not a respawn

echo "✓ client came and went; server held the PTY (pid $pid_after unchanged)"

This is the kaval-tui-scoped reattach test — the client can come and go while the server holds the PTY. (Surviving a server restart is a different assertion that belongs to the daemon plan, not here.)

Later — how this dovetails with the daemon plan (out of scope)

Stated only so we don’t trip over it: when the parent plan’s Phase R2 eventually moves the pty-host out of kolu-server into a surviving kolu --stdio daemon, kaval-tui’s socket target shifts from kolu-server to the daemon — with no contract change, because both serve the same ptyHostSurface. At that point the CLI’s terminals gain server-restart survival for free, and the raw-vs-rich client split is unchanged. But that is a separate plan; nothing in kaval-tui’s phases above depends on it, and kaval-tui ships and is useful entirely on the in-process server.