A local-first multi-agent app development platform, built on PenguinHarness
/**
* The terminal stream's PROTOCOL: frames, coalescing, the restore-first attach sequence,
* size ownership, the heartbeat and the lagging-viewer resync.
*
* This is platform code even though the socket is the runtime's. The seam cannot carry a
* stream — a handler returns one whole Response — so the runtime keeps the upgrade
* handshake and its authentication (terminal/ws.ts) and hands the live socket here. What
* flows over it afterwards is behaviour, and behaviour a push must be able to change:
* every byte of the wire format, the coalescing window, the heartbeat and both
* backpressure watermarks are decided in this file. Two of those are no longer constants:
* the window and the high-water mark are derived per socket from what the link measures
* (link-quality.ts), because a number tuned on a LAN means something else entirely on a
* phone.
*
* Attach sequence — the part that makes a browser reload look seamless:
* 1. the client's geometry (?cols=&rows=) resizes the pty FIRST, so the snapshot is
* rendered at the width the client is about to display it at;
* 2. one Restore frame replays the whole screen;
* 3. live output follows, coalesced.
* Any output produced between 2 and 3 would be a lost line, so the output subscription is
* opened before the snapshot is rendered and buffered until the Restore frame is out.
*/
import { randomUUID } from "node:crypto";
import type { WebSocket } from "ws";
import {
TerminalStreamOpcode,
decodeTerminalFrame,
encodeTerminalFrame,
framePayloadText,
parseResizePayload,
} from "./frames.js";
import { TerminalOutputCoalescer } from "./output-coalescer.js";
import { RoundTripEstimator, SocketDrainMeter } from "./link-quality.js";
import type { TerminalSession } from "./session.js";
/**
* Per-viewer backpressure. A send queues without limit when the peer cannot drain, so a
* viewer too far behind stops receiving live output — the bytes keep feeding the server
* emulator, nothing of the session is lost — and once its backlog falls below LOW_WATER it
* is repainted with one fresh Restore frame (the same self-contained repaint an attach
* uses) and live output resumes. Skipping ahead beats both alternatives: replaying
* megabytes the viewer could only fast-forward through, or disconnecting it.
*
* "Too far behind" is the one number that is no longer a constant: it is derived per socket
* from what that link delivers (link-quality.ts), because the byte bound this used to be
* meant milliseconds of lag on a LAN and many seconds on a phone.
*/
const BACKPRESSURE_LOW_WATER = 64 * 1024;
const BACKPRESSURE_POLL_MS = 250;
/**
* Heartbeat. A phone loses a socket without closing it — a radio hand-off, a carrier NAT
* reaping an idle flow — and both ends then hold a connection that will never carry a byte
* again: the pty writes into a dead socket, the viewer waits for output that cannot arrive.
* The probe is what turns that into a close, which is what the client retries on. The reply
* doubles as the round-trip sample that sizes the merge window (link-quality.ts).
*
* The timeout is generous on purpose: a backgrounded tab is throttled to roughly one timer
* a minute, and reaping a viewer that is merely asleep would cost it a full repaint on
* every glance at the screen.
*
* Only a viewer that has ANSWERED a probe is ever reaped for silence. A page loaded before
* this shipped stays open across the push that brought it — the platform is replaced under
* a tab that is not reloaded — and that page does not know the opcode: it would go quiet,
* be closed, and (having no reattach either) show a dead pane. Silence only means something
* from a peer that has shown it can break it.
*/
const HEARTBEAT_INTERVAL_MS = 15_000;
const HEARTBEAT_TIMEOUT_MS = 75_000;
/**
* Frames smaller than this go out uncompressed even when the stream negotiated
* permessage-deflate: a keystroke's echo compresses to more bytes than it started with
* once the deflate overhead rides along. ws's own `perMessageDeflate.threshold` cannot
* carry this promise — it only applies to a direction that negotiated no_context_takeover,
* and this server keeps its deflate context precisely because a shared context is what
* compresses repeated output best — so the decision is made per message, here.
*/
const SMALL_FRAME_BYTES = 512;
export function bindTerminalStream(
ws: WebSocket,
session: TerminalSession,
url: URL,
log: (line: string) => void,
): void {
const connectionId = randomUUID();
ws.binaryType = "nodebuffer";
// What this viewer's link is doing, measured from this socket alone: the round trip from
// the heartbeat's echo, the drain rate from what the socket accepts.
const roundTrip = new RoundTripEstimator();
const drain = new SocketDrainMeter();
/**
* Bytes handed to the socket that have not left it yet — the viewer's backlog, counted in
* the output the terminal produced rather than in what the wire carried. `bufferedAmount`
* cannot answer this any more: the stream is compressed (terminal/ws.ts), and a screen of
* repeated build output leaves the socket a hundred times smaller than the user is behind.
* ws calls back once a message is flushed, so what has not called back is what is waiting.
*/
let inFlight = 0;
const send = (bytes: Uint8Array): void => {
if (ws.readyState !== ws.OPEN) return;
const size = bytes.byteLength;
inFlight += size;
ws.send(bytes, { compress: size >= SMALL_FRAME_BYTES }, () => {
inFlight -= size;
drain.note(size, inFlight);
});
};
// Lagging-viewer state (see the watermark comment above): while desynced, this viewer's
// live output is dropped and a slow poll waits for its socket to drain for the resync.
let desynced = false;
let resyncTimer: ReturnType<typeof setInterval> | null = null;
const stopResyncPoll = (): void => {
if (resyncTimer) clearInterval(resyncTimer);
resyncTimer = null;
};
const sendOutput = (data: string): void => {
if (desynced) return; // dropped: the emulator keeps every byte; the resync repaints
send(encodeTerminalFrame({ opcode: TerminalStreamOpcode.Output, payload: data }));
// A LAG bound, in bytes: how much output this viewer can still be behind and catch up
// within MAX_VIEWER_LAG_MS at the rate its socket has been delivering (link-quality.ts),
// which on a link fast enough to drain it is the 1MB this server always used.
if (inFlight <= drain.highWaterBytes()) return;
desynced = true;
log(`[terminal] stream ${session.id}: viewer ${inFlight}B behind, pausing for resync`);
resyncTimer = setInterval(() => {
if (ws.readyState !== ws.OPEN) return stopResyncPoll();
if (inFlight > BACKPRESSURE_LOW_WATER) return;
stopResyncPoll();
desynced = false; // flip first: output parsed after this snapshot flows live again
try {
send(
encodeTerminalFrame({
opcode: TerminalStreamOpcode.Restore,
payload: session.restoreStream(),
}),
);
} catch {
// The session was reaped while this viewer lagged; the Exit frame (sent directly,
// never dropped) already told it the story.
}
}, BACKPRESSURE_POLL_MS);
};
// Buffers output until the Restore frame has been sent (see the attach sequence above).
let restored = false;
let preRestore = "";
// The merge window follows the measured round trip: 5ms on a LAN, up to 50ms on a link
// where a single trip already costs twenty times that.
const coalescer = new TerminalOutputCoalescer(sendOutput, () => roundTrip.windowMs());
const unsubscribeOutput = session.onOutput((data) => {
if (!restored) {
preRestore += data;
return;
}
coalescer.push(data);
});
const unsubscribeExit = session.onExit((info) => {
coalescer.flush();
send(
encodeTerminalFrame({
opcode: TerminalStreamOpcode.Exit,
payload: JSON.stringify({ exitCode: info.exitCode, signal: info.signal }),
}),
);
});
// The attaching client's geometry wins: it is the viewport the user is looking at, and the
// snapshot below is laid out for it.
const cols = Number.parseInt(url.searchParams.get("cols") ?? "", 10);
const rows = Number.parseInt(url.searchParams.get("rows") ?? "", 10);
if (Number.isInteger(cols) && Number.isInteger(rows)) {
session.resize({ connectionId, cols, rows, intent: "claim" });
}
send(
encodeTerminalFrame({
opcode: TerminalStreamOpcode.Restore,
payload: session.restoreStream(),
}),
);
restored = true;
if (preRestore) {
coalescer.push(preRestore);
preRestore = "";
}
if (!session.alive && session.exit) {
send(
encodeTerminalFrame({
opcode: TerminalStreamOpcode.Exit,
payload: JSON.stringify({ exitCode: session.exit.exitCode, signal: session.exit.signal }),
}),
);
}
// Anything arriving proves the socket is still a socket, heartbeat replies included.
let lastSeenAt = Date.now();
// Whether this viewer speaks the heartbeat at all (see HEARTBEAT_TIMEOUT_MS).
let answersProbes = false;
const heartbeat = setInterval(() => {
if (ws.readyState !== ws.OPEN) return;
if (answersProbes && Date.now() - lastSeenAt > HEARTBEAT_TIMEOUT_MS) {
log(`[terminal] stream ${session.id}: viewer stopped answering, closing`);
ws.terminate(); // not close(): a socket this quiet will not complete a handshake
return;
}
send(encodeTerminalFrame({ opcode: TerminalStreamOpcode.Ping, payload: String(Date.now()) }));
}, HEARTBEAT_INTERVAL_MS);
ws.on("message", (raw: Buffer, isBinary: boolean) => {
if (!isBinary) return; // the data plane is binary-only
lastSeenAt = Date.now();
const frame = decodeTerminalFrame(new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength));
if (!frame) return;
switch (frame.opcode) {
case TerminalStreamOpcode.Input:
session.write(framePayloadText(frame));
break;
case TerminalStreamOpcode.Resize: {
const size = parseResizePayload(frame);
if (size) session.resize({ connectionId, ...size });
break;
}
// The client probes for itself (its own timers are the ones a phone suspends); the
// payload is its clock reading and goes back untouched.
case TerminalStreamOpcode.Ping:
send(encodeTerminalFrame({ opcode: TerminalStreamOpcode.Pong, payload: frame.payload }));
break;
case TerminalStreamOpcode.Pong: {
answersProbes = true;
const sentAt = Number.parseInt(framePayloadText(frame), 10);
if (Number.isFinite(sentAt)) roundTrip.sample(Date.now() - sentAt);
break;
}
default:
break; // server-only opcodes echoed back by a confused client
}
});
const teardown = (): void => {
clearInterval(heartbeat);
unsubscribeOutput();
unsubscribeExit();
stopResyncPoll();
coalescer.dispose();
// Closing a view must not resize or kill the shell — only give up size ownership so the
// next client to attach can claim it.
session.releaseSize(connectionId);
};
ws.on("close", teardown);
ws.on("error", (err: Error) => {
log(`[terminal] stream ${session.id} socket error: ${err.message}`);
teardown();
});
}