1095 lines
39 KiB
TypeScript
1095 lines
39 KiB
TypeScript
/**
|
|
* tmux backend for the Terminal app: lists, watches, views and types into
|
|
* tmux panes on an SSH host, presenting them through the same TerminalClient
|
|
* model as g2mirror sessions (each pane is one "session"; its pane id, e.g.
|
|
* "%12", plays the part of g2mirror's session socket).
|
|
*
|
|
* Two kinds of channel run on the host, both opened through `openChannel`
|
|
* (an SSH exec channel in the app, a local process in tests):
|
|
*
|
|
* - The poller: a /bin/sh loop that prints the tmux version and host name,
|
|
* then every 2 s lists every pane of every session (only when the listing
|
|
* changed). It also (re)installs an alert-bell hook that counts bells per
|
|
* window in the @faceclaw_bells window option: tmux's own bell flag misses
|
|
* bells in a session's current window, and this way bells that ring while
|
|
* we're disconnected still show up as a higher count. Bell, activity and
|
|
* title notifications come from diffing successive listings.
|
|
*
|
|
* - The viewer (after connectSession): a tmux control-mode client
|
|
* (`tmux -C attach-session`) on the pane's session. It never changes the
|
|
* session's current window or active pane, so a desktop client attached to
|
|
* the same session is undisturbed. Viewing sets a per-window size for this
|
|
* client (`refresh-client -C @W:WxH`, which resizes the window to the
|
|
* glasses while we look, and restores it when cleared), snapshots the pane
|
|
* with capture-pane, and then applies its %output stream. Unviewing pauses
|
|
* the pane's output to this client (`refresh-client -A %N:pause`; "off"
|
|
* would make tmux stop reading the pane altogether when no other client
|
|
* wants it, stalling the program). Output from the session's other panes is
|
|
* paused as soon as it shows up.
|
|
*
|
|
* Requires tmux 3.2+ (control-mode pause/continue and per-window sizes);
|
|
* older versions get a message asking for an upgrade. 3.8's history_added /
|
|
* history_collected make scrollback paging exact; before that it assumes
|
|
* the history hasn't hit its limit since the snapshot.
|
|
*/
|
|
import type { G2MirrorHistoryReply, G2MirrorPhase, G2MirrorSession, G2MirrorState } from "./terminal-client";
|
|
|
|
export const TMUX_MIN_VERSION: [number, number] = [3, 2];
|
|
|
|
export type LineChannelListener = {
|
|
onOpen(): void;
|
|
/** One stdout line (see native/ssh escapeLine for non-UTF-8 lines). */
|
|
onLine(line: string): void;
|
|
onStderr(line: string): void;
|
|
onClosed(exitStatus: number | null): void;
|
|
onFailure(message: string): void;
|
|
};
|
|
|
|
export type LineChannel = {
|
|
send(line: string): boolean;
|
|
close(): void;
|
|
};
|
|
|
|
/** Run `command` on the host (through the user's login shell, like ssh does). */
|
|
export type OpenLineChannel = (command: string, listener: LineChannelListener) => LineChannel;
|
|
|
|
export type TmuxClientOptions = {
|
|
openChannel: OpenLineChannel;
|
|
/** How status lines name the host, e.g. "jim@laptop". */
|
|
label: string;
|
|
/** Grid the glasses view sessions at. */
|
|
cols: number;
|
|
rows: number;
|
|
/**
|
|
* Remembers per-window bell counts across client instances (the worker
|
|
* makes a new client per reconnect), so a bell that rang while we were
|
|
* disconnected is still reported. The connection id for the client that
|
|
* watches bells; "" (counts kept per instance) for view clients, which
|
|
* mustn't consume bells the watching client hasn't seen yet.
|
|
*/
|
|
stateKey: string;
|
|
};
|
|
|
|
const POLL_INTERVAL_S = 2;
|
|
const BELL_HOOK_INDEX = 7091;
|
|
const LAUNCH_TIMEOUT_MS = 15_000;
|
|
const SUBMIT_DELAY_MS = 150;
|
|
// send-keys -H takes one argument per byte; keep command lines modest.
|
|
const SEND_KEYS_CHUNK_BYTES = 256;
|
|
// How many listings connectSession waits for a just-launched pane to appear.
|
|
const CONNECT_WAIT_POLLS = 4;
|
|
|
|
// ---- host-side scripts ----
|
|
|
|
const TMUX_CANDIDATES = [
|
|
"/opt/homebrew/bin/tmux",
|
|
"/usr/local/bin/tmux",
|
|
'"$HOME/.local/bin/tmux"',
|
|
'"$HOME/bin/tmux"',
|
|
"/home/linuxbrew/.linuxbrew/bin/tmux",
|
|
'"$HOME/.nix-profile/bin/tmux"',
|
|
"/run/current-system/sw/bin/tmux",
|
|
"/snap/bin/tmux",
|
|
];
|
|
|
|
/**
|
|
* Wrap a /bin/sh script as an exec command. The command runs under the
|
|
* user's login shell, which may be bash, zsh, fish or csh, so it stays a
|
|
* single line whose only quoting is one pair of single quotes, and the
|
|
* script may contain neither single quotes nor "\\" (fish treats \\ and \'
|
|
* specially inside single quotes; any other backslash is literal in all of
|
|
* them).
|
|
*/
|
|
export function hostCommand(script: string): string {
|
|
if (script.includes("'") || script.includes("\\\\") || /[\r\n]/.test(script)) {
|
|
throw new Error("host script contains characters that can't be quoted portably");
|
|
}
|
|
return `exec /bin/sh -c '${script}'`;
|
|
}
|
|
|
|
/**
|
|
* Sets T to the tmux binary: PATH as the exec shell sees it, then PATH as a
|
|
* login shell sees it (Homebrew/Nix/~/.local installs are often only on the
|
|
* login PATH), then common install locations.
|
|
*/
|
|
function locateTmux(): string {
|
|
return [
|
|
"T=$(command -v tmux 2>/dev/null)",
|
|
'[ -x "$T" ] || T=$("${SHELL:-/bin/sh}" -lc "command -v tmux" 2>/dev/null </dev/null | tail -n 1)',
|
|
`for c in ${TMUX_CANDIDATES.join(" ")}; do [ -x "$T" ] && break; T=$c; done`,
|
|
'[ -x "$T" ] || { echo FACECLAW-NO-TMUX; exit 127; }',
|
|
].join("; ");
|
|
}
|
|
|
|
// Listing fields, tab-separated, title last (it may contain tabs itself).
|
|
const PANE_FIELDS = [
|
|
"#{pane_id}",
|
|
"#{session_id}",
|
|
"#{session_name}",
|
|
"#{window_id}",
|
|
"#{window_index}",
|
|
"#{window_name}",
|
|
"#{window_panes}",
|
|
"#{pane_index}",
|
|
"#{pane_pid}",
|
|
"#{pane_dead}",
|
|
// Per-pane output time (3.8+), else per-window activity; seconds either way.
|
|
"#{?pane_last_output_time,#{pane_last_output_time},#{window_activity}}",
|
|
"#{@faceclaw_bells}",
|
|
"#{pane_current_command}",
|
|
"#{pane_current_path}",
|
|
"#{pane_title}",
|
|
];
|
|
|
|
export function pollerCommand(): string {
|
|
const format = PANE_FIELDS.join("\t");
|
|
const hook = 'set -wF @faceclaw_bells \\"#{e|+:#{@faceclaw_bells},1}\\"';
|
|
return hostCommand(
|
|
[
|
|
locateTmux(),
|
|
'echo "FACECLAW-TMUX $("$T" -V 2>&1)"',
|
|
'echo "FACECLAW-HOST $(hostname 2>/dev/null)"',
|
|
'echo "FACECLAW-HOME $HOME"',
|
|
`F="${format}"`,
|
|
`H="${hook}"`,
|
|
"P=-",
|
|
// Print the listing only when it changed. No server running: the
|
|
// listing is empty.
|
|
`while :; do O=$("$T" set-hook -g "alert-bell[${BELL_HOOK_INDEX}]" "$H" \\; list-panes -a -F "$F" 2>/dev/null); ` +
|
|
`if [ "$O" != "$P" ]; then echo FACECLAW-BEGIN; printf "%s\\n" "$O"; echo FACECLAW-END; P=$O; fi; sleep ${POLL_INTERVAL_S}; done`,
|
|
].join("; "),
|
|
);
|
|
}
|
|
|
|
export function viewerCommand(sessionId: string): string {
|
|
if (!/^\$\d+$/.test(sessionId)) throw new Error(`bad tmux session id ${sessionId}`);
|
|
// "\$" keeps /bin/sh from expanding the session id ($3) as a variable.
|
|
return hostCommand(`${locateTmux()}; exec "$T" -C attach-session -t "\\${sessionId}"`);
|
|
}
|
|
|
|
const SAFE_LAUNCH_COMMAND = /^[A-Za-z0-9 ._/+:=@%,-]+$/;
|
|
|
|
/** New detached session running `preset` ("shell" or "": the default shell). */
|
|
export function launchCommand(preset: string): string {
|
|
const command = preset === "shell" ? "" : preset.trim();
|
|
if (command && !SAFE_LAUNCH_COMMAND.test(command)) {
|
|
throw new Error(`Launch preset "${preset}" has characters that can't be passed to tmux.`);
|
|
}
|
|
return hostCommand(
|
|
`${locateTmux()}; exec "$T" new-session -d -P -F "FACECLAW-LAUNCHED #{pane_id} #{session_id}"${command ? ` "${command}"` : ""}`,
|
|
);
|
|
}
|
|
|
|
// ---- parsing helpers ----
|
|
|
|
/** Parse `tmux -V` output; null for builds without a numeric version (master), treated as new. */
|
|
export function parseTmuxVersion(text: string): [number, number] | null {
|
|
const match = /(\d+)\.(\d+)/.exec(text);
|
|
return match ? [parseInt(match[1]!, 10), parseInt(match[2]!, 10)] : null;
|
|
}
|
|
|
|
export function tmuxVersionSupported(text: string): boolean {
|
|
const version = parseTmuxVersion(text);
|
|
if (!version) return true;
|
|
const [major, minor] = version;
|
|
return major > TMUX_MIN_VERSION[0] || (major === TMUX_MIN_VERSION[0] && minor >= TMUX_MIN_VERSION[1]);
|
|
}
|
|
|
|
export type PaneRow = {
|
|
paneId: string;
|
|
sessionId: string;
|
|
sessionName: string;
|
|
windowId: string;
|
|
windowIndex: string;
|
|
windowName: string;
|
|
windowPanes: number;
|
|
paneIndex: string;
|
|
pid: number;
|
|
dead: boolean;
|
|
/** Last output (or window activity), seconds, host clock. */
|
|
activity: number;
|
|
bells: number;
|
|
command: string;
|
|
path: string;
|
|
title: string;
|
|
};
|
|
|
|
export function parsePaneRow(line: string): PaneRow | null {
|
|
const fields = line.split("\t");
|
|
if (fields.length < PANE_FIELDS.length || !fields[0]!.startsWith("%")) return null;
|
|
const title = fields.slice(PANE_FIELDS.length - 1).join("\t");
|
|
return {
|
|
paneId: fields[0]!,
|
|
sessionId: fields[1]!,
|
|
sessionName: fields[2]!,
|
|
windowId: fields[3]!,
|
|
windowIndex: fields[4]!,
|
|
windowName: fields[5]!,
|
|
windowPanes: parseInt(fields[6]!, 10) || 1,
|
|
paneIndex: fields[7]!,
|
|
pid: parseInt(fields[8]!, 10) || 0,
|
|
dead: fields[9] === "1",
|
|
activity: parseInt(fields[10]!, 10) || 0,
|
|
bells: parseInt(fields[11]!, 10) || 0,
|
|
command: fields[12]!,
|
|
path: fields[13]!,
|
|
title,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* A row's label in the session list: "session:window[.pane] <title>", where
|
|
* the title is what the program set (OSC 0/2) or, when it hasn't set one
|
|
* (tmux's default title is the host name), the running command and its
|
|
* directory.
|
|
*/
|
|
export function paneLabel(row: PaneRow, hostName: string, home: string): string {
|
|
const where = `${row.sessionName}:${row.windowIndex}${row.windowPanes > 1 ? `.${row.paneIndex}` : ""}`;
|
|
const shortHost = hostName.split(".")[0] ?? "";
|
|
const meaningfulTitle = row.title && row.title !== hostName && row.title !== shortHost ? row.title : "";
|
|
if (meaningfulTitle) return `${where} ${meaningfulTitle}`;
|
|
const path = home && (row.path === home || row.path.startsWith(`${home}/`)) ? `~${row.path.slice(home.length)}` : row.path;
|
|
return `${where} ${row.command}${path ? ` ${path}` : ""}`;
|
|
}
|
|
|
|
/**
|
|
* Decode a tmux control-mode %output value to bytes: "\ooo" is an octal
|
|
* byte (tmux escapes control characters and backslashes this way, and the
|
|
* SSH transport escapes bytes of lines that aren't valid UTF-8 the same
|
|
* way); any other character is UTF-8 encoded.
|
|
*/
|
|
export function decodeTmuxOutput(value: string): Uint8Array {
|
|
const bytes: number[] = [];
|
|
for (let i = 0; i < value.length; i++) {
|
|
const code = value.charCodeAt(i);
|
|
if (code === 0x5c && i + 3 < value.length && /^[0-7]{3}$/.test(value.slice(i + 1, i + 4))) {
|
|
bytes.push(parseInt(value.slice(i + 1, i + 4), 8) & 0xff);
|
|
i += 3;
|
|
continue;
|
|
}
|
|
pushUtf8(bytes, value, i);
|
|
if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length) i++;
|
|
}
|
|
return Uint8Array.from(bytes);
|
|
}
|
|
|
|
function pushUtf8(bytes: number[], text: string, index: number): void {
|
|
const point = text.codePointAt(index)!;
|
|
if (point < 0x80) bytes.push(point);
|
|
else if (point < 0x800) bytes.push(0xc0 | (point >> 6), 0x80 | (point & 0x3f));
|
|
else if (point < 0x10000) bytes.push(0xe0 | (point >> 12), 0x80 | ((point >> 6) & 0x3f), 0x80 | (point & 0x3f));
|
|
else
|
|
bytes.push(
|
|
0xf0 | (point >> 18),
|
|
0x80 | ((point >> 12) & 0x3f),
|
|
0x80 | ((point >> 6) & 0x3f),
|
|
0x80 | (point & 0x3f),
|
|
);
|
|
}
|
|
|
|
export function encodeUtf8(text: string): Uint8Array {
|
|
const bytes: number[] = [];
|
|
for (let i = 0; i < text.length; i++) {
|
|
const code = text.charCodeAt(i);
|
|
pushUtf8(bytes, text, i);
|
|
if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) i++;
|
|
}
|
|
return Uint8Array.from(bytes);
|
|
}
|
|
|
|
// Pane state read for a snapshot, '|'-separated (all numeric but the id).
|
|
const SNAPSHOT_FIELDS = [
|
|
"#{pane_id}",
|
|
"#{cursor_x}",
|
|
"#{cursor_y}",
|
|
"#{cursor_flag}",
|
|
"#{keypad_cursor_flag}",
|
|
"#{keypad_flag}",
|
|
"#{wrap_flag}",
|
|
"#{insert_flag}",
|
|
"#{alternate_on}",
|
|
"#{scroll_region_upper}",
|
|
"#{scroll_region_lower}",
|
|
"#{pane_width}",
|
|
"#{pane_height}",
|
|
"#{history_size}",
|
|
"#{history_added}",
|
|
"#{history_collected}",
|
|
"#{history_generation}",
|
|
];
|
|
|
|
export type PaneState = {
|
|
paneId: string;
|
|
cursorX: number;
|
|
cursorY: number;
|
|
cursorVisible: boolean;
|
|
appCursorKeys: boolean;
|
|
appKeypad: boolean;
|
|
wrap: boolean;
|
|
insert: boolean;
|
|
alternate: boolean;
|
|
scrollUpper: number;
|
|
scrollLower: number;
|
|
width: number;
|
|
height: number;
|
|
/** Absolute index of the next line to enter the history (history_added, else history_size). */
|
|
historyNext: number;
|
|
/** Oldest retained absolute index (history_collected, else 0). */
|
|
historyOldest: number;
|
|
generation: string;
|
|
};
|
|
|
|
export function parsePaneState(line: string): PaneState | null {
|
|
const f = line.split("|");
|
|
if (f.length < SNAPSHOT_FIELDS.length || !f[0]!.startsWith("%")) return null;
|
|
const n = (index: number) => parseInt(f[index]!, 10) || 0;
|
|
const exact = f[14] !== "";
|
|
return {
|
|
paneId: f[0]!,
|
|
cursorX: n(1),
|
|
cursorY: n(2),
|
|
cursorVisible: f[3] !== "0",
|
|
appCursorKeys: f[4] === "1",
|
|
appKeypad: f[5] === "1",
|
|
wrap: f[6] !== "0",
|
|
insert: f[7] === "1",
|
|
alternate: f[8] === "1",
|
|
scrollUpper: n(9),
|
|
scrollLower: n(10),
|
|
width: n(11),
|
|
height: n(12),
|
|
historyNext: exact ? n(14) : n(13),
|
|
historyOldest: exact ? n(15) : 0,
|
|
generation: f[16] ?? "",
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Terminal bytes that recreate a captured pane in a freshly reset emulator:
|
|
* the normal screen (when the pane is in the alternate screen), the visible
|
|
* lines, then cursor position and the modes that change how keys encode.
|
|
*/
|
|
export function snapshotBytes(state: PaneState, visible: string[], normalScreen: string[]): Uint8Array {
|
|
let out = "";
|
|
const rows = (lines: string[]) => lines.slice(0, Math.max(1, state.height)).join("\x1b[0m\r\n");
|
|
if (state.alternate) {
|
|
out += rows(normalScreen) + "\x1b[0m\x1b[?1049h\x1b[H";
|
|
}
|
|
out += rows(visible) + "\x1b[0m";
|
|
if (state.scrollUpper !== 0 || state.scrollLower !== state.height - 1) {
|
|
out += `\x1b[${state.scrollUpper + 1};${state.scrollLower + 1}r`;
|
|
}
|
|
out += `\x1b[${state.cursorY + 1};${state.cursorX + 1}H`;
|
|
if (!state.cursorVisible) out += "\x1b[?25l";
|
|
if (state.appCursorKeys) out += "\x1b[?1h";
|
|
if (state.appKeypad) out += "\x1b=";
|
|
if (!state.wrap) out += "\x1b[?7l";
|
|
if (state.insert) out += "\x1b[4h";
|
|
return encodeUtf8(out);
|
|
}
|
|
|
|
/** send-keys -H commands typing `bytes` into pane `paneId`. */
|
|
export function sendKeysCommands(paneId: string, bytes: Uint8Array): string[] {
|
|
const commands: string[] = [];
|
|
for (let start = 0; start < bytes.length; start += SEND_KEYS_CHUNK_BYTES) {
|
|
const hex = Array.from(bytes.subarray(start, start + SEND_KEYS_CHUNK_BYTES), (byte) => byte.toString(16).padStart(2, "0"));
|
|
commands.push(`send-keys -t ${paneId} -H ${hex.join(" ")}`);
|
|
}
|
|
return commands;
|
|
}
|
|
|
|
// ---- client ----
|
|
|
|
type Block = { ok: boolean; lines: string[] };
|
|
type PendingCommands = { count: number; blocks: Block[]; done: (blocks: Block[]) => void };
|
|
type BellMemory = Map<string, { count: number; lastBellAt: number | null }>;
|
|
|
|
const bellMemoryByKey = new Map<string, BellMemory>();
|
|
|
|
export class TmuxClient {
|
|
private phase: G2MirrorPhase = "idle";
|
|
private status = "Not connected.";
|
|
private retryable = true;
|
|
private stopped = false;
|
|
private generation = 0;
|
|
|
|
private poller: LineChannel | null = null;
|
|
private pollerLines: string[] | null = null;
|
|
private versionText = "";
|
|
private hostName = "";
|
|
private home = "";
|
|
private rows = new Map<string, PaneRow>();
|
|
private sessions: G2MirrorSession[] = [];
|
|
private listings = 0;
|
|
private pendingConnect: { paneId: string; deadline: number } | null = null;
|
|
|
|
private viewer: LineChannel | null = null;
|
|
private attachedPane: PaneRow | null = null;
|
|
private viewing = false;
|
|
private sizeDirty = false;
|
|
private snapshotInFlight = false;
|
|
private snapshotGeneration = "";
|
|
private pausedPanes = new Set<string>();
|
|
private pending: PendingCommands[] = [];
|
|
private block: { time: string; number: string; ours: boolean; lines: string[] } | null = null;
|
|
private liveCheckInFlight = false;
|
|
private readonly localBellMemory: BellMemory = new Map();
|
|
|
|
private readonly stateListeners = new Set<(state: G2MirrorState) => void>();
|
|
private readonly terminalDataListeners = new Set<(data: Uint8Array, kind: "snapshot" | "output") => void>();
|
|
private readonly snapshotListeners = new Set<(historyNext: number, historyOldest: number) => void>();
|
|
private readonly historyListeners = new Set<(reply: G2MirrorHistoryReply) => void>();
|
|
private readonly attachedListeners = new Set<(command: string) => void>();
|
|
private readonly detachedListeners = new Set<(reason: string) => void>();
|
|
private readonly bellListeners = new Set<(socket: string, lastBellAtMs: number) => void>();
|
|
private readonly activityListeners = new Set<(socket: string, lastOutputAtMs: number) => void>();
|
|
private readonly titleListeners = new Set<(socket: string, title: string) => void>();
|
|
|
|
constructor(private readonly options: TmuxClientOptions) {}
|
|
|
|
state(): G2MirrorState & { retryable: boolean } {
|
|
return {
|
|
phase: this.phase,
|
|
status: this.status,
|
|
sessions: this.sessions.slice(),
|
|
attachedCommand: this.attachedPane ? this.labelFor(this.attachedPane) : "",
|
|
serverName: this.hostName,
|
|
retryable: this.retryable,
|
|
};
|
|
}
|
|
|
|
onStateChange(listener: (state: G2MirrorState) => void): () => void {
|
|
return subscribe(this.stateListeners, listener);
|
|
}
|
|
onTerminalData(listener: (data: Uint8Array, kind: "snapshot" | "output") => void): () => void {
|
|
return subscribe(this.terminalDataListeners, listener);
|
|
}
|
|
onSnapshot(listener: (historyNext: number, historyOldest: number) => void): () => void {
|
|
return subscribe(this.snapshotListeners, listener);
|
|
}
|
|
onHistoryLines(listener: (reply: G2MirrorHistoryReply) => void): () => void {
|
|
return subscribe(this.historyListeners, listener);
|
|
}
|
|
onSessionAttached(listener: (command: string) => void): () => void {
|
|
return subscribe(this.attachedListeners, listener);
|
|
}
|
|
onSessionDetached(listener: (reason: string) => void): () => void {
|
|
return subscribe(this.detachedListeners, listener);
|
|
}
|
|
onBell(listener: (socket: string, lastBellAtMs: number) => void): () => void {
|
|
return subscribe(this.bellListeners, listener);
|
|
}
|
|
onActivity(listener: (socket: string, lastOutputAtMs: number) => void): () => void {
|
|
return subscribe(this.activityListeners, listener);
|
|
}
|
|
onTitle(listener: (socket: string, title: string) => void): () => void {
|
|
return subscribe(this.titleListeners, listener);
|
|
}
|
|
|
|
setViewport(cols: number, rows: number): void {
|
|
if (cols === this.options.cols && rows === this.options.rows) return;
|
|
this.options.cols = cols;
|
|
this.options.rows = rows;
|
|
if (this.viewing) this.snapshot();
|
|
}
|
|
|
|
start(): void {
|
|
if (this.poller || this.viewer) return;
|
|
this.stopped = false;
|
|
this.retryable = true;
|
|
this.resetSessionState();
|
|
this.setState("connecting", `Connecting to ${this.options.label}...`);
|
|
this.openPoller();
|
|
}
|
|
|
|
stop(): void {
|
|
this.stopped = true;
|
|
this.generation++;
|
|
if (this.viewer && this.attachedPane && this.viewing) {
|
|
// Best effort: give the window back its own size before detaching.
|
|
this.viewer.send(`refresh-client -C ${this.attachedPane.windowId}:`);
|
|
}
|
|
this.closeChannels();
|
|
this.resetSessionState();
|
|
this.setState("idle", "Not connected.");
|
|
}
|
|
|
|
listSessions(): void {
|
|
// The poller pushes every change; nothing to ask for.
|
|
}
|
|
|
|
launchSession(preset: string): Promise<string> {
|
|
return new Promise((resolve, reject) => {
|
|
if (this.phase !== "connected" && this.phase !== "attached") {
|
|
reject(new Error("Not connected to tmux."));
|
|
return;
|
|
}
|
|
let command: string;
|
|
try {
|
|
command = launchCommand(preset);
|
|
} catch (error) {
|
|
reject(error);
|
|
return;
|
|
}
|
|
let settled = false;
|
|
let channel: LineChannel | null = null;
|
|
const errors: string[] = [];
|
|
const finish = (error: Error | null, paneId?: string) => {
|
|
if (settled) return;
|
|
settled = true;
|
|
clearTimeout(timer);
|
|
channel?.close();
|
|
if (error) reject(error);
|
|
else resolve(paneId!);
|
|
};
|
|
const timer = setTimeout(() => finish(new Error(`Launch of "${preset}" timed out.`)), LAUNCH_TIMEOUT_MS);
|
|
channel = this.options.openChannel(command, {
|
|
onOpen: () => {},
|
|
onLine: (line) => {
|
|
const match = /^FACECLAW-LAUNCHED (%\d+) (\$\d+)$/.exec(line);
|
|
if (match) finish(null, match[1]);
|
|
else if (line === "FACECLAW-NO-TMUX") finish(new Error("tmux is not installed on the host."));
|
|
},
|
|
onStderr: (line) => errors.push(line),
|
|
onClosed: () => finish(new Error(errors.join(" ") || `Launch of "${preset}" failed.`)),
|
|
onFailure: (message) => finish(new Error(message)),
|
|
});
|
|
if (settled) channel.close();
|
|
});
|
|
}
|
|
|
|
connectSession(paneId: string): void {
|
|
if (this.phase !== "connected") return;
|
|
const row = this.rows.get(paneId);
|
|
if (!row) {
|
|
// Just launched, perhaps: wait a few listings for it to show up.
|
|
this.pendingConnect = { paneId, deadline: this.listings + CONNECT_WAIT_POLLS };
|
|
this.setState(this.phase, "Waiting for the session...");
|
|
return;
|
|
}
|
|
this.pendingConnect = null;
|
|
this.openViewer(row);
|
|
}
|
|
|
|
disconnectSession(): void {
|
|
if (this.phase !== "attached") return;
|
|
this.unview();
|
|
this.viewer?.close();
|
|
this.viewer = null;
|
|
this.attachedPane = null;
|
|
this.setState("idle", "Detached.");
|
|
}
|
|
|
|
view(): void {
|
|
if (this.phase !== "attached" || !this.attachedPane) return;
|
|
this.viewing = true;
|
|
this.snapshot();
|
|
}
|
|
|
|
unview(): void {
|
|
if (this.phase !== "attached" || !this.attachedPane || !this.viewing) return;
|
|
this.viewing = false;
|
|
const pane = this.attachedPane;
|
|
this.command([`refresh-client -A '${pane.paneId}:pause'`, `refresh-client -C ${pane.windowId}:`]);
|
|
}
|
|
|
|
requestHistory(before: number, limit = 200): void {
|
|
if (this.phase !== "attached" || !this.attachedPane) return;
|
|
void this.fetchHistory(this.attachedPane, before, limit);
|
|
}
|
|
|
|
sendInput(text: string): void {
|
|
if (this.phase !== "attached" || !this.attachedPane || !text) return;
|
|
if (this.sizeDirty && this.viewing) {
|
|
// Someone else resized the window since we sized it (window-size
|
|
// "latest" follows the most recently active client). Typing here makes
|
|
// us the active one again: take the size back and resync.
|
|
this.snapshot();
|
|
}
|
|
this.command(sendKeysCommands(this.attachedPane.paneId, encodeUtf8(text)));
|
|
}
|
|
|
|
submitInput(text: string): void {
|
|
if (this.phase !== "attached") return;
|
|
// Like g2mirror's `delays`: a pause before Enter so paste-detecting apps
|
|
// (Claude Code) read it as a keypress, not the tail of a paste.
|
|
if (text) this.sendInput(text);
|
|
const generation = this.generation;
|
|
setTimeout(() => {
|
|
if (generation === this.generation) this.sendInput("\r");
|
|
}, text ? SUBMIT_DELAY_MS : 0);
|
|
}
|
|
|
|
// ---- poller ----
|
|
|
|
private openPoller(): void {
|
|
const generation = this.generation;
|
|
const stderr: string[] = [];
|
|
this.poller = this.options.openChannel(pollerCommand(), {
|
|
onOpen: () => {},
|
|
onLine: (line) => {
|
|
if (generation === this.generation) this.handlePollerLine(line);
|
|
},
|
|
onStderr: (line) => {
|
|
stderr.push(line);
|
|
if (stderr.length > 5) stderr.shift();
|
|
},
|
|
onClosed: (exitStatus) => {
|
|
if (generation !== this.generation || this.phase === "failed") return;
|
|
this.poller = null;
|
|
if (this.phase === "attached") return; // the viewer carries on alone
|
|
const detail = stderr.length ? `: ${stderr[stderr.length - 1]}` : exitStatus !== null ? ` (exit ${exitStatus})` : "";
|
|
this.fail(`Session listing on ${this.options.label} ended${detail}`);
|
|
},
|
|
onFailure: (message) => {
|
|
if (generation !== this.generation) return;
|
|
this.poller = null;
|
|
this.fail(message);
|
|
},
|
|
});
|
|
}
|
|
|
|
private handlePollerLine(line: string): void {
|
|
if (this.pollerLines) {
|
|
if (line === "FACECLAW-END") {
|
|
this.applyListing(this.pollerLines);
|
|
this.pollerLines = null;
|
|
} else {
|
|
this.pollerLines.push(line);
|
|
}
|
|
return;
|
|
}
|
|
if (line === "FACECLAW-BEGIN") {
|
|
this.pollerLines = [];
|
|
} else if (line === "FACECLAW-NO-TMUX") {
|
|
this.retryable = false;
|
|
this.fail(`tmux is not installed on ${this.options.label} (or not on the login shell's PATH).`);
|
|
} else if (line.startsWith("FACECLAW-TMUX ")) {
|
|
this.versionText = line.slice("FACECLAW-TMUX ".length).trim();
|
|
if (!tmuxVersionSupported(this.versionText)) {
|
|
this.retryable = false;
|
|
this.fail(
|
|
`${this.versionText || "tmux"} on ${this.options.label} is too old; Faceclaw needs tmux ${TMUX_MIN_VERSION.join(".")} or newer. Please upgrade it.`,
|
|
);
|
|
}
|
|
} else if (line.startsWith("FACECLAW-HOST ")) {
|
|
this.hostName = line.slice("FACECLAW-HOST ".length).trim();
|
|
} else if (line.startsWith("FACECLAW-HOME ")) {
|
|
this.home = line.slice("FACECLAW-HOME ".length).trim();
|
|
}
|
|
}
|
|
|
|
private applyListing(lines: string[]): void {
|
|
const now = Date.now();
|
|
const previous = this.rows;
|
|
const firstListing = this.listings === 0;
|
|
this.listings++;
|
|
const memory = this.options.stateKey ? bellMemoryFor(this.options.stateKey) : this.localBellMemory;
|
|
const rows = new Map<string, PaneRow>();
|
|
const bellsByWindow = new Map<string, number>();
|
|
for (const line of lines) {
|
|
const row = parsePaneRow(line);
|
|
if (!row || rows.has(row.paneId)) continue;
|
|
rows.set(row.paneId, row);
|
|
bellsByWindow.set(row.windowId, row.bells);
|
|
}
|
|
// Bells are counted per window. A count above the remembered one is a
|
|
// bell (possibly one that rang while we were away); a lower one means the
|
|
// tmux server restarted and reused the id.
|
|
const belledWindows = new Set<string>();
|
|
for (const [windowId, count] of bellsByWindow) {
|
|
const known = memory.get(windowId);
|
|
if (!known) {
|
|
memory.set(windowId, { count, lastBellAt: null });
|
|
} else if (count > known.count) {
|
|
memory.set(windowId, { count, lastBellAt: now });
|
|
belledWindows.add(windowId);
|
|
} else if (count < known.count) {
|
|
memory.set(windowId, { count, lastBellAt: known.lastBellAt });
|
|
}
|
|
}
|
|
this.rows = rows;
|
|
this.sessions = [...rows.values()]
|
|
.filter((row) => !row.dead)
|
|
.map((row) => ({
|
|
socket: row.paneId,
|
|
pid: row.pid,
|
|
cwdHint: row.path.replace(/\//g, "_"),
|
|
lastBellAt: memory.get(row.windowId)?.lastBellAt ?? null,
|
|
lastOutputAt: row.activity ? row.activity * 1000 : null,
|
|
title: this.labelFor(row),
|
|
}));
|
|
if (this.phase === "connecting") {
|
|
this.setState("connected", `Connected to ${this.options.label} (${this.versionText || "tmux"}).`);
|
|
} else {
|
|
this.emitState();
|
|
}
|
|
if (!firstListing) {
|
|
for (const row of rows.values()) {
|
|
const before = previous.get(row.paneId);
|
|
if (belledWindows.has(row.windowId)) {
|
|
const at = memory.get(row.windowId)?.lastBellAt ?? now;
|
|
for (const listener of this.bellListeners) listener(row.paneId, at);
|
|
}
|
|
if (before && row.activity > before.activity) {
|
|
for (const listener of this.activityListeners) listener(row.paneId, row.activity * 1000);
|
|
}
|
|
if (before && row.title !== before.title) {
|
|
for (const listener of this.titleListeners) listener(row.paneId, this.labelFor(row));
|
|
}
|
|
}
|
|
}
|
|
if (this.pendingConnect) {
|
|
const { paneId, deadline } = this.pendingConnect;
|
|
const row = rows.get(paneId);
|
|
if (row) {
|
|
this.pendingConnect = null;
|
|
this.openViewer(row);
|
|
} else if (this.listings >= deadline) {
|
|
this.pendingConnect = null;
|
|
this.setState("connected", "That session no longer exists.");
|
|
for (const listener of this.detachedListeners) listener("session not found");
|
|
}
|
|
}
|
|
}
|
|
|
|
private labelFor(row: PaneRow): string {
|
|
return paneLabel(row, this.hostName, this.home);
|
|
}
|
|
|
|
// ---- viewer ----
|
|
|
|
private openViewer(row: PaneRow): void {
|
|
const generation = this.generation;
|
|
let command: string;
|
|
try {
|
|
command = viewerCommand(row.sessionId);
|
|
} catch (error) {
|
|
this.fail(String((error as Error).message ?? error));
|
|
return;
|
|
}
|
|
this.attachedPane = row;
|
|
this.pausedPanes.clear();
|
|
this.pending = [];
|
|
this.block = null;
|
|
this.setState("connected", "Attaching to session...");
|
|
const stderr: string[] = [];
|
|
let attached = false;
|
|
let attachError = "";
|
|
this.viewer = this.options.openChannel(command, {
|
|
onOpen: () => {},
|
|
onLine: (line) => {
|
|
if (generation !== this.generation) return;
|
|
if (!attached) {
|
|
// The attach-session command's own reply block: %end means tmux
|
|
// attached us, %error (then %exit) that the session is gone.
|
|
if (line.startsWith("%end ")) {
|
|
attached = true;
|
|
// The view needs no listings from here on.
|
|
this.poller?.close();
|
|
this.poller = null;
|
|
this.setState("attached", `Attached to ${this.labelFor(row)}.`);
|
|
for (const listener of this.attachedListeners) listener(this.labelFor(row));
|
|
} else if (!line.startsWith("%") && !attachError) {
|
|
attachError = line;
|
|
}
|
|
return;
|
|
}
|
|
this.handleControlLine(line);
|
|
},
|
|
onStderr: (line) => {
|
|
stderr.push(line);
|
|
if (stderr.length > 5) stderr.shift();
|
|
},
|
|
onClosed: () => {
|
|
if (generation !== this.generation) return;
|
|
this.viewer = null;
|
|
if (!attached && attachError) {
|
|
// E.g. "can't find session": it ended between listing and attaching.
|
|
this.generation++;
|
|
this.closeChannels();
|
|
this.attachedPane = null;
|
|
this.setState("connected", `That session no longer exists (${attachError}).`);
|
|
for (const listener of this.detachedListeners) listener("session not found");
|
|
return;
|
|
}
|
|
if (!attached) {
|
|
this.fail(stderr.length ? `tmux: ${stderr[stderr.length - 1]}` : "tmux refused to attach.");
|
|
return;
|
|
}
|
|
this.sessionEnded("tmux client exited");
|
|
},
|
|
onFailure: (message) => {
|
|
if (generation !== this.generation) return;
|
|
this.viewer = null;
|
|
this.fail(message);
|
|
},
|
|
});
|
|
}
|
|
|
|
private handleControlLine(line: string): void {
|
|
const block = this.block;
|
|
if (block) {
|
|
if (line.startsWith("%end ") || line.startsWith("%error ")) {
|
|
const [, time, number] = line.split(" ");
|
|
if (time === block.time && number === block.number) {
|
|
this.block = null;
|
|
if (block.ours) this.finishBlock({ ok: line.startsWith("%end "), lines: block.lines });
|
|
return;
|
|
}
|
|
}
|
|
block.lines.push(line);
|
|
return;
|
|
}
|
|
const space = line.indexOf(" ");
|
|
const kind = space < 0 ? line : line.slice(0, space);
|
|
switch (kind) {
|
|
case "%begin": {
|
|
const [, time, number, flags] = line.split(" ");
|
|
// flags 1: a command this client sent (0: e.g. the initial attach).
|
|
this.block = { time: time ?? "", number: number ?? "", ours: flags === "1", lines: [] };
|
|
return;
|
|
}
|
|
case "%output": {
|
|
const second = line.indexOf(" ", space + 1);
|
|
if (second < 0) return;
|
|
this.handleOutput(line.slice(space + 1, second), line.slice(second + 1));
|
|
return;
|
|
}
|
|
case "%exit":
|
|
this.sessionEnded(line.length > 6 ? line.slice(6) : "tmux session ended");
|
|
return;
|
|
case "%layout-change": {
|
|
const [, windowId, layout] = line.split(" ");
|
|
const pane = this.attachedPane;
|
|
if (pane && windowId === pane.windowId) {
|
|
const size = /^[0-9a-f]{4},(\d+)x(\d+),/.exec(layout ?? "");
|
|
if (size && this.viewing && (+size[1]! !== this.options.cols || +size[2]! !== this.options.rows)) {
|
|
this.sizeDirty = true;
|
|
}
|
|
this.checkPaneAlive();
|
|
}
|
|
return;
|
|
}
|
|
case "%window-close":
|
|
case "%unlinked-window-close":
|
|
case "%window-pane-changed":
|
|
case "%session-changed":
|
|
this.checkPaneAlive();
|
|
return;
|
|
default:
|
|
// %session-renamed, %window-renamed, %pause, %continue, ...
|
|
return;
|
|
}
|
|
}
|
|
|
|
private handleOutput(paneId: string, value: string): void {
|
|
const pane = this.attachedPane;
|
|
if (!pane || paneId !== pane.paneId) {
|
|
// Another pane in the attached session: we never show it, so stop tmux
|
|
// sending it to us.
|
|
if (!this.pausedPanes.has(paneId) && /^%\d+$/.test(paneId)) {
|
|
this.pausedPanes.add(paneId);
|
|
this.command([`refresh-client -A '${paneId}:pause'`]);
|
|
}
|
|
return;
|
|
}
|
|
// Output that arrives before a snapshot's capture is already in it.
|
|
if (!this.viewing || this.snapshotInFlight) return;
|
|
const bytes = decodeTmuxOutput(value);
|
|
for (const listener of this.terminalDataListeners) listener(bytes, "output");
|
|
}
|
|
|
|
private finishBlock(block: Block): void {
|
|
const pending = this.pending[0];
|
|
if (!pending) return;
|
|
pending.blocks.push(block);
|
|
if (pending.blocks.length >= pending.count) {
|
|
this.pending.shift();
|
|
pending.done(pending.blocks);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Send commands as one line (tmux runs them back to back, so e.g. a
|
|
* capture and the state read with it are consistent); `done` gets one
|
|
* block per command, synchronously as the last one arrives — before any
|
|
* later %output line is handled — or [] if the viewer went away.
|
|
*/
|
|
private command(commands: string[], done: (blocks: Block[]) => void = () => {}): void {
|
|
if (!this.viewer || !commands.length) {
|
|
done([]);
|
|
return;
|
|
}
|
|
this.pending.push({ count: commands.length, blocks: [], done });
|
|
if (!this.viewer.send(commands.join(" ; "))) {
|
|
this.pending.pop();
|
|
done([]);
|
|
}
|
|
}
|
|
|
|
private commandAsync(commands: string[]): Promise<Block[]> {
|
|
return new Promise((resolve) => this.command(commands, resolve));
|
|
}
|
|
|
|
private snapshot(): void {
|
|
const pane = this.attachedPane;
|
|
if (!pane || this.snapshotInFlight) return;
|
|
this.snapshotInFlight = true;
|
|
this.sizeDirty = false;
|
|
const generation = this.generation;
|
|
const { cols, rows } = this.options;
|
|
this.command([
|
|
`refresh-client -C ${pane.windowId}:${cols}x${rows}`,
|
|
`refresh-client -A '${pane.paneId}:continue'`,
|
|
`display -p -t ${pane.paneId} '${SNAPSHOT_FIELDS.join("|")}'`,
|
|
`capture-pane -p -e -t ${pane.paneId}`,
|
|
`capture-pane -p -e -a -q -t ${pane.paneId}`,
|
|
], (blocks) => {
|
|
if (generation !== this.generation) return;
|
|
this.snapshotInFlight = false;
|
|
if (blocks.length < 5 || !this.viewing) return;
|
|
const state = parsePaneState(blocks[2]!.lines[0] ?? "");
|
|
if (!state || state.paneId !== pane.paneId) {
|
|
this.sessionEnded("session closed");
|
|
return;
|
|
}
|
|
this.snapshotGeneration = state.generation;
|
|
const data = snapshotBytes(state, blocks[3]!.lines, blocks[4]!.ok ? blocks[4]!.lines : []);
|
|
for (const listener of this.terminalDataListeners) listener(data, "snapshot");
|
|
for (const listener of this.snapshotListeners) listener(state.historyNext, state.historyOldest);
|
|
});
|
|
}
|
|
|
|
private async fetchHistory(pane: PaneRow, before: number, limit: number): Promise<void> {
|
|
const generation = this.generation;
|
|
const stateCommand = `display -p -t ${pane.paneId} '${SNAPSHOT_FIELDS.join("|")}'`;
|
|
let state = parsePaneState((await this.commandAsync([stateCommand]))[0]?.lines[0] ?? "");
|
|
// Absolute index a is at capture-pane line (a - historyNext). If more
|
|
// lines scroll into the history between our two requests, the offsets go
|
|
// stale; the second request re-reads the state with the capture, so
|
|
// retry until they agree.
|
|
for (let attempt = 0; attempt < 3 && state && generation === this.generation; attempt++) {
|
|
if (state.generation !== this.snapshotGeneration) {
|
|
// History was cleared or reflowed: our indices mean nothing now.
|
|
this.snapshot();
|
|
return;
|
|
}
|
|
const start = Math.max(state.historyOldest, before - limit);
|
|
const end = Math.min(before, state.historyNext);
|
|
if (end <= start) {
|
|
this.emitHistory({ start, oldest: state.historyOldest, next: state.historyNext, lines: [] });
|
|
return;
|
|
}
|
|
const blocks = await this.commandAsync([
|
|
stateCommand,
|
|
`capture-pane -p -t ${pane.paneId} -S ${start - state.historyNext} -E ${end - 1 - state.historyNext}`,
|
|
]);
|
|
if (generation !== this.generation || blocks.length < 2) return;
|
|
const after = parsePaneState(blocks[0]!.lines[0] ?? "");
|
|
if (after && after.historyNext === state.historyNext && after.generation === state.generation) {
|
|
this.emitHistory({
|
|
start,
|
|
oldest: state.historyOldest,
|
|
next: state.historyNext,
|
|
lines: blocks[1]!.ok ? blocks[1]!.lines.slice(0, end - start) : [],
|
|
});
|
|
return;
|
|
}
|
|
state = after;
|
|
}
|
|
}
|
|
|
|
private emitHistory(reply: G2MirrorHistoryReply): void {
|
|
for (const listener of this.historyListeners) listener(reply);
|
|
}
|
|
|
|
/** Something structural changed: make sure our pane still exists. */
|
|
private checkPaneAlive(): void {
|
|
const pane = this.attachedPane;
|
|
if (!pane || this.liveCheckInFlight) return;
|
|
this.liveCheckInFlight = true;
|
|
const generation = this.generation;
|
|
this.command([`display -p -t ${pane.paneId} '#{pane_id} #{window_id}'`], (blocks) => {
|
|
this.liveCheckInFlight = false;
|
|
if (generation !== this.generation || !blocks.length) return;
|
|
const [paneId, windowId] = (blocks[0]!.lines[0] ?? "").split(" ");
|
|
if (paneId !== pane.paneId) {
|
|
this.sessionEnded("session closed");
|
|
} else if (windowId && windowId !== pane.windowId) {
|
|
// The pane moved to another window (break-pane, move-pane).
|
|
this.attachedPane = { ...pane, windowId };
|
|
if (this.viewing) this.snapshot();
|
|
}
|
|
});
|
|
}
|
|
|
|
private sessionEnded(reason: string): void {
|
|
if (this.phase !== "attached") return;
|
|
this.generation++;
|
|
this.closeChannels();
|
|
this.attachedPane = null;
|
|
this.viewing = false;
|
|
this.setState("connected", `Session ended (${reason}).`);
|
|
for (const listener of this.detachedListeners) listener(reason);
|
|
}
|
|
|
|
// ---- shared ----
|
|
|
|
private fail(message: string): void {
|
|
if (this.stopped) return;
|
|
this.generation++;
|
|
this.closeChannels();
|
|
this.attachedPane = null;
|
|
this.viewing = false;
|
|
this.setState("failed", message);
|
|
}
|
|
|
|
private closeChannels(): void {
|
|
this.poller?.close();
|
|
this.poller = null;
|
|
this.viewer?.close();
|
|
this.viewer = null;
|
|
for (const pending of this.pending.splice(0)) pending.done([]);
|
|
this.block = null;
|
|
this.snapshotInFlight = false;
|
|
this.liveCheckInFlight = false;
|
|
}
|
|
|
|
private resetSessionState(): void {
|
|
this.pollerLines = null;
|
|
this.rows = new Map();
|
|
this.sessions = [];
|
|
this.listings = 0;
|
|
this.pendingConnect = null;
|
|
this.attachedPane = null;
|
|
this.viewing = false;
|
|
this.sizeDirty = false;
|
|
}
|
|
|
|
private setState(phase: G2MirrorPhase, status: string): void {
|
|
this.phase = phase;
|
|
this.status = status;
|
|
this.emitState();
|
|
}
|
|
|
|
private emitState(): void {
|
|
const state = this.state();
|
|
for (const listener of this.stateListeners) listener(state);
|
|
}
|
|
}
|
|
|
|
function bellMemoryFor(key: string): BellMemory {
|
|
let memory = bellMemoryByKey.get(key);
|
|
if (!memory) {
|
|
memory = new Map();
|
|
bellMemoryByKey.set(key, memory);
|
|
}
|
|
return memory;
|
|
}
|
|
|
|
function subscribe<T>(set: Set<T>, listener: T): () => void {
|
|
set.add(listener);
|
|
return () => set.delete(listener);
|
|
}
|