Files
faceclaw/app/apps/terminal/terminal-app.worker.ts
T

2706 lines
101 KiB
TypeScript

/**
* Terminal app, hosted in its own worker thread. Window model:
* - "terminal:hub": the window opened from the launcher; shows the list of
* live g2mirror sessions grouped under a heading per configured host
* (unconnected hosts show their state and a Connect row; selecting a
* connected host's heading launches a shell there), and hosts the Manage
* Connections section
* where g2mirror:// connections are added, removed, and toggled.
* - Selecting a session in the hub shows it in the hub's own window: a view
* takes the hub's place in `windows` under the same window id, and
* double-click puts the hub back. The window grows to the view's height
* meanwhile. Sessions already open in a window of their own focus it instead.
* - "terminal:view:N": a session in a window of its own, opened with "Open in
* new window" from the window menu (or by launching a session).
*
* Each view has its own websocket connection (the protocol allows one attached
* session per connection) and its own xterm emulator.
*
* Connections are connection strings stored as JSON in the settings store
* (see connections.ts): g2mirror://<token>@<host>[:port] for a g2mirror
* server (g2mirrors:// for TLS), ssh://<user>@<host> for tmux over SSH
* (TmuxClient), or ssh://<user>@<host>?g2mirror=<token> for a g2mirror server
* tunnelled over SSH. Each enabled connection gets a control client that
* backs the session list and carries bell/title/activity notifications;
* control connections live as long as the worker so bells keep flowing even
* if the hub window is closed. SSH connections that need the user (an
* unverified or changed host key, a password, an unauthorized key) record
* the failure on the control (sshIssue) and offer a page that resolves it
* instead of retrying.
* The host's server_name (from the init reply) is cached per connection and
* used as its display name, falling back to the connection string's
* host[:port] before the first successful handshake.
*
* Bells for a session with an open, non-foregrounded view window set that
* window's sidebar attention flag (cleared by the host on foregrounding).
* Frames are painted here and submitted directly to the Java compositor from
* this worker's thread.
*
* Auto-reconnect (window menu > Settings, default on): while any terminal window
* is open, a dropped control connection reconnects with exponential backoff;
* the first session list after reconnect delivers bells that rang while
* disconnected (attention + wake) via their advanced lastBellAt. A dropped
* view connection reconnects immediately while visible, but a hidden view just
* marks itself stale and reconnects on its next foreground/screen-on — its
* re-attach snapshot resyncs contents and scrollback only once it's needed.
*/
import "@nativescript/core/globals";
import { hasTerminalBackgroundWork } from "./background";
import { finishWorkerShutdown } from "../../ui/shell/worker-lifecycle";
import { GrayImage, type UiFont } from "../../graphics/image";
import { flattenPlanesWithDraws, planesFingerprint, type Plane } from "../../graphics/plane";
import { prepareFrameDraws } from "../../graphics/glyph-wire";
import { getDefaultSmallFont, getTerminalFontConfig } from "../../graphics/ui-fonts";
import { HUB_TITLE_INSET_X, layoutHubHeader } from "./hub-header";
import { TERMINAL_ICON_GLYPHS, type IconActivity } from "../../graphics/icons";
import {
drawSessionRow,
TERMINAL_SESSIONS_STATE_KEY,
type TerminalSessionsSnapshot,
} from "./session-list";
import * as frameTimings from "../../native/frame-timings";
import { getActiveDisplay } from "../../native/active-display";
import { GESTURE_DOUBLE_CLICK, type InputEvent } from "../../ui/gestures";
import type { KeyEvent } from "../../g2/keyboard/keys";
import { encodeTerminalKey, terminalScrollbackKey } from "./terminal-keys";
import { G2MirrorClient, type G2MirrorSession, type G2MirrorState } from "../../native/g2mirror-client";
import type { TerminalClient } from "./terminal-client";
import { TmuxClient, type OpenLineChannel } from "./tmux-client";
import {
copyToPhoneClipboard,
describeSshFailure,
getSshSecret,
openSshChannel,
removeSshSecret,
setSshSecret,
sshClientKey,
type SshEndpoint,
type SshFailure,
type SshHostKey,
} from "../../native/ssh";
import { wrapText } from "../../graphics/textwrap";
import { onSettingsStoreChanged } from "../../native/settings-store";
import { clamp } from "../../util/numeric-util";
import {
enumSettingMenuItem,
terminalAutoReconnectSetting,
terminalDisplayLayoutSetting,
terminalLaunchPresetsSetting,
terminalNewConnectionSetting,
terminalSshPasswordSetting,
terminalWakeOnBellSetting,
textSettingMenuItem,
toggleSettingMenuItem,
} from "../../ui/dashboard-settings";
import { terminalFontPickerMenuItem } from "../../ui/font-picker";
import {
connectionDisplayName,
connectionStringHostLabel,
loadConnections,
parseAnyConnectionString,
saveConnections,
TERMINAL_CONNECTIONS_KEY,
updateConnection,
type TerminalConnection,
} from "./connections";
import { TerminalEmulator } from "./terminal-emulator";
import { drawSubmenuIndicator, submenuItem, type MenuItem } from "../../ui/menu";
import { Menu, type MenuDrawArgs } from "../../ui/menu-core";
import { centeredTextY, lineStep, listRowHeight, textInkHeight } from "../../ui/metrics";
import { WindowMenu, WindowMenuLayer } from "../../ui/window-menu";
import { appViewportSize, type WindowHeightMode } from "../../ui/shell/geometry";
import type { EdgeKind, Edges, Viewport } from "../../ui/viewport";
import type { WorkerAppMessage, WorkerAppReply } from "../../ui/shell/worker-window";
import type { ToolResult, ToolSpec } from "../../assistant/tool-registry";
declare const global: any;
// Cell geometry comes from the terminal font setting (window menu > Settings >
// Font; the default is Terminus-12's 6x12). Each window derives its grid from
// the viewport in its open-window message (the hub is min-height, session
// views full-height). Grid dimensions are baked into each session's websocket
// handshake, so windows and control connections capture the cell size at
// creation — a font change applies to ones (re)opened afterwards.
function chromeFont(): UiFont {
return getDefaultSmallFont();
}
// Grid of a session view window (full-height); also declared on the control
// connections so sessions launched from presets come up at view size.
const VIEW_VIEWPORT = appViewportSize("max");
function viewGrid(): { cols: number; rows: number } {
const { cellWidth, cellHeight } = getTerminalFontConfig();
return {
cols: Math.floor(VIEW_VIEWPORT.width / cellWidth),
rows: Math.floor(VIEW_VIEWPORT.height / cellHeight),
};
}
const DEVICE_NAME = "Faceclaw G2";
const RENDER_COALESCE_MS = 33;
const HISTORY_PAGE = 200;
// Auto-reconnect backoff: doubles per failed attempt, resets on success.
const RECONNECT_MIN_DELAY_MS = 1_000;
const RECONNECT_MAX_DELAY_MS = 60_000;
// Storage key of terminalNewConnectionSetting (the Add-connection draft the
// phone text editor types into); its changes just repaint the add screen.
const NEW_CONNECTION_DRAFT_KEY = "terminal.newConnectionDraft";
// Storage key of terminalLaunchPresetsSetting, edited from the window menu.
const LAUNCH_PRESETS_KEY = "terminal.launchPresets";
// Storage key of terminalSshPasswordSetting (the password page's draft).
const SSH_PASSWORD_DRAFT_KEY = "terminal.sshPasswordDraft";
// Comment on this device's SSH public key in authorized_keys.
const SSH_KEY_COMMENT = "faceclaw";
type BaseWindow = {
windowId: string;
surfaceId: string;
/**
* Window menu title: the shell-side window title, echoed back in the
* open-window message, or the session's label for a view in the hub's window.
*/
title: string;
/** Content viewport from the shell's open-window message; grid = viewport / cell. */
viewportWidth: number;
viewportHeight: number;
/**
* What the viewport's edges touch and the padding suggested for them
* (viewport.ts), as of the last open or resize message. The hub's pages lay
* out inside the padding; a session's grid fills the window regardless.
*/
edges: Edges<EdgeKind>;
padding: Edges<number>;
gridCols: number;
gridRows: number;
foreground: boolean;
/**
* Whether this window is the shell's input target (vs. the sidebar having
* focus). Pushed by the shell on every input/render/foreground message;
* every focus transition triggers one of those, so it never goes stale.
*/
focused: boolean;
renderScheduled: boolean;
lastSubmittedFingerprint: string;
/** Long-press window menu; created on first open. */
menu: WindowMenu | null;
};
/**
* What the hub window is showing: the session list, the Manage Connections
* section, the Add-connection screen (type the connection string on the
* phone, click to save), or a page of text with a click action (verify a
* host key, enter a password, show this device's SSH key).
*/
type HubMode = "sessions" | "connections" | "add" | "page";
type HubPage = {
title: string;
/** Body text, wrapped to the window; re-read on every paint. */
body: () => string;
/** Bottom hint line. */
hint: string;
onClick?: () => void;
/** Double-click. */
onBack: () => void;
/** Runs whenever the page goes away (back, click, window closed). */
onLeave?: () => void;
};
type HubWindow = BaseWindow & {
kind: "hub";
mode: HubMode;
/** The section's item list; created on first paint or input (hubMenu). */
list: Menu<HubItem> | null;
/**
* Session recency keys in display order, captured when the window last
* became visible so the list doesn't reshuffle under the user while it's
* open. Cleared on foreground/screen-on; orderedSessions() rebuilds it
* lazily, sorting by recency and appending sessions that appear while
* visible.
*/
sessionOrder: string[];
/** Parse-failure message shown on the Add-connection screen. */
addError: string;
/** The page shown in mode "page". */
page: HubPage | null;
};
type ViewWindow = BaseWindow & {
kind: "view";
/**
* Set when this view is showing in the hub's window rather than one of its
* own: the hub it replaced, which double-click restores.
*/
hub: HubWindow | null;
/** Grid font and integer cell pitch, captured at window creation. */
font: UiFont;
cellWidth: number;
cellHeight: number;
connectionId: string;
socket: string;
label: string;
/** Sidebar-icon character (">3"); "" if every glyph was taken at open time. */
glyph: string;
client: TerminalClient;
emulator: TerminalEmulator;
receivedData: boolean;
attachRequested: boolean;
status: string;
unsubscribers: Array<() => void>;
// Scrollback model. Absolute line indices span the archive and the emulator:
// indices < historyNext are archived lines; >= historyNext are emulator buffer
// line (index - historyNext). `archive` holds fetched lines [archiveStart,
// historyNext). `scrollTop` is the absolute index of the top visible line, or
// null to follow the live bottom.
historyNext: number;
historyOldest: number;
archive: string[];
archiveStart: number;
scrollTop: number | null;
historyFetchInFlight: boolean;
/**
* The websocket dropped and hasn't been reconnected yet. While the view is
* hidden this just sits set (content resync deferred); the next
* foreground/screen-on reconnects if auto-reconnect is enabled.
*/
needsReconnect: boolean;
reconnectTimer: ReturnType<typeof setTimeout> | null;
reconnectDelayMs: number;
};
type TerminalWindow = HubWindow | ViewWindow;
type PendingView = {
connectionId: string;
socket: string;
label: string;
glyph: string;
/** How to make the view's client, captured when it was requested from a live control. */
options: ClientRecipe;
};
const windows = new Map<string, TerminalWindow>();
const pendingViews = new Map<string, PendingView>();
// Windows waiting on the shell's answer to a set-height-mode, by window id:
// what to do with the viewport it comes back with (see changeWindowHeight).
const pendingHeightChanges = new Map<string, (viewport: Viewport) => void>();
// The view an assistant tool acts on when the terminal isn't foregrounded:
// the last view to be foregrounded or receive input.
let activeViewId: string | null = null;
let nextViewSerial = 1;
/**
* Assistant tools this app contributes, declared on the hub window (which the
* launcher opens and which persists for the app's life). All `open`-tier so
* "rerun the build" works while the terminal is backgrounded. send_input and
* read_screen act on the active view session (see resolveActiveView).
*/
const TERMINAL_TOOLS: ToolSpec[] = [
{
name: "list_sessions",
description: "List the live g2mirror terminal sessions the glasses can see, across every connected host.",
inputSchema: { type: "object", properties: {}, additionalProperties: false },
availability: "open",
},
{
name: "send_input",
description:
"Type a line into the active terminal session and submit it (as if typed and Enter pressed). Use to run a command in the terminal.",
inputSchema: {
type: "object",
properties: { text: { type: "string", description: "The line to type and run." } },
required: ["text"],
additionalProperties: false,
},
availability: "open",
},
{
name: "read_screen",
description: "Return the current visible contents of the active terminal session's screen.",
inputSchema: { type: "object", properties: {}, additionalProperties: false },
availability: "open",
},
{
name: "list_launch_presets",
description:
"List the named launch presets that can start a new terminal session on a host machine (for launch_session).",
inputSchema: { type: "object", properties: {}, additionalProperties: false },
availability: "open",
},
{
name: "launch_session",
description:
"Start a new terminal session on a connected host machine from a named launch preset (see list_launch_presets) and open a window viewing it.",
inputSchema: {
type: "object",
properties: {
preset: { type: "string", description: "Name of the launch preset to start." },
host: {
type: "string",
description: "Which host to launch on (server name), when more than one is connected.",
},
},
required: ["preset"],
additionalProperties: false,
},
availability: "open",
timeoutMs: 15_000,
},
];
let screenOn = true;
/**
* One record per configured connection: the stored config plus the live
* control client (session listing for the hub, unsolicited bell/title
* notifications). `client` is null while the connection is disabled or the
* config doesn't parse.
*/
type ControlConnection = {
config: TerminalConnection;
client: TerminalClient | null;
/**
* An SSH failure only the user can fix (host key to verify, password or
* key needed). Shown on the host's heading with a row that opens the fix;
* reconnects wait for it. Cleared on a successful connection.
*/
sshIssue: SshFailure | null;
state: G2MirrorState | null;
unsubscribers: Array<() => void>;
reconnectTimer: ReturnType<typeof setTimeout> | null;
reconnectDelayMs: number;
sessionsSeeded: boolean;
};
// Keyed by connection id; iteration order mirrors the stored list (rebuilt by
// syncControlsFromSettings). Populated once the app is first opened.
const controls = new Map<string, ControlConnection>();
let controlsInitialized = false;
// When each session last "updated", unix epoch ms: bells, title changes, and
// terminal output from open views. Keys are recencyKey(connectionId, socket).
// Sessions first seen in the initial list after (re)connect are seeded from
// their last bell, since we weren't watching; ones appearing later were just
// created, so they get "now".
const sessionRecency = new Map<string, number>();
// When each session's app last produced output, as LOCAL receive time of the
// server's `activity` push (phone clock — the wire timestamp is host-clock
// and can't be compared against Date.now() across machines). Keys are
// recencyKey(connectionId, socket). A session is "active" (hub rows show an
// animated indicator) while an activity push arrived within the last
// ACTIVITY_ACTIVE_MS; the wrapper reports at most one per 2s while output
// continues, so 5s of slack keeps the indicator lit through the gaps.
const sessionActivity = new Map<string, number>();
const ACTIVITY_ACTIVE_MS = 5_000;
// Alternation period shared by hub rows and sidebar cursors.
const HUB_ANIMATION_STEP_MS = 800;
function recencyKey(connectionId: string, socket: string): string {
return `${connectionId}\n${socket}`;
}
function post(message: WorkerAppReply): void {
global.postMessage(message);
}
// The host queues messages until this arrives: posts to a worker whose bundle
// is still evaluating can be silently dropped (see WorkerAppHost). Top-level
// evaluation is synchronous, so the handler below is installed before any
// queued message can be delivered.
post({ type: "worker-ready" });
global.onmessage = (event: { data: WorkerAppMessage }) => {
const message = event.data;
switch (message.type) {
case "check-idle":
reportIdle();
break;
case "shutdown":
for (const control of controls.values()) stopControl(control);
controls.clear();
finishWorkerShutdown();
break;
case "open-window":
openWindow(message.windowId, message.surfaceId, message.title, message.viewport);
break;
case "resize-window": {
const heightChange = pendingHeightChanges.get(message.windowId);
if (heightChange) {
pendingHeightChanges.delete(message.windowId);
heightChange(message.viewport);
break;
}
const window = windows.get(message.windowId);
if (!window) break;
const resized = window.viewportWidth !== message.viewport.width || window.viewportHeight !== message.viewport.height;
window.viewportWidth = message.viewport.width;
window.viewportHeight = message.viewport.height;
window.edges = message.viewport.edges;
window.padding = message.viewport.padding;
window.menu?.resize(message.viewport);
// A resize at the same size says what the window's edges touch has
// changed. The hub's pages move with their padding; a session's grid
// does not, so it keeps its connection, and only a menu page open over
// it (which lays out in the padding) has anything to repaint.
if (window.kind === "view" && !resized) {
if (window.menu?.isOpen()) scheduleRender(window);
break;
}
if (resized) window.lastSubmittedFingerprint = "";
if (window.kind === "view") {
window.gridCols = Math.floor(window.viewportWidth / window.cellWidth);
window.gridRows = Math.floor(window.viewportHeight / window.cellHeight);
if (window.reconnectTimer) clearTimeout(window.reconnectTimer);
window.reconnectTimer = null;
window.client.stop();
window.client.setViewport(window.gridCols, window.gridRows);
window.emulator.dispose();
window.emulator = new TerminalEmulator(window.gridCols, window.gridRows);
window.receivedData = false;
window.archive = [];
window.scrollTop = null;
reconnectView(window);
}
scheduleRender(window);
break;
}
case "close-window":
closeWindow(message.windowId);
break;
case "input": {
const window = windows.get(message.windowId);
if (!window) {
frameTimings.finishFrame(message.frameId, "discarded: unknown terminal window");
break;
}
window.focused = message.focused;
// Marks the main-thread -> worker hop, which is otherwise an
// unexplained gap inside the shell's handle-input span.
frameTimings.logFrame(message.frameId, `input received in ${message.windowId} worker`);
handleInput(window, message.event as InputEvent, message.frameId);
break;
}
case "text-input": {
const window = windows.get(message.windowId);
// Attached view windows type into their terminal. The hub accepts text
// only on the Add-connection screen, where it fills the draft (voice
// input as an alternative to the phone keyboard). submitInput appends
// Enter ("\r") after a wrapper-side pause so paste-detecting apps
// (e.g. Claude Code) submit instead of inserting a newline.
if (window && window.kind === "view") {
if (message.submit === false) window.client.sendInput(message.text);
else window.client.submitInput(message.text);
} else if (window && window.kind === "hub" && window.mode === "add") {
terminalNewConnectionSetting.set(message.text);
scheduleRender(window);
}
break;
}
case "key": {
const window = windows.get(message.windowId);
if (!window) break;
window.focused = message.focused;
handleKey(window, message.event as KeyEvent);
break;
}
case "render": {
const window = windows.get(message.windowId);
if (!window) break;
window.focused = message.focused;
renderAndSubmit(window, 0);
break;
}
case "foreground": {
const window = windows.get(message.windowId);
if (!window) break;
window.foreground = message.foreground;
window.focused = message.focused;
if (window.foreground && window.kind === "view") {
activeViewId = window.windowId;
maybeReconnectView(window);
}
if (window.foreground && window.kind === "hub") window.sessionOrder = [];
if (window.foreground) renderAndSubmit(window, 0);
updateHubAnimation();
break;
}
case "screen":
screenOn = message.on;
if (screenOn) {
for (const window of windows.values()) {
if (!window.foreground) continue;
// Waking counts as becoming visible: let the session list re-sort.
if (window.kind === "hub") window.sessionOrder = [];
if (window.kind === "view") maybeReconnectView(window);
renderAndSubmit(window, 0);
}
}
updateHubAnimation();
break;
case "tool-call": {
const callId = message.callId;
Promise.resolve(handleTerminalTool(message.name, message.args))
.then((result) => post({ type: "tool-result", callId, result }))
.catch((error) =>
post({
type: "tool-result",
callId,
result: { ok: false, error: String((error as Error)?.message ?? error) },
}),
);
break;
}
case "input-focus":
case "navigation-sensors":
break;
}
};
// React to setting changes (connections edited here or in another isolate,
// the window menu's settings, the Add-connection draft typed on the phone).
onSettingsStoreChanged((key) => {
if (key.startsWith("glanceboard.")) {
reportIdle();
return;
}
if (!key.startsWith("terminal.")) return;
switch (key) {
case TERMINAL_CONNECTIONS_KEY:
// Only once the app has actually been opened.
if (controlsInitialized) syncControlsFromSettings();
renderHubWindows();
reportIdle();
return;
case NEW_CONNECTION_DRAFT_KEY:
case SSH_PASSWORD_DRAFT_KEY:
// Live keystrokes from the phone editor; repaint the add/password screen.
renderHubWindows();
return;
case "terminal.autoReconnect":
if (!terminalAutoReconnectSetting.get()) {
cancelPendingReconnects();
} else if (windows.size > 0 || hasTerminalBackgroundWork()) {
for (const control of controls.values()) {
if ((control.state?.phase ?? "idle") === "failed") scheduleControlReconnect(control);
}
}
return;
case LAUNCH_PRESETS_KEY:
// Live keystrokes from the phone editor (Settings > Launch presets in
// the window menu): repaint its edit page, and the hub, whose host
// headings launch presets.
for (const window of windows.values()) {
if (window.menu?.isOpen()) scheduleRender(window);
}
renderHubWindows();
return;
default:
// wakeOnBell: no connection impact.
return;
}
});
function reportIdle(): void {
if (windows.size === 0 && !hasTerminalBackgroundWork()) post({ type: "worker-idle" });
}
/** Cancel scheduled retries (auto-reconnect turned off); stale views stay marked. */
function cancelPendingReconnects(): void {
for (const control of controls.values()) {
cancelControlReconnect(control);
}
for (const window of windows.values()) {
if (window.kind === "view" && window.reconnectTimer) {
clearTimeout(window.reconnectTimer);
window.reconnectTimer = null;
}
}
}
function openWindow(windowId: string, surfaceId: string, title: string, viewport: Viewport): void {
const pendingView = pendingViews.get(windowId);
if (pendingView) {
pendingViews.delete(windowId);
windows.set(windowId, createViewWindow(windowId, surfaceId, title, viewport, pendingView));
updateHubAnimation();
renderHubWindows();
return;
}
const hubCell = getTerminalFontConfig();
windows.set(windowId, {
kind: "hub",
windowId,
surfaceId,
title,
viewportWidth: viewport.width,
viewportHeight: viewport.height,
edges: viewport.edges,
padding: viewport.padding,
gridCols: Math.floor(viewport.width / hubCell.cellWidth),
gridRows: Math.floor(viewport.height / hubCell.cellHeight),
foreground: false,
focused: false,
renderScheduled: false,
lastSubmittedFingerprint: "",
menu: null,
mode: "sessions",
list: null,
sessionOrder: [],
addError: "",
page: null,
});
// The hub carries the app's assistant tools; declare them once it exists.
post({ type: "set-tools", windowId, tools: TERMINAL_TOOLS });
if (!controlsInitialized) {
syncControlsFromSettings();
}
updateHubAnimation();
}
/** Drop a view's connection for good: its window closed or the hub took its place. */
function stopViewConnection(window: ViewWindow): void {
for (const unsubscribe of window.unsubscribers.splice(0)) {
unsubscribe();
}
if (window.reconnectTimer) {
clearTimeout(window.reconnectTimer);
window.reconnectTimer = null;
}
window.client.stop();
}
function closeWindow(windowId: string): void {
const window = windows.get(windowId);
if (!window) return;
pendingHeightChanges.delete(windowId);
if (window.kind === "view") {
stopViewConnection(window);
}
if (window.kind === "hub" && window.mode === "add") {
// Window closed mid-add: shut the phone editor down.
endAddConnection(window);
}
if (window.kind === "hub" && window.mode === "page") {
// Likewise for a page's phone editor (the password draft).
closeHubPage(window, "sessions");
}
// Likewise for a setting being edited from the window menu.
window.menu?.close();
windows.delete(windowId);
windowIconActivity.delete(windowId);
updateHubAnimation();
// A configured widget owns the control connections after the last window closes.
if (windows.size === 0 && !hasTerminalBackgroundWork()) {
for (const control of controls.values()) {
cancelControlReconnect(control);
}
}
if (activeViewId === windowId) activeViewId = null;
if (window.kind === "view") {
renderHubWindows();
}
}
/**
* How to make clients for a connection: "g2mirror" dials a g2mirror server
* directly, "ssh-g2mirror" reaches one through an SSH tunnel, "tmux" runs
* tmux control mode over SSH.
*/
type ClientRecipe = {
kind: "g2mirror" | "ssh-g2mirror" | "tmux";
/**
* `role` "control" watches bells (tmux keeps the bell bookkeeping for that
* client only). `onSshFailure` hears why an SSH channel failed.
*/
create(cols: number, rows: number, role: "control" | "view", onSshFailure?: (failure: SshFailure) => void): TerminalClient;
};
/** Client recipe for a connection string; null if the string doesn't parse. */
function clientOptionsFor(connection: TerminalConnection): ClientRecipe | null {
const parsed = parseAnyConnectionString(connection.url);
if (!parsed) return null;
if (parsed.kind === "g2mirror") {
const { secure, host, port, authToken } = parsed;
return {
kind: "g2mirror",
create: (cols, rows) => new G2MirrorClient({ secure, host, port, authToken, deviceName: DEVICE_NAME, cols, rows }),
};
}
const connectionId = connection.id;
const label = connectionStringHostLabel(connection.url);
// Read at every channel open, so a newly trusted key or saved password
// applies to the next (re)connect, views included.
const endpoint = (): SshEndpoint => ({
host: parsed.host,
port: parsed.port,
user: parsed.user,
hostKeys: loadConnections().find((candidate) => candidate.id === connectionId)?.hostKeys ?? [],
password: getSshSecret(sshPasswordSecretId(connectionId)),
useKey: true,
});
if (parsed.mode === "g2mirror") {
const { authToken, targetHost, targetPort } = parsed;
const urlHost = targetHost.includes(":") && !targetHost.startsWith("[") ? `[${targetHost}]` : targetHost;
const url = `ws://${urlHost}:${targetPort}/`;
return {
kind: "ssh-g2mirror",
create: (cols, rows, _role, onSshFailure) =>
new G2MirrorClient({
secure: false,
host: targetHost,
port: targetPort,
authToken,
deviceName: DEVICE_NAME,
cols,
rows,
transport: {
label: `${label} over SSH`,
open: (listener) => {
const channel = openSshChannel(endpoint(), { type: "websocket", url }, {
onOpen: () => listener.onOpen(),
onText: (text) => listener.onTextMessage(text),
onClosed: (info) => listener.onClosed(info.code ?? 1000, info.reason ?? ""),
onFailure: (failure) => {
onSshFailure?.(failure);
listener.onFailure(describeSshFailure(failure));
},
});
return { sendText: (text) => channel.send(text), sendBinary: () => false, close: () => channel.close() };
},
},
}),
};
}
return {
kind: "tmux",
create: (cols, rows, role, onSshFailure) => {
const openChannel: OpenLineChannel = (command, listener) =>
openSshChannel(endpoint(), { type: "exec", command }, {
onOpen: () => listener.onOpen(),
onText: (line) => listener.onLine(line),
onStderr: (line) => listener.onStderr(line),
onClosed: (info) => listener.onClosed(info.exitStatus ?? null),
onFailure: (failure) => {
onSshFailure?.(failure);
listener.onFailure(describeSshFailure(failure));
},
});
return new TmuxClient({ openChannel, label, cols, rows, stateKey: role === "control" ? connectionId : "" });
},
};
}
function sshPasswordSecretId(connectionId: string): string {
return `terminal.password.${connectionId}`;
}
/** Failures that retrying can't fix: the user has to verify a key or supply credentials. */
function sshFailureNeedsUser(failure: SshFailure): boolean {
return failure.kind === "hostkey-unknown" || failure.kind === "hostkey-mismatch" || failure.kind === "auth";
}
/**
* A control's SSH channel failed. If the user has to act, remember why, and
* if they're looking at the hub's lists, open the page that fixes it.
*/
function noteSshFailure(control: ControlConnection, failure: SshFailure): void {
if (!sshFailureNeedsUser(failure) || controls.get(control.config.id) !== control || !control.client) return;
control.sshIssue = failure;
renderHubWindows();
for (const window of windows.values()) {
if (window.kind === "hub" && window.foreground && (window.mode === "sessions" || window.mode === "connections")) {
openSshIssuePage(window, control);
break;
}
}
}
/**
* Reconcile the live control clients with the stored connection list: start
* enabled connections, stop disabled or removed ones, restart ones whose
* connection string changed. Called on first open and whenever the stored
* list changes (including our own edits). Rebuilds the map in stored order so
* UI iteration matches the list the user manages.
*/
function syncControlsFromSettings(): void {
controlsInitialized = true;
const stored = loadConnections();
const storedIds = new Set(stored.map((connection) => connection.id));
for (const [id, control] of Array.from(controls)) {
if (!storedIds.has(id)) {
stopControl(control);
controls.delete(id);
}
}
const previous = new Map(controls);
controls.clear();
for (const connection of stored) {
let control = previous.get(connection.id);
if (!control) {
control = {
config: connection,
client: null,
sshIssue: null,
state: null,
unsubscribers: [],
reconnectTimer: null,
reconnectDelayMs: RECONNECT_MIN_DELAY_MS,
sessionsSeeded: false,
};
}
const urlChanged = control.config.url !== connection.url;
control.config = connection;
controls.set(connection.id, control);
if (connection.enabled && (urlChanged || !control.client)) {
startControl(control);
} else if (!connection.enabled && control.client) {
stopControl(control);
}
}
renderHubWindows();
}
function startControl(control: ControlConnection): void {
stopControl(control);
const recipe = clientOptionsFor(control.config);
if (!recipe) {
control.state = null;
return;
}
const grid = viewGrid();
const client = recipe.create(grid.cols, grid.rows, "control", (failure) => noteSshFailure(control, failure));
const connectionId = control.config.id;
control.client = client;
control.state = client.state();
control.sessionsSeeded = false;
control.unsubscribers.push(
client.onStateChange((state) => {
// Only the current client speaks for the control (stopControl clears
// listeners, but a stop() emits synchronously before that).
if (control.client !== client) return;
noteSessionListRecency(control, state);
control.state = state;
if (state.phase === "connected") {
control.reconnectDelayMs = RECONNECT_MIN_DELAY_MS;
control.sshIssue = null;
maybeCacheServerName(control, state.serverName);
}
if (state.phase === "failed") scheduleControlReconnect(control);
renderHubWindows();
}),
client.onBell((socket, lastBellAtMs) => {
routeBell(connectionId, socket, lastBellAtMs);
}),
client.onTitle((socket) => {
noteSessionUpdated(connectionId, socket);
}),
client.onActivity((socket) => {
noteSessionActivity(connectionId, socket);
}),
);
client.start();
}
function stopControl(control: ControlConnection): void {
cancelControlReconnect(control);
for (const unsubscribe of control.unsubscribers.splice(0)) {
unsubscribe();
}
control.client?.stop();
control.client = null;
control.state = null;
}
/**
* A successful handshake reported the host's server_name; cache it on the
* stored connection so the hub can name the host even while disconnected.
* The resulting settings change re-runs syncControlsFromSettings, which sees
* an unchanged url and leaves the live client alone.
*/
function maybeCacheServerName(control: ControlConnection, serverName: string): void {
if (!serverName || control.config.serverName === serverName) return;
control.config.serverName = serverName;
updateConnection(control.config.id, { serverName });
}
function noteSessionUpdated(connectionId: string, socket: string): void {
sessionRecency.set(recencyKey(connectionId, socket), Date.now());
}
function noteSessionListRecency(control: ControlConnection, state: G2MirrorState): void {
const connectionId = control.config.id;
for (const session of state.sessions) {
const key = recencyKey(connectionId, session.socket);
const known = sessionRecency.get(key);
if (known === undefined) {
sessionRecency.set(
key,
Math.max(session.lastBellAt ?? 0, control.sessionsSeeded ? Date.now() : 0),
);
} else if ((session.lastBellAt ?? 0) > known) {
// A bell rang while we weren't connected to hear it (the live bell
// message would have advanced the recency); deliver it late so the
// missed attention flag / wake still happens.
routeBell(connectionId, session.socket, session.lastBellAt!);
}
}
if (state.sessions.length) control.sessionsSeeded = true;
}
/**
* Retry a control connection after a backoff delay. The delay doubles per
* scheduled attempt and resets when a connection reaches "connected" (or on
* a manual Connect). Windows and a configured widget can both own the client.
*/
function scheduleControlReconnect(control: ControlConnection): void {
if (control.reconnectTimer) return;
if (!terminalAutoReconnectSetting.get()) return;
if (windows.size === 0 && !hasTerminalBackgroundWork()) return;
if (!control.config.enabled) return;
// Waiting on the user (host key, password) or on the host (no usable tmux).
if (control.sshIssue || control.state?.retryable === false) return;
const delayMs = control.reconnectDelayMs;
control.reconnectDelayMs = Math.min(control.reconnectDelayMs * 2, RECONNECT_MAX_DELAY_MS);
control.reconnectTimer = setTimeout(() => {
control.reconnectTimer = null;
if (!terminalAutoReconnectSetting.get() || (windows.size === 0 && !hasTerminalBackgroundWork())) return;
if (controls.get(control.config.id) !== control || !control.config.enabled) return;
if ((control.state?.phase ?? "idle") === "failed") startControl(control);
}, delayMs);
}
function cancelControlReconnect(control: ControlConnection): void {
if (control.reconnectTimer) {
clearTimeout(control.reconnectTimer);
control.reconnectTimer = null;
}
}
function routeBell(connectionId: string, socket: string, lastBellAtMs: number): void {
const key = recencyKey(connectionId, socket);
const known = sessionRecency.get(key) ?? 0;
if (lastBellAtMs > known) sessionRecency.set(key, lastBellAtMs);
for (const window of windows.values()) {
if (
window.kind === "view" &&
window.connectionId === connectionId &&
window.socket === socket &&
!window.foreground
) {
post({ type: "set-attention", windowId: window.windowId, attention: true });
}
}
if (terminalWakeOnBellSetting.get()) {
// Wake to the belling session's view window, or the hub's window (whatever
// it is showing) if it has none. The shell drops the message unless the
// glasses are actually asleep.
const viewId = viewWindowIdForSocket(connectionId, socket);
const hubId = [...windows.values()].find((window) => window.kind === "hub" || window.hub)?.windowId ?? null;
const target = viewId ?? hubId;
if (target) post({ type: "wake-window", windowId: target });
}
}
function renderHubWindows(): void {
for (const window of windows.values()) {
if (window.kind === "hub") scheduleRender(window);
}
// Every change the hub repaints for is one the published list may reflect.
publishSessionsSnapshot();
}
let lastPublishedSnapshot = "";
/**
* Publish the session list for main-thread consumers (the Glanceboard's
* Terminal widget): connected hosts with their sessions most-recently-updated
* first, each with its activity deadline (local clock, so the consumer can
* expire and animate it itself) and the glyph of its open view window. Posted
* only when the JSON actually changed.
*/
function publishSessionsSnapshot(): void {
const connected = connectedControls();
const snapshot: TerminalSessionsSnapshot = {
hosts: connected.map((control) => {
const connectionId = control.config.id;
const sessions = (control.state?.sessions ?? [])
.slice()
.sort(
(a, b) =>
(sessionRecency.get(recencyKey(connectionId, b.socket)) ?? 0) -
(sessionRecency.get(recencyKey(connectionId, a.socket)) ?? 0),
);
return {
name: connectionDisplayName(control.config),
sessions: sessions.map((session) => ({
key: recencyKey(connectionId, session.socket),
label: sessionLabel(session),
activeUntilMs: (sessionActivity.get(recencyKey(connectionId, session.socket)) ?? -ACTIVITY_ACTIVE_MS) + ACTIVITY_ACTIVE_MS,
openGlyph: viewGlyphForSocket(connectionId, session.socket),
})),
};
}),
status: sessionsStatusLine(),
configured: controls.size > 0,
};
const encoded = JSON.stringify(snapshot);
if (encoded === lastPublishedSnapshot) return;
lastPublishedSnapshot = encoded;
post({ type: "publish-state", key: TERMINAL_SESSIONS_STATE_KEY, state: snapshot });
}
// One animation clock for foreground hub rows and every terminal sidebar icon.
// Keep ticking while the sidebar can show activity, even with the hub closed.
let hubAnimationPhase = 0;
let hubAnimationTimer: ReturnType<typeof setInterval> | null = null;
const windowIconActivity = new Map<string, IconActivity>();
function isSessionActive(connectionId: string, socket: string): boolean {
const at = sessionActivity.get(recencyKey(connectionId, socket));
return at !== undefined && Date.now() - at < ACTIVITY_ACTIVE_MS;
}
function isWindowSessionActive(window: TerminalWindow): boolean {
if (window.kind === "view") return isSessionActive(window.connectionId, window.socket);
const now = Date.now();
return [...sessionActivity.values()].some((at) => now - at < ACTIVITY_ACTIVE_MS);
}
function hubAnimationShouldRun(): boolean {
return screenOn && [...windows.values()].some(isWindowSessionActive);
}
function syncWindowIconActivity(): void {
for (const window of windows.values()) {
const activity: IconActivity = screenOn && isWindowSessionActive(window)
? (hubAnimationPhase === 0 ? "on" : "off") : "idle";
if ((windowIconActivity.get(window.windowId) ?? "idle") === activity) continue;
windowIconActivity.set(window.windowId, activity);
post({ type: "set-icon-activity", windowId: window.windowId, activity });
}
}
/** Start or stop animation and publish changed icons, including expiry/wake. */
function updateHubAnimation(): void {
const shouldRun = hubAnimationShouldRun();
if (shouldRun && !hubAnimationTimer) hubAnimationPhase = 0;
syncWindowIconActivity();
if (shouldRun) {
if (hubAnimationTimer) return;
hubAnimationTimer = setInterval(() => {
hubAnimationPhase = (hubAnimationPhase + 1) % 2;
updateHubAnimation();
// Render even on the stopping tick, to clear expired indicators.
renderHubWindows();
}, HUB_ANIMATION_STEP_MS);
} else if (hubAnimationTimer) {
clearInterval(hubAnimationTimer);
hubAnimationTimer = null;
}
}
/** An activity push arrived for a session: mark it and (re)start the animation. */
function noteSessionActivity(connectionId: string, socket: string): void {
const key = recencyKey(connectionId, socket);
const wasActive = isSessionActive(connectionId, socket);
sessionActivity.set(key, Date.now());
sessionRecency.set(key, Date.now());
updateHubAnimation();
// A session just turned active: show its indicator now rather than up to
// one animation step later.
if (!wasActive) renderHubWindows();
}
function createViewWindow(
windowId: string,
surfaceId: string,
title: string,
viewport: Viewport,
view: PendingView,
): ViewWindow {
const { connectionId, socket, label, glyph } = view;
// Capture the terminal font at open time: the grid dims go into the
// websocket handshake and the emulator, so they must not change under a
// live window (a font-setting change applies to the next window).
const cell = getTerminalFontConfig();
const gridCols = Math.floor(viewport.width / cell.cellWidth);
const gridRows = Math.floor(viewport.height / cell.cellHeight);
const client = view.options.create(gridCols, gridRows, "view");
const window: ViewWindow = {
kind: "view",
hub: null,
windowId,
surfaceId,
title,
viewportWidth: viewport.width,
viewportHeight: viewport.height,
edges: viewport.edges,
padding: viewport.padding,
gridCols,
gridRows,
font: cell.font,
cellWidth: cell.cellWidth,
cellHeight: cell.cellHeight,
foreground: false,
focused: false,
renderScheduled: false,
lastSubmittedFingerprint: "",
menu: null,
connectionId,
socket,
label,
glyph,
client,
emulator: new TerminalEmulator(gridCols, gridRows),
receivedData: false,
attachRequested: false,
status: "Connecting...",
unsubscribers: [],
historyNext: 0,
historyOldest: 0,
archive: [],
archiveStart: 0,
scrollTop: null,
historyFetchInFlight: false,
needsReconnect: false,
reconnectTimer: null,
reconnectDelayMs: RECONNECT_MIN_DELAY_MS,
};
window.unsubscribers.push(
client.onSnapshot((historyNext, historyOldest) => {
// A (re)snapshot resets the emulator, so reset the scroll model too:
// follow the bottom and drop any fetched archive (its splice may move).
window.historyNext = historyNext;
window.historyOldest = historyOldest;
window.archive = [];
window.archiveStart = historyNext;
window.scrollTop = null;
window.historyFetchInFlight = false;
maybePrefetchHistory(window);
scheduleRender(window);
}),
client.onHistoryLines((reply) => {
applyHistoryReply(window, reply);
scheduleRender(window);
}),
client.onStateChange((state) => {
if (state.phase === "connected" && !window.attachRequested) {
window.attachRequested = true;
client.connectSession(socket);
}
if (state.phase === "connected") window.reconnectDelayMs = RECONNECT_MIN_DELAY_MS;
if (state.phase === "failed") handleViewConnectionLost(window);
window.status = state.status;
scheduleRender(window);
}),
client.onSessionAttached(() => {
client.view();
scheduleRender(window);
}),
client.onTerminalData((data, kind) => {
if (kind === "snapshot") {
window.emulator.reset();
}
window.receivedData = true;
noteSessionUpdated(window.connectionId, window.socket);
window.emulator.write(data, () => scheduleRender(window));
}),
client.onSessionDetached((reason) => {
window.status = `Detached (${reason}).`;
scheduleRender(window);
}),
);
client.start();
return window;
}
/**
* The view's websocket dropped. While visible, retry on the backoff schedule;
* while hidden, leave it stale (needsReconnect) so contents and scrollback
* only resync once the view is next looked at. Bells still arrive via the
* control connection either way.
*/
function handleViewConnectionLost(window: ViewWindow): void {
window.needsReconnect = true;
if (window.foreground && screenOn && terminalAutoReconnectSetting.get()) {
scheduleViewReconnect(window);
}
}
function scheduleViewReconnect(window: ViewWindow): void {
if (window.reconnectTimer) return;
const delayMs = window.reconnectDelayMs;
window.reconnectDelayMs = Math.min(window.reconnectDelayMs * 2, RECONNECT_MAX_DELAY_MS);
window.reconnectTimer = setTimeout(() => {
window.reconnectTimer = null;
if (!windows.has(window.windowId) || !window.needsReconnect) return;
if (!terminalAutoReconnectSetting.get()) return;
// Went invisible while waiting: defer to the next foreground/screen-on.
if (!window.foreground || !screenOn) return;
reconnectView(window);
}, delayMs);
}
/** A stale view just became visible (foreground/screen-on): reconnect it now. */
function maybeReconnectView(window: ViewWindow): void {
if (!window.needsReconnect || window.reconnectTimer) return;
if (!terminalAutoReconnectSetting.get()) return;
window.reconnectDelayMs = RECONNECT_MIN_DELAY_MS;
reconnectView(window);
}
/**
* Restart the view's websocket. On success the connected handler re-attaches
* (attachRequested reset here) and the fresh snapshot resets the emulator and
* scrollback archive, which is the content resync.
*/
function reconnectView(window: ViewWindow): void {
window.needsReconnect = false;
window.attachRequested = false;
window.status = "Reconnecting...";
window.client.start();
scheduleRender(window);
}
/** The window's context menu, created lazily so window literals stay simple. */
function windowMenu(window: TerminalWindow): WindowMenu {
if (!window.menu) {
window.menu = new WindowMenu({
windowId: window.windowId,
post,
title: () => window.title,
items: () => windowMenuItems(window),
size: { width: window.viewportWidth, height: window.viewportHeight, edges: window.edges, padding: window.padding },
paintBase: () => paintContent(window),
isFocused: () => window.focused,
});
}
return window.menu;
}
/** Whether a control's handshake has been accepted (it can list and launch sessions). */
function isControlConnected(control: ControlConnection): boolean {
const phase = control.state?.phase;
return phase === "connected" || phase === "attached";
}
/** Controls currently connected (handshake accepted), in stored order. */
function connectedControls(): ControlConnection[] {
return [...controls.values()].filter(isControlConnected);
}
/**
* What the window menu's "Open in new window" does here, if it applies: to the
* session selected in the hub's list, or the session showing in the hub's
* window (which gives way to the list, as a session has one window at a time).
*/
function openInNewWindowAction(window: TerminalWindow): (() => void) | null {
if (window.kind === "hub") {
const row = hubMenu(window).selectedItem?.sessionRow;
if (!row) return null;
return () => {
if (!focusSessionWindow(row.control, row.session)) openViewWindowFor(row.control, row.session);
};
}
const control = window.hub && controls.get(window.connectionId);
if (!control) return null;
return () => returnToHub(window, () => openViewWindow(control, window.socket, window.label));
}
function windowMenuItems(window: TerminalWindow): MenuItem[] {
const items: MenuItem[] = [];
const openInNewWindow = openInNewWindowAction(window);
if (openInNewWindow) {
items.push({
label: "Open in new window",
onSelect: (ctx) => {
ctx.stack.pop();
openInNewWindow();
},
});
}
items.push(
submenuItem("Settings", (ctx) => {
ctx.stack.push(new WindowMenuLayer("Terminal settings", settingsMenuItems()));
}),
);
if (window.kind === "hub") {
const connected = connectedControls();
const multiHost = connected.length > 1;
for (const control of connected) {
for (const preset of launchPresetNames()) {
const label = multiHost
? `Launch ${preset} @ ${connectionDisplayName(control.config)}`
: `Launch ${preset}`;
items.push({
label,
onSelect: (ctx) => {
ctx.stack.pop();
launchFromUi(control, preset);
},
});
}
}
} else {
if (window.client.state().phase === "failed") {
items.push({
label: "Reconnect",
onSelect: (ctx) => {
ctx.stack.pop();
if (window.reconnectTimer) {
clearTimeout(window.reconnectTimer);
window.reconnectTimer = null;
}
window.reconnectDelayMs = RECONNECT_MIN_DELAY_MS;
reconnectView(window);
},
});
}
items.push(
{
label: "Send <Enter>",
onSelect: (ctx) => {
ctx.stack.pop();
window.client.sendInput("\r");
},
},
{
label: "Send <Esc>",
onSelect: (ctx) => {
ctx.stack.pop();
window.client.sendInput("\u001b");
},
},
);
}
return items;
}
/**
* The app's settings (the window menu's Settings submenu). Connections are
* managed in the hub's Manage Connections section instead.
*/
function settingsMenuItems(): MenuItem[] {
return [
enumSettingMenuItem(terminalDisplayLayoutSetting),
terminalFontPickerMenuItem(),
// Opens the phone text editor; the settings listener repaints its page.
textSettingMenuItem(terminalLaunchPresetsSetting),
toggleSettingMenuItem(terminalAutoReconnectSetting),
toggleSettingMenuItem(terminalWakeOnBellSetting),
];
}
function handleInput(window: TerminalWindow, event: InputEvent, frameId: number): void {
if (window.kind === "view") activeViewId = window.windowId;
// An open window menu owns all input (it closes itself via pop).
if (window.menu?.isOpen()) {
void window.menu
.handleInput(event)
.catch((error) => console.error(`terminal menu input failed: ${error}`))
.then(() => renderAndSubmit(window, frameId));
return;
}
if (event.type === "short-then-long-press") {
windowMenu(window).open();
renderAndSubmit(window, frameId);
return;
}
if (event.type === "double-click") {
// Inside the hub's sub-sections and a session shown in its window,
// double-click backs out one level; at the top level (and in views with
// windows of their own) it yields focus to the sidebar as everywhere.
if (window.kind === "view" && window.hub) {
frameTimings.finishFrame(frameId, "discarded: terminal returning to the session list");
returnToHub(window);
return;
}
if (window.kind === "hub" && window.mode === "add") {
cancelAddConnection(window);
renderAndSubmit(window, frameId);
return;
}
if (window.kind === "hub" && window.mode === "page") {
window.page?.onBack();
renderAndSubmit(window, frameId);
return;
}
if (window.kind === "hub" && window.mode === "connections") {
setHubMode(window, "sessions");
renderAndSubmit(window, frameId);
return;
}
frameTimings.finishFrame(frameId, "discarded: terminal yielded focus");
post({ type: "yield-focus", windowId: window.windowId });
return;
}
if (window.kind === "hub") {
handleHubInput(window, event, frameId);
return;
}
// View windows: scroll gestures page through scrollback; text input arrives
// via the separate "text-input" message.
if (event.type === "scroll-up" || event.type === "scroll-down") {
handleViewScroll(window, event.type === "scroll-up" ? -1 : 1, frameId);
return;
}
frameTimings.finishFrame(frameId, "discarded: terminal view ignored input");
}
/**
* A key from a hardware keyboard (the glasses' keyboard bridge) that no
* keybinding claimed. A session with nothing over it gets the key as its
* terminal would: Escape and the arrows belong to the program, and the way
* out is Escape with Shift, Ctrl or Alt, which never arrives here (it is a
* built-in keybinding for "back"). Anywhere else (the hub's lists, an open
* menu) the key is handed back, to act as navigation.
*/
function handleKey(window: TerminalWindow, event: KeyEvent): void {
if (window.kind === "view" && !window.menu?.isOpen()) {
activeViewId = window.windowId;
const page = terminalScrollbackKey(event);
if (page !== null) {
handleViewScroll(window, page, 0);
return;
}
const bytes = encodeTerminalKey(event, window.emulator.applicationCursorKeys());
if (bytes === null) return;
// Typing follows the live screen, as in any terminal emulator.
if (window.scrollTop !== null) {
window.scrollTop = null;
scheduleRender(window);
}
window.client.sendInput(bytes);
return;
}
post({ type: "key-unhandled", windowId: window.windowId, event });
}
/** Top visible absolute line index when following the live bottom. */
function followTop(window: ViewWindow): number {
return window.historyNext + window.emulator.bufferLength() - window.gridRows;
}
function handleViewScroll(window: ViewWindow, direction: -1 | 1, frameId: number): void {
const page = Math.max(1, window.gridRows - 1);
const bottomTop = followTop(window);
const minTop = window.archiveStart;
const currentTop = window.scrollTop ?? bottomTop;
const newTop = clamp(currentTop + direction * page, Math.min(minTop, bottomTop), bottomTop);
// Snapping to (or below) the live bottom re-locks to follow mode.
window.scrollTop = newTop >= bottomTop ? null : newTop;
maybePrefetchHistory(window);
renderAndSubmit(window, frameId);
}
/** Fetch an older page of archive when the view nears the top of what's loaded. */
function maybePrefetchHistory(window: ViewWindow): void {
if (window.historyFetchInFlight) return;
if (window.archiveStart <= window.historyOldest) return; // nothing older retained
const top = window.scrollTop ?? followTop(window);
if (window.archive.length === 0 || top - window.archiveStart <= window.gridRows) {
window.historyFetchInFlight = true;
window.client.requestHistory(window.archiveStart, HISTORY_PAGE);
}
}
function applyHistoryReply(window: ViewWindow, reply: { start: number; oldest: number; lines: string[] }): void {
window.historyFetchInFlight = false;
window.historyOldest = reply.oldest;
if (!reply.lines.length) {
// Nothing older was returned; stop asking below what we already have.
window.historyOldest = window.archiveStart;
return;
}
// The page ends just before our request (archiveStart); prepend it.
if (reply.start < window.archiveStart) {
window.archive = reply.lines.concat(window.archive);
window.archiveStart = reply.start;
}
}
type HubItem = {
label: string;
/**
* Group heading (host name): drawn unindented and dimmer. Selectable only
* when it has an onSelect (launch a shell on that host).
*/
heading?: boolean;
/**
* Top-level action (Manage Connections, Settings): drawn
* unindented like a heading but at full brightness, rather than as an
* indented session row.
*/
topLevel?: boolean;
/** Opens a nested menu: a right-edge ">" marks the row. */
submenu?: boolean;
/** Session with recent output: an animated indicator marks the row. */
active?: boolean;
/** Glyph of the view window showing this session (the number column). */
openGlyph?: string | null;
/** The live session this row lists, for the window menu's "Open in new window". */
sessionRow?: { control: ControlConnection; session: G2MirrorSession };
onSelect?: () => void;
};
/** Vertical offset of a row's text line from the top of its selection box. */
const HUB_ROW_TEXT_INSET = 4;
/** How far the first selection box starts above the list's first text line. */
const HUB_LIST_LEAD = 2;
/** The list's scrollbar (Menu.drawScrollbar's bar), and the gap the selection boxes keep from it. */
const HUB_SCROLLBAR_WIDTH = 3;
const HUB_SCROLLBAR_GAP = 10;
/** How far the scrollbar's track stops short of the rows' span at each end. */
const HUB_SCROLLBAR_INSET = 2;
/**
* Left padding of unindented (heading and top-level) row text inside its
* selection box; the hub's title starts in the same column.
*/
const HUB_TOP_LEVEL_TEXT_X = HUB_TITLE_INSET_X;
/** A page of text's body, indented under its title. */
const PAGE_BODY_INDENT = 6;
/** The hub window's list, created on first use so openWindow stays free of paint dependencies. */
function hubMenu(window: HubWindow): Menu<HubItem> {
window.list ??= new Menu<HubItem>({
wrap: false,
rowGap: 1,
getHeight: () => listRowHeight(chromeFont()),
isSelectable: (item) => Boolean(item.onSelect),
onSelect: (item) => item.onSelect?.(),
draw: drawHubRow,
});
return window.list;
}
function drawHubRow({ image, item, x, y, width, height, selected }: MenuDrawArgs<HubItem>): void {
const font = chromeFont();
if (item.heading || item.topLevel) {
const value = selected ? 255 : item.heading ? 140 : 200;
image.drawText(font, x + HUB_TOP_LEVEL_TEXT_X, y + HUB_ROW_TEXT_INSET, item.label, value);
if (item.submenu) drawSubmenuIndicator(image, font, x, y, width, height, value);
return;
}
// Activity gutter, open-window number column, then the label, truncated
// to the row (shared with the Glanceboard's Terminal widget).
drawSessionRow(image, font, {
x: x + 2,
y: y + HUB_ROW_TEXT_INSET,
width: width - 8,
label: item.label,
openGlyph: item.openGlyph ?? null,
active: Boolean(item.active),
phase: hubAnimationPhase,
value: selected ? 255 : 200,
});
}
/** Switch the hub between its sections, resetting selection state. */
function setHubMode(window: HubWindow, mode: HubMode): void {
window.mode = mode;
window.list?.select(0);
window.addError = "";
}
function openHubPage(window: HubWindow, page: HubPage): void {
if (window.mode === "add") endAddConnection(window);
if (window.mode === "page") window.page?.onLeave?.();
window.page = page;
window.mode = "page";
scheduleRender(window);
}
/** Leave the current page (if any) for `mode`. */
function closeHubPage(window: HubWindow, mode: HubMode): void {
const page = window.page;
window.page = null;
page?.onLeave?.();
setHubMode(window, mode);
scheduleRender(window);
}
/** The list a page returns to: the one it was opened from. */
function hubListMode(window: HubWindow): HubMode {
return window.mode === "connections" ? "connections" : "sessions";
}
function openSshIssuePage(window: HubWindow, control: ControlConnection): void {
const issue = control.sshIssue;
if (!issue) return;
if (issue.kind === "hostkey-unknown" && issue.hostKey) {
openHostKeyPage(window, control, issue.hostKey);
} else if (issue.kind === "hostkey-mismatch" && issue.hostKey) {
openHostKeyChangedPage(window, control, issue.hostKey);
} else if (issue.kind === "auth" && issue.passwordAllowed) {
openPasswordPage(window, control, Boolean(issue.passwordTried));
} else if (issue.kind === "auth") {
openClientKeyPage(window, `${connectionDisplayName(control.config)} didn't accept this device's key (and doesn't take passwords).\n`);
}
}
function hostKeyTypeName(type: string): string {
if (type === "ssh-ed25519") return "ED25519";
if (type.startsWith("ecdsa-")) return "ECDSA";
if (type === "ssh-rsa") return "RSA";
return type;
}
function hostKeyFile(type: string): string {
if (type === "ssh-ed25519") return "/etc/ssh/ssh_host_ed25519_key.pub";
if (type.startsWith("ecdsa-")) return "/etc/ssh/ssh_host_ecdsa_key.pub";
return "/etc/ssh/ssh_host_rsa_key.pub";
}
/** First connection to an SSH host: show the key's fingerprint; click trusts it. */
function openHostKeyPage(window: HubWindow, control: ControlConnection, hostKey: SshHostKey): void {
const returnMode = hubListMode(window);
openHubPage(window, {
title: "Verify host key",
body: () =>
`First connection to ${connectionStringHostLabel(control.config.url)}. Its ${hostKeyTypeName(hostKey.type)} host key fingerprint is:\n` +
`${hostKey.fingerprint}\n\n` +
`To check it, run this on the host and compare:\nssh-keygen -lf ${hostKeyFile(hostKey.type)}`,
hint: `click trust and connect ${GESTURE_DOUBLE_CLICK} cancel`,
onClick: () => {
const hostKeys = [...control.config.hostKeys.filter((key) => key !== hostKey.key), hostKey.key];
control.config.hostKeys = hostKeys;
updateConnection(control.config.id, { hostKeys });
control.sshIssue = null;
closeHubPage(window, returnMode);
connectControl(control);
},
onBack: () => closeHubPage(window, returnMode),
});
}
function openHostKeyChangedPage(window: HubWindow, control: ControlConnection, hostKey: SshHostKey): void {
const returnMode = hubListMode(window);
openHubPage(window, {
title: "HOST KEY CHANGED",
body: () =>
`${connectionStringHostLabel(control.config.url)} presented a different host key than the one trusted before: ` +
`${hostKeyTypeName(hostKey.type)} ${hostKey.fingerprint}\n\n` +
"Someone may be intercepting the connection, so Faceclaw won't connect. If the host was reinstalled or its keys " +
'were regenerated, use "Forget host key" on this connection in Manage Connections, then verify the new fingerprint.',
hint: `${GESTURE_DOUBLE_CLICK} back`,
onBack: () => closeHubPage(window, returnMode),
});
}
/** Ask for the host's password on the phone (masked editor); click saves it and connects. */
function openPasswordPage(window: HubWindow, control: ControlConnection, rejected: boolean): void {
const returnMode = hubListMode(window);
terminalSshPasswordSetting.set("");
post({ type: "start-text-setting-edit", settingId: terminalSshPasswordSetting.id });
openHubPage(window, {
title: "SSH password",
body: () => {
const typed = terminalSshPasswordSetting.get();
return (
(rejected ? "The host refused the saved password.\n" : "") +
`Type the password for ${connectionStringHostLabel(control.config.url)} in the phone app, then click to connect. ` +
"It is saved encrypted on this phone.\n\n" +
(typed ? "*".repeat(Math.min(typed.length, 32)) : "(nothing typed yet)")
);
},
hint: `click connect ${GESTURE_DOUBLE_CLICK} cancel`,
onClick: () => {
const password = terminalSshPasswordSetting.get();
if (!password) return;
setSshSecret(sshPasswordSecretId(control.config.id), password);
control.sshIssue = null;
closeHubPage(window, returnMode);
connectControl(control);
},
onBack: () => closeHubPage(window, returnMode),
onLeave: () => {
terminalSshPasswordSetting.set("");
post({ type: "end-text-setting-edit" });
},
});
}
/** This device's SSH public key (the private half never leaves the keystore); click copies it. */
function openClientKeyPage(window: HubWindow, intro = ""): void {
const returnMode = hubListMode(window);
let key: { authorizedKey: string; fingerprint: string } | null = null;
let error = "";
try {
key = sshClientKey(SSH_KEY_COMMENT);
} catch (caught) {
error = String((caught as Error)?.message ?? caught);
}
let copied = false;
openHubPage(window, {
title: "This device's SSH key",
body: () =>
key
? `${intro}Add this line to ~/.ssh/authorized_keys on each host to log in with this phone's key:\n` +
`${key.authorizedKey}\n${key.fingerprint}` +
(copied ? "\n\nCopied to the phone's clipboard." : "")
: `Couldn't create this device's key: ${error}`,
hint: key ? `click copy to phone clipboard ${GESTURE_DOUBLE_CLICK} back` : `${GESTURE_DOUBLE_CLICK} back`,
onClick: key
? () => {
copyToPhoneClipboard("SSH public key", key!.authorizedKey);
copied = true;
}
: undefined,
onBack: () => closeHubPage(window, returnMode),
});
}
/**
* One control connection's sessions in this hub window's display order:
* most-recently-updated first as of when the window became visible, with
* sessions that appeared since then at the end. The captured order lives in
* window.sessionOrder (cleared when the window becomes visible; keys are
* connection-scoped) so the list doesn't reshuffle while the user is looking
* at it.
*/
function orderedSessions(window: HubWindow, control: ControlConnection): G2MirrorSession[] {
const connectionId = control.config.id;
const sessions = control.state?.sessions ?? [];
const position = new Map<string, number>();
for (const key of window.sessionOrder) {
if (!position.has(key)) position.set(key, position.size);
}
const fresh = sessions
.filter((session) => !position.has(recencyKey(connectionId, session.socket)))
.sort(
(a, b) =>
(sessionRecency.get(recencyKey(connectionId, b.socket)) ?? 0) -
(sessionRecency.get(recencyKey(connectionId, a.socket)) ?? 0),
);
for (const session of fresh) {
const key = recencyKey(connectionId, session.socket);
position.set(key, position.size);
window.sessionOrder.push(key);
}
return sessions
.slice()
.sort(
(a, b) =>
position.get(recencyKey(connectionId, a.socket))! - position.get(recencyKey(connectionId, b.socket))!,
);
}
function hubItems(window: HubWindow): HubItem[] {
return window.mode === "connections" ? hubConnectionItems(window) : hubSessionItems(window);
}
function hubSessionItems(window: HubWindow): HubItem[] {
const items: HubItem[] = [
{
label: "Manage Connections",
topLevel: true,
onSelect: () => setHubMode(window, "connections"),
},
{
label: "Settings",
topLevel: true,
submenu: true,
onSelect: () => windowMenu(window).open(settingsMenuItems(), "Terminal settings"),
},
];
const multiHost = controls.size > 1;
const canLaunch = launchPresetNames().length > 0;
const isTmux = (control: ControlConnection) => clientOptionsFor(control.config)?.kind === "tmux";
// Every configured host is listed under its own heading, in stored order,
// whatever its connection state: a connected host lists its sessions, any
// other shows its state on the heading plus a Connect row (unless it is
// already connecting). Full management (remove, add) lives in Manage
// Connections.
for (const control of controls.values()) {
const name = connectionDisplayName(control.config);
if (!isControlConnected(control)) {
items.push({ label: `${name} (${controlStatusWord(control)})`, heading: true });
if (control.sshIssue && control.config.enabled) {
items.push({ label: sshIssueAction(control.sshIssue), onSelect: () => openSshIssuePage(window, control) });
continue;
}
const connecting = control.config.enabled && control.state?.phase === "connecting";
if (!connecting && clientOptionsFor(control.config)) {
// A failure retrying can't fix (tmux missing or too old) says why;
// selecting it retries once the host is fixed.
const unfixable = control.config.enabled && control.state?.retryable === false;
items.push({
label: unfixable ? control.state!.status : control.reconnectTimer ? "Connect now" : "Connect",
onSelect: () => connectControl(control),
});
}
continue;
}
items.push({
label: name,
heading: true,
// tmux hosts can always start a shell, presets or not.
onSelect: canLaunch || isTmux(control) ? () => launchOnHost(window, control) : undefined,
});
const sessions = orderedSessions(window, control);
for (const session of sessions) {
items.push({
label: sessionLabel(session),
active: isSessionActive(control.config.id, session.socket),
openGlyph: viewGlyphForSocket(control.config.id, session.socket),
sessionRow: { control, session },
onSelect: () => {
if (!focusSessionWindow(control, session)) showSessionInHub(window, control, session);
},
});
}
if (!sessions.length) {
items.push({
label: isTmux(control)
? "(no tmux sessions; select the host to start one)"
: multiHost
? "(no live sessions)"
: "(no live sessions; run g2mirror <command>)",
onSelect: () => control.client?.listSessions(),
});
}
}
return items;
}
function hubConnectionItems(window: HubWindow): HubItem[] {
const items: HubItem[] = [];
for (const control of controls.values()) {
items.push({
label: `${connectionDisplayName(control.config)} (${controlStatusWord(control)})`,
onSelect: () => openConnectionActions(window, control),
});
}
items.push(
{
label: "Add connection",
onSelect: () => beginAddConnection(window),
},
{
label: "This device's SSH key",
onSelect: () => openClientKeyPage(window),
},
{
label: "Done",
onSelect: () => setHubMode(window, "sessions"),
},
);
return items;
}
function controlStatusWord(control: ControlConnection): string {
if (!control.config.enabled) return "off";
const issue = control.sshIssue;
if (issue) {
if (issue.kind === "hostkey-unknown") return "verify host key";
if (issue.kind === "hostkey-mismatch") return "HOST KEY CHANGED";
if (issue.passwordTried) return "password rejected";
return issue.passwordAllowed ? "password needed" : "key not authorized";
}
switch (control.state?.phase) {
case "connected":
case "attached":
return "connected";
case "connecting":
return "connecting";
case "failed":
return control.reconnectTimer ? "retrying" : "failed";
default:
return clientOptionsFor(control.config) ? "off" : "bad connection string";
}
}
/** Per-connection action menu (reuses the window-menu machinery). */
function openConnectionActions(window: HubWindow, control: ControlConnection): void {
const name = connectionDisplayName(control.config);
const items: MenuItem[] = [
control.config.enabled
? {
label: "Disconnect",
onSelect: (ctx) => {
ctx.stack.pop();
disconnectControl(control);
},
}
: {
label: "Connect",
onSelect: (ctx) => {
ctx.stack.pop();
connectControl(control);
},
},
...(control.config.hostKeys.length
? [
{
label: "Forget host key",
onSelect: (ctx: { stack: { pop(): unknown } }) => {
ctx.stack.pop();
control.config.hostKeys = [];
updateConnection(control.config.id, { hostKeys: [] });
control.sshIssue = null;
if (control.config.enabled) startControl(control);
renderHubWindows();
},
},
]
: []),
...(isSshConnection(control) && getSshSecret(sshPasswordSecretId(control.config.id))
? [
{
label: "Forget saved password",
onSelect: (ctx: { stack: { pop(): unknown } }) => {
ctx.stack.pop();
removeSshSecret(sshPasswordSecretId(control.config.id));
},
},
]
: []),
{
label: `Remove ${name}`,
onSelect: (ctx) => {
ctx.stack.pop();
removeControl(control);
},
},
{
label: "Cancel",
onSelect: (ctx) => {
ctx.stack.pop();
},
},
];
windowMenu(window).open(items);
}
function isSshConnection(control: ControlConnection): boolean {
const kind = clientOptionsFor(control.config)?.kind;
return kind === "tmux" || kind === "ssh-g2mirror";
}
/** Enable and (re)connect now; also the manual retry path, so reset backoff. */
function connectControl(control: ControlConnection): void {
control.reconnectDelayMs = RECONNECT_MIN_DELAY_MS;
if (!control.config.enabled) {
control.config.enabled = true;
updateConnection(control.config.id, { enabled: true });
}
startControl(control);
renderHubWindows();
}
function disconnectControl(control: ControlConnection): void {
control.config.enabled = false;
updateConnection(control.config.id, { enabled: false });
stopControl(control);
renderHubWindows();
}
function removeControl(control: ControlConnection): void {
stopControl(control);
removeSshSecret(sshPasswordSecretId(control.config.id));
controls.delete(control.config.id);
saveConnections(loadConnections().filter((connection) => connection.id !== control.config.id));
renderHubWindows();
}
/**
* Enter the Add-connection screen: clear the draft and ask the shell to open
* the phone text editor on it. The user types (or voice-inputs) the
* connection string, then clicks to save or double-clicks to cancel.
*/
function beginAddConnection(window: HubWindow): void {
terminalNewConnectionSetting.set("");
setHubMode(window, "add");
post({ type: "start-text-setting-edit", settingId: terminalNewConnectionSetting.id });
}
function saveAddConnection(window: HubWindow): void {
const url = terminalNewConnectionSetting.get();
if (!parseAnyConnectionString(url)) {
window.addError = url
? "Not an ssh://user@host or g2mirror://token@host string."
: "Enter a connection string first.";
scheduleRender(window);
return;
}
const connections = loadConnections();
connections.push({ id: `c${Date.now()}`, url, serverName: null, enabled: true, hostKeys: [] });
saveConnections(connections);
endAddConnection(window);
setHubMode(window, "connections");
// Start it immediately rather than waiting for the settings-change tick.
syncControlsFromSettings();
}
function cancelAddConnection(window: HubWindow): void {
endAddConnection(window);
setHubMode(window, "connections");
}
/** Common teardown for leaving the add screen: clear draft, close phone editor. */
function endAddConnection(window: HubWindow): void {
window.addError = "";
terminalNewConnectionSetting.set("");
post({ type: "end-text-setting-edit" });
}
function handleHubInput(window: HubWindow, event: InputEvent, frameId: number): void {
if (window.mode === "add") {
if (event.type === "click") {
saveAddConnection(window);
renderAndSubmit(window, frameId);
return;
}
frameTimings.finishFrame(frameId, "discarded: terminal add-connection ignored input");
return;
}
if (window.mode === "page") {
if (event.type === "click" && window.page?.onClick) {
window.page.onClick();
renderAndSubmit(window, frameId);
return;
}
frameTimings.finishFrame(frameId, "discarded: terminal page ignored input");
return;
}
const list = hubMenu(window);
list.setItems(hubItems(window));
switch (event.type) {
case "scroll-up":
case "scroll-down":
case "click":
// The menu's input handler is async only to await onSelect; hub item
// callbacks are synchronous, so the selection move or action has
// already applied when it returns and the frame can paint right away.
list.handleInput(event).catch((error) => console.error("terminal hub action failed", error));
renderAndSubmit(window, frameId);
return;
default:
frameTimings.finishFrame(frameId, "discarded: terminal hub ignored input");
return;
}
}
/**
* Window id of the view already showing this session's terminal, if any.
* Includes views that were requested but whose surface hasn't opened yet, so
* a quick double-select can't spawn two windows for one session.
*/
/** Sidebar glyph of the (open or opening) view window on a session, or null. */
function viewGlyphForSocket(connectionId: string, socket: string): string | null {
for (const window of windows.values()) {
if (window.kind === "view" && window.connectionId === connectionId && window.socket === socket) {
return window.glyph || null;
}
}
for (const pending of pendingViews.values()) {
if (pending.connectionId === connectionId && pending.socket === socket) return pending.glyph || null;
}
return null;
}
function viewWindowIdForSocket(connectionId: string, socket: string): string | null {
for (const window of windows.values()) {
if (window.kind === "view" && window.connectionId === connectionId && window.socket === socket) {
return window.windowId;
}
}
for (const [windowId, pending] of pendingViews) {
if (pending.connectionId === connectionId && pending.socket === socket) return windowId;
}
return null;
}
/** Focus the window already showing a session; false if it has none. */
function focusSessionWindow(control: ControlConnection, session: G2MirrorSession): boolean {
const windowId = viewWindowIdForSocket(control.config.id, session.socket);
if (!windowId) return false;
post({ type: "focus-window", windowId });
return true;
}
function openViewWindowFor(control: ControlConnection, session: G2MirrorSession): void {
openViewWindow(control, session.socket, sessionLabel(session));
}
/**
* Ask the shell to move a window to another height band, then run `apply` with
* the viewport it answers with: only the shell knows what a band comes to (the
* bottom switcher's height lives on the main thread), and a view's grid goes
* into its websocket handshake, so the size has to be right before it starts.
* Ignored if the window is already waiting on an answer (a repeated gesture).
*/
function changeWindowHeight(windowId: string, heightMode: WindowHeightMode, apply: (viewport: Viewport) => void): void {
if (pendingHeightChanges.has(windowId)) return;
pendingHeightChanges.set(windowId, apply);
post({ type: "set-height-mode", windowId, heightMode });
}
/** Make `incoming` what its window id shows, in place of `outgoing`. */
function replaceWindowContent(outgoing: TerminalWindow, incoming: TerminalWindow): void {
incoming.foreground = outgoing.foreground;
incoming.focused = outgoing.focused;
incoming.lastSubmittedFingerprint = "";
// Its pending timers and emulator callbacks must not paint over the surface.
outgoing.foreground = false;
windows.set(incoming.windowId, incoming);
updateHubAnimation();
renderAndSubmit(incoming, 0);
}
/** A session was selected in the list: show it in the hub's own window. */
function showSessionInHub(hub: HubWindow, control: ControlConnection, session: G2MirrorSession): void {
const options = clientOptionsFor(control.config);
if (!options) return;
const label = sessionLabel(session);
// Tall like a session in its own window (see openViewWindow).
changeWindowHeight(hub.windowId, "max", (viewport) => {
const view = createViewWindow(hub.windowId, hub.surfaceId, label, viewport, {
connectionId: control.config.id,
socket: session.socket,
label,
glyph: "",
options,
});
view.hub = hub;
if (hub.foreground) activeViewId = view.windowId;
replaceWindowContent(hub, view);
});
}
/**
* Back from a session in the hub's window to the list. The list keeps the order
* it had, with this session's row selected: viewing a session bumps its
* recency, and re-sorting on every return would shuffle the list while the user
* steps through it. `then` runs once the session's connection is gone.
*/
function returnToHub(view: ViewWindow, then?: () => void): void {
const hub = view.hub;
if (!hub) return;
changeWindowHeight(view.windowId, "min", (viewport) => {
stopViewConnection(view);
view.emulator.dispose();
if (activeViewId === view.windowId) activeViewId = null;
hub.viewportWidth = viewport.width;
hub.viewportHeight = viewport.height;
hub.edges = viewport.edges;
hub.padding = viewport.padding;
hub.menu?.resize(viewport);
const items = hubItems(hub);
const row = items.findIndex(
(item) => item.sessionRow?.control.config.id === view.connectionId && item.sessionRow.session.socket === view.socket,
);
hubMenu(hub).setItems(items, row >= 0 ? row : undefined);
replaceWindowContent(view, hub);
then?.();
});
}
/**
* Lowest unused sidebar-icon character for a new view window (its terminal
* icon shows ">N"). Glyphs free up when their window closes, since usage is
* recomputed from the live windows; "" (plain ">_" icon) if all are taken.
*/
function allocateViewGlyph(): string {
const used = new Set<string>();
for (const window of windows.values()) {
if (window.kind === "view") used.add(window.glyph);
}
for (const pending of pendingViews.values()) used.add(pending.glyph);
for (const glyph of TERMINAL_ICON_GLYPHS) {
if (!used.has(glyph)) return glyph;
}
return "";
}
function openViewWindow(control: ControlConnection, socket: string, label: string): void {
const options = clientOptionsFor(control.config);
if (!options) return;
const windowId = `terminal:view:${nextViewSerial++}`;
const glyph = allocateViewGlyph();
pendingViews.set(windowId, { connectionId: control.config.id, socket, label, glyph, options });
post({
type: "open-window-request",
windowId,
title: label,
iconLetter: "T",
icon: "terminal",
iconGlyph: glyph || undefined,
focus: true,
// Default to tall sessions; the app display setting can override this.
heightMode: "max",
acceptsKeys: true,
});
}
/** Preset names the user listed in the app's settings (the wire protocol has no way to enumerate the server's). */
function launchPresetNames(): string[] {
const names: string[] = [];
for (const piece of terminalLaunchPresetsSetting.get().split(",")) {
const name = piece.trim();
if (name && !names.includes(name)) names.push(name);
}
return names;
}
/**
* A host heading in the hub was selected: launch a shell there. With a single
* launch preset it starts right away; with several, a submenu titled with the
* host's name picks which.
*/
function launchOnHost(window: HubWindow, control: ControlConnection): void {
const presets = launchPresetNames();
if (presets.length === 0) {
// A tmux host with no presets configured: a new session running the login shell.
launchFromUi(control, "shell");
return;
}
if (presets.length === 1) {
launchFromUi(control, presets[0]!);
return;
}
windowMenu(window).open(
presets.map((preset) => ({
label: `Launch ${preset}`,
onSelect: (ctx) => {
ctx.stack.pop();
launchFromUi(control, preset);
},
})),
connectionDisplayName(control.config),
);
}
/** Launch started from a menu or list row; failures only get logged. */
function launchFromUi(control: ControlConnection, preset: string): void {
launchAndOpenView(control, preset).catch((error) => {
// The hub status line also shows the server's error message.
console.warn(`terminal launch ${preset} failed: ${error}`);
});
}
/** Launch a preset on a host and open a view window on the new session. */
async function launchAndOpenView(control: ControlConnection, preset: string): Promise<string> {
if (!control.client) throw new Error("Not connected to the g2mirror server.");
const socket = await control.client.launchSession(preset);
openViewWindow(control, socket, preset);
return socket;
}
function paint(window: TerminalWindow): Plane[] {
return windowMenu(window).paint();
}
function paintContent(window: TerminalWindow): GrayImage {
return window.kind === "hub" ? paintHub(window) : paintView(window);
}
function paintHub(window: HubWindow): GrayImage {
if (window.mode === "add") {
return paintAddConnection(window);
}
if (window.mode === "page" && window.page) {
return paintHubPage(window, window.page);
}
const { viewportWidth: width, viewportHeight: height, padding } = window;
const image = new GrayImage(width, height, 0);
const font = chromeFont();
const step = lineStep(font);
// The header stays put inside the window's top padding, its title in line
// with the rows' text. Long statuses get a wrapped block and move the list
// below it.
const title = window.mode === "connections" ? "Terminal - Connections" : "Terminal";
const header = layoutHubHeader(font, title, hubStatusLine(window), { width, padding }, step);
image.drawText(font, header.titleX, header.titleY, title, 220);
header.lines.forEach((line, index) => image.drawText(font, header.x, header.y + index * step, line, 170));
let listTop = header.listTop;
if (window.mode === "sessions" && controls.size === 0) {
image.drawText(font, header.titleX, listTop, "Add an ssh:// (tmux) or g2mirror:// connection to get started, see:", 150);
image.drawText(font, header.titleX, listTop + step, "https://github.com/jimrandomh/g2mirror", 190);
listTop += 2 * step + 6;
}
const list = hubMenu(window);
list.setItems(hubItems(window));
// Selection boxes start at the left padding, above the text line; the menu
// fills the selected box only while this window has focus (an outline alone
// means the sidebar owns input), matching the shell convention. The list
// scrolls, so under the header it runs to the window's bottom edge with
// that edge's padding inside it, after the last row: rows scrolled past the
// end are cut off at the edge itself. The scrollbar hugs the right padding.
const boxTop = listTop - HUB_LIST_LEAD;
const scrollbarX = width - padding.right - HUB_SCROLLBAR_WIDTH;
list.paint(
image,
{
x: padding.left,
y: boxTop,
width: Math.max(0, scrollbarX - HUB_SCROLLBAR_GAP - padding.left),
height: Math.max(0, height - boxTop),
padBottom: padding.bottom,
},
window.focused,
);
const trackTop = boxTop + HUB_SCROLLBAR_INSET;
list.drawScrollbar(image, scrollbarX, trackTop, Math.max(0, height - padding.bottom - HUB_SCROLLBAR_INSET - trackTop));
return image;
}
function paintAddConnection(window: HubWindow): GrayImage {
const { viewportWidth: width, viewportHeight: height, padding } = window;
const image = new GrayImage(width, height, 0);
const font = chromeFont();
const step = lineStep(font);
// A page of text: its title sits at the window's top and left padding, the
// body indented under it, and the hint line on the bottom padding.
image.drawText(font, padding.left, padding.top, "Add connection", 220);
const bodyX = padding.left + PAGE_BODY_INDENT;
const instructionsY = padding.top + 10 + step;
image.drawText(font, bodyX, instructionsY, "Type ssh://user@host (tmux) or g2mirror://token@host in", 170);
image.drawText(font, bodyX, instructionsY + step, "the phone app (or use voice input from the menu).", 170);
const draftY = instructionsY + 3 * step;
const draft = terminalNewConnectionSetting.get();
image.drawText(font, bodyX, draftY, truncateLabel(draft || "(empty)", 52), 220);
if (window.addError) {
image.drawText(font, bodyX, draftY + step + 6, window.addError, 150);
}
image.drawText(font, bodyX, height - padding.bottom - font.lineHeight, `click save ${GESTURE_DOUBLE_CLICK} cancel`, 110);
return image;
}
/** A page of text: title at the top padding, wrapped body, hint on the bottom padding. */
function paintHubPage(window: HubWindow, page: HubPage): GrayImage {
const { viewportWidth: width, viewportHeight: height, padding } = window;
const image = new GrayImage(width, height, 0);
const font = chromeFont();
const step = lineStep(font);
image.drawText(font, padding.left, padding.top, page.title, 220);
const bodyX = padding.left + PAGE_BODY_INDENT;
const hintY = height - padding.bottom - font.lineHeight;
const lines = wrapText(font, page.body(), Math.max(1, width - padding.right - bodyX), { breakLongWords: true });
let y = padding.top + 10 + step;
for (const line of lines) {
if (y + step > hintY) break;
image.drawText(font, bodyX, y, line, 190);
y += step;
}
image.drawText(font, bodyX, hintY, page.hint, 110);
return image;
}
/** The action row under a host whose SSH connection needs the user. */
function sshIssueAction(issue: SshFailure): string {
if (issue.kind === "hostkey-unknown") return "Verify host key...";
if (issue.kind === "hostkey-mismatch") return "Host key changed!";
if (issue.passwordAllowed) return issue.passwordTried ? "Re-enter password..." : "Enter password...";
return "Show this device's SSH key...";
}
function truncateLabel(text: string, maxLength: number): string {
return text.length <= maxLength ? text : `${text.slice(0, Math.max(0, maxLength - 3))}...`;
}
function hubStatusLine(window: HubWindow): string {
if (window.mode === "connections") {
return "Select a connection to connect, disconnect, or remove.";
}
return sessionsStatusLine();
}
/** The sessions view's status line (also published with the session snapshot). */
function sessionsStatusLine(): string {
if (controls.size === 0) {
return "No connections configured.";
}
const anyRetrying = [...controls.values()].some((control) => control.reconnectTimer);
if (controls.size === 1) {
const control = [...controls.values()][0]!;
const status = control.config.enabled ? (control.state?.status ?? "Not connected.") : "Disconnected.";
return anyRetrying ? `${status} Retrying...` : status;
}
const summary = `${connectedControls().length} of ${controls.size} hosts connected.`;
return anyRetrying ? `${summary} Retrying...` : summary;
}
/**
* Draw one terminal row at a fixed integer cell pitch, so glyph columns stay
* aligned with the emulator's grid arithmetic even when a TTF face has
* fractional advances. Identical to drawText for the 6px bitmap default.
*/
function drawGridRow(
image: GrayImage,
font: UiFont,
cellWidth: number,
rowY: number,
text: string,
value: number,
): void {
let col = 0;
for (const char of text) {
const codePoint = char.codePointAt(0) ?? 32;
if (codePoint !== 32) {
const glyph = font.getGlyph(codePoint);
if (glyph && glyph.bbxWidth > 0) {
image.drawGlyph(font, glyph, col * cellWidth, rowY, value);
}
}
col++;
}
}
function paintView(window: ViewWindow): GrayImage {
const image = new GrayImage(window.viewportWidth, window.viewportHeight, 0);
if (!window.receivedData) {
const font = chromeFont();
image.drawText(font, 24, 110, window.status, 170);
return image;
}
const rows = window.gridRows;
const historyNext = window.historyNext;
const bufferLength = window.emulator.bufferLength();
const bottomTop = historyNext + bufferLength - rows;
const following = window.scrollTop === null;
const top = following ? bottomTop : clamp(window.scrollTop!, window.archiveStart, bottomTop);
// Draw the cursor only if its line is within the visible window.
const cursorScreenRow = historyNext + window.emulator.cursorRow() - top;
if (cursorScreenRow >= 0 && cursorScreenRow < rows) {
image.fillRect(window.emulator.cursorCol() * window.cellWidth, cursorScreenRow * window.cellHeight, window.cellWidth, window.cellHeight, 70);
}
// Stale content stays visible across a disconnect, so flag it: a status
// line over the bottom row(s) whenever the session isn't actually attached.
// It's in the UI font, which can be taller than a terminal cell, so it's
// sized to that font's ink. Text is deferred glyphs (always on top of
// raster), so the covered rows must be suppressed rather than painted over.
const statusFont = chromeFont();
const statusBannerHeight = Math.max(window.cellHeight, textInkHeight(statusFont));
const statusBannerY = window.client.state().phase !== "attached"
? window.viewportHeight - statusBannerHeight
: null;
for (let row = 0; row < rows; row++) {
const rowY = row * window.cellHeight;
if (statusBannerY !== null && rowY + window.cellHeight > statusBannerY) continue;
const absolute = top + row;
let text = "";
if (absolute >= historyNext) {
const bufferIndex = absolute - historyNext;
if (bufferIndex >= 0 && bufferIndex < bufferLength) text = window.emulator.lineAt(bufferIndex);
} else if (absolute >= window.archiveStart) {
text = window.archive[absolute - window.archiveStart] ?? "";
}
if (text.length) drawGridRow(image, window.font, window.cellWidth, rowY, text, 200);
}
if (!following) {
drawScrollIndicator(image, top, window.archiveStart, bottomTop);
}
if (statusBannerY !== null) {
image.fillRect(0, statusBannerY, window.viewportWidth, statusBannerHeight, 0);
image.drawText(statusFont, 0, centeredTextY(statusFont, statusBannerY, statusBannerHeight), window.status, 170);
}
return image;
}
/** Right-edge scrollbar showing the view position within the scrollback. */
function drawScrollIndicator(image: GrayImage, top: number, minTop: number, maxTop: number): void {
const trackX = image.width - 3;
image.fillRect(trackX, 0, 3, image.height, 30);
const fraction = clamp((top - minTop) / Math.max(1, maxTop - minTop), 0, 1);
const thumbHeight = 24;
const thumbY = Math.round((image.height - thumbHeight) * fraction);
image.fillRect(trackX, thumbY, 3, thumbHeight, 150);
}
/** Coalesce bursty repaint triggers (terminal output) into ~30fps renders. */
function scheduleRender(window: TerminalWindow): void {
if (window.renderScheduled) return;
window.renderScheduled = true;
setTimeout(() => {
window.renderScheduled = false;
renderAndSubmit(window, 0);
}, RENDER_COALESCE_MS);
}
function renderAndSubmit(window: TerminalWindow, inputFrameId: number): void {
if (!window.foreground || !screenOn) {
frameTimings.finishFrame(inputFrameId, "discarded: terminal window not visible");
return;
}
const frameId = inputFrameId > 0 ? inputFrameId : frameTimings.startFrame(`render:${window.windowId}`);
try {
const paintStartedAtMs = Date.now();
const planes = frameTimings.span(frameId, "paint", () =>
frameTimings.runWithFrame(frameId, () => paint(window)),
);
const paintMs = Date.now() - paintStartedAtMs;
const fingerprint = planesFingerprint(planes);
if (fingerprint === window.lastSubmittedFingerprint) {
frameTimings.finishFrame(frameId, "discarded: terminal content unchanged");
return;
}
const communicator = getActiveDisplay();
if (!communicator) {
frameTimings.finishFrame(frameId, "discarded: no active display");
return;
}
const { image, draws } = frameTimings.span(frameId, "flatten", () => flattenPlanesWithDraws(planes));
const buffer = frameTimings.span(frameId, "to8bpp", () => image.to8bppBuffer());
communicator.submitSurfaceFrame(
buffer.buffer,
window.surfaceId,
0,
0,
image.width,
image.height,
fingerprint,
paintMs,
frameId,
frameTimings.span(frameId, "prepareFrameDraws", () => prepareFrameDraws(draws)),
);
window.lastSubmittedFingerprint = fingerprint;
} catch (error) {
frameTimings.finishFrame(frameId, "discarded: terminal render failed");
console.error(`terminal worker render failed: ${error}`);
}
}
function sessionLabel(session: G2MirrorSession): string {
if (session.title) {
return session.title;
}
const hint = session.cwdHint.replace(/^_+/, "").replace(/_+/g, "/");
return hint || "session";
}
/** Dispatch an assistant tool-call (unprefixed name) to its handler. */
function handleTerminalTool(name: string, args: any): ToolResult | Promise<ToolResult> {
switch (name) {
case "list_sessions":
return toolListSessions();
case "send_input":
return toolSendInput(args);
case "read_screen":
return toolReadScreen();
case "list_launch_presets":
return toolListLaunchPresets();
case "launch_session":
return toolLaunchSession(args);
default:
return { ok: false, error: `Unknown terminal tool: ${name}` };
}
}
function toolListLaunchPresets(): ToolResult {
const presets = launchPresetNames();
if (!presets.length) {
return { ok: true, content: "No launch presets configured (Terminal window menu > Settings > Launch presets)." };
}
return { ok: true, content: presets.map((preset) => `- ${preset}`).join("\n") };
}
/**
* Pick the host a launch_session call targets: by (partial) server-name match
* when `host` is given, else the sole connected host; ambiguity is an error
* listing the choices.
*/
function resolveLaunchControl(host: string): ControlConnection | { error: string } {
const connected = connectedControls();
if (!connected.length) return { error: "Not connected to any g2mirror server." };
if (host) {
const matches = connected.filter((control) =>
connectionDisplayName(control.config).toLowerCase().includes(host.toLowerCase()),
);
if (matches.length === 1) return matches[0]!;
return {
error: `Host "${host}" ${matches.length ? "is ambiguous among" : "does not match any of"}: ${connected
.map((control) => connectionDisplayName(control.config))
.join(", ")}`,
};
}
if (connected.length === 1) return connected[0]!;
return {
error: `Multiple hosts connected; pass host: ${connected
.map((control) => connectionDisplayName(control.config))
.join(", ")}`,
};
}
async function toolLaunchSession(args: any): Promise<ToolResult> {
const preset = String(args?.preset ?? "").trim();
if (!preset) return { ok: false, error: "launch_session requires a preset name." };
const control = resolveLaunchControl(String(args?.host ?? "").trim());
if ("error" in control) return { ok: false, error: control.error };
const socket = await launchAndOpenView(control, preset);
return { ok: true, content: `Launched "${preset}" (session ${socket}) and opened a window viewing it.` };
}
function toolListSessions(): ToolResult {
const connected = connectedControls();
const multiHost = connected.length > 1;
const lines: string[] = [];
for (const control of connected) {
const sessions = control.state?.sessions ?? [];
if (multiHost) {
lines.push(`${connectionDisplayName(control.config)}:`);
}
for (const session of sessions) {
const glyph = viewGlyphForSocket(control.config.id, session.socket);
const open = glyph ? ` [open in window ${glyph}]` : viewWindowIdForSocket(control.config.id, session.socket) ? " [open]" : "";
lines.push(`- ${sessionLabel(session)}${open}`);
}
if (!sessions.length && multiHost) {
lines.push("- (no live sessions)");
}
}
if (!lines.length) {
return { ok: true, content: "No live terminal sessions (run g2mirror <command> on a host)." };
}
return { ok: true, content: lines.join("\n") };
}
function toolSendInput(args: any): ToolResult {
const text = String(args?.text ?? "");
if (!text) return { ok: false, error: "send_input requires non-empty text." };
const view = resolveActiveView();
if (!view) return { ok: false, error: "No terminal session is open to send input to." };
view.client.submitInput(text);
return { ok: true, content: `Sent to ${view.label}.` };
}
function toolReadScreen(): ToolResult {
const view = resolveActiveView();
if (!view) return { ok: false, error: "No terminal session is open." };
const length = view.emulator.bufferLength();
const start = Math.max(0, length - view.gridRows);
const lines: string[] = [];
for (let index = start; index < length; index++) {
lines.push(view.emulator.lineAt(index));
}
const text = lines.join("\n").replace(/\s+$/, "");
return { ok: true, content: text || "(screen is empty)" };
}
/**
* The terminal view an `open`-tier tool acts on: a foregrounded view if any,
* else the last view to be active, else the sole open view. Null when no view
* is open (the model gets a tool error it can relay).
*/
function resolveActiveView(): ViewWindow | null {
const views: ViewWindow[] = [];
let foreground: ViewWindow | null = null;
for (const window of windows.values()) {
if (window.kind !== "view") continue;
views.push(window);
if (window.foreground) foreground = window;
}
if (foreground) return foreground;
if (activeViewId) {
const window = windows.get(activeViewId);
if (window && window.kind === "view") return window;
}
return views.length === 1 ? views[0]! : null;
}