import type {
EnvironmentId,
TerminalAttachStreamEvent,
TerminalMetadataStreamEvent,
TerminalSessionSnapshot,
TerminalSummary,
ThreadId,
} from "@t3tools/contracts";
import { DEFAULT_MAX_TERMINAL_BUFFER_BYTES } from "@t3tools/contracts";
import {
appendOutput,
EMPTY_TERMINAL_OUTPUT_STATE,
resetOutput,
type TerminalOutputState,
} from "./terminalOutput.ts";
export {
INITIAL_TERMINAL_OUTPUT_CURSOR,
readTerminalOutputUpdate,
terminalOutputText,
type TerminalOutputCursor,
type TerminalOutputState,
type TerminalOutputUpdate,
} from "./terminalOutput.ts";
export { DEFAULT_MAX_TERMINAL_BUFFER_BYTES } from "@t3tools/contracts";
/** The PTY grid every renderer of a shared terminal draws. */
export interface TerminalGrid {
readonly cols: number;
readonly rows: number;
}
export interface TerminalSessionState {
readonly summary: TerminalSummary | null;
readonly output: TerminalOutputState;
/** Null when the server predates shared terminal geometry. */
readonly grid: TerminalGrid | null;
readonly status: TerminalSessionSnapshot["status"] | "closed";
readonly error: string | null;
readonly hasRunningSubprocess: boolean;
readonly updatedAt: string | null;
readonly version: number;
readonly lifecycleVersion: number;
}
export interface TerminalBufferState {
readonly output: TerminalOutputState;
readonly grid: TerminalGrid | null;
readonly status: TerminalSessionSnapshot["status"] | "closed";
readonly error: string | null;
readonly updatedAt: string | null;
readonly version: number;
readonly lifecycleVersion: number;
}
export interface KnownTerminalSessionTarget {
readonly environmentId: EnvironmentId;
readonly threadId: ThreadId;
readonly terminalId: string;
}
export interface KnownTerminalSession {
readonly target: KnownTerminalSessionTarget;
readonly state: TerminalSessionState;
}
export function selectRunningSubprocessTerminalIds(
sessions: ReadonlyArray<KnownTerminalSession>,
): ReadonlyArray<string> {
return sessions
.filter((session) => session.state.hasRunningSubprocess)
.map((session) => session.target.terminalId);
}
export const EMPTY_TERMINAL_BUFFER_STATE = Object.freeze<TerminalBufferState>({
output: EMPTY_TERMINAL_OUTPUT_STATE,
grid: null,
status: "closed",
error: null,
updatedAt: null,
version: 0,
lifecycleVersion: 0,
});
export const EMPTY_TERMINAL_SESSION_STATE = Object.freeze<TerminalSessionState>({
summary: null,
output: EMPTY_TERMINAL_OUTPUT_STATE,
grid: null,
status: "closed",
error: null,
hasRunningSubprocess: false,
updatedAt: null,
version: 0,
lifecycleVersion: 0,
});
let terminalAttachGeneration = 0;
/** A reinstalled attach stream must not reuse an old renderer's output cursor. */
export function nextTerminalAttachSeedState(): TerminalBufferState {
return {
...EMPTY_TERMINAL_BUFFER_STATE,
output: {
...EMPTY_TERMINAL_OUTPUT_STATE,
generation: ++terminalAttachGeneration,
},
};
}
function terminalBufferStateFromSnapshot(
snapshot: TerminalSessionSnapshot,
maxBufferBytes: number,
current: TerminalBufferState = EMPTY_TERMINAL_BUFFER_STATE,
): TerminalBufferState {
return {
output: resetOutput(current.output, snapshot.history, maxBufferBytes),
grid: nextGrid(current.grid, snapshot),
status: snapshot.status,
error: null,
updatedAt: snapshot.updatedAt,
version: current.version + 1,
lifecycleVersion: current.lifecycleVersion,
};
}
function nextGrid(
current: TerminalGrid | null,
source: { readonly cols?: number | undefined; readonly rows?: number | undefined },
): TerminalGrid | null {
if (source.cols === undefined || source.rows === undefined) return current;
return current?.cols === source.cols && current.rows === source.rows
? current
: { cols: source.cols, rows: source.rows };
}
function latestTimestamp(left: string | null, right: string | null): string | null {
if (left === null) return right;
if (right === null) return left;
return Date.parse(left) >= Date.parse(right) ? left : right;
}
export function combineTerminalSessionState(
summary: TerminalSummary | null,
buffer: TerminalBufferState,
): TerminalSessionState {
return {
summary,
output: buffer.output,
grid: buffer.grid,
status: buffer.version > 0 ? buffer.status : (summary?.status ?? buffer.status),
error: buffer.error,
hasRunningSubprocess: summary?.hasRunningSubprocess ?? false,
updatedAt: latestTimestamp(summary?.updatedAt ?? null, buffer.updatedAt),
version: buffer.version,
lifecycleVersion: buffer.lifecycleVersion,
};
}
export function applyTerminalAttachStreamEvent(
current: TerminalBufferState,
event: TerminalAttachStreamEvent,
maxBufferBytes = DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
): TerminalBufferState {
switch (event.type) {
case "snapshot": {
if (current.version === 0) {
return terminalBufferStateFromSnapshot(event.snapshot, maxBufferBytes, current);
}
// A later snapshot is a new server attachment, as after a socket reconnect. It starts a
// new generation because viewers replay their measured grid once per generation.
const reattached = {
...current,
output: { ...current.output, generation: ++terminalAttachGeneration },
};
return {
...terminalBufferStateFromSnapshot(event.snapshot, maxBufferBytes, reattached),
lifecycleVersion: current.lifecycleVersion + 1,
};
}
case "restarted":
return {
...terminalBufferStateFromSnapshot(event.snapshot, maxBufferBytes, current),
lifecycleVersion: current.lifecycleVersion + 1,
};
case "output":
return {
...current,
output: appendOutput(current.output, event.data, maxBufferBytes),
status: current.status === "closed" ? "running" : current.status,
error: null,
version: current.version + 1,
};
case "cleared":
return {
...current,
output: resetOutput(current.output, "", maxBufferBytes),
error: null,
version: current.version + 1,
};
case "exited":
return {
...current,
status: "exited",
error: null,
version: current.version + 1,
};
case "closed":
return {
...current,
status: "closed",
error: null,
version: current.version + 1,
};
case "error":
return {
...current,
status: "error",
error: event.message,
version: current.version + 1,
};
case "activity": {
const grid = nextGrid(current.grid, event);
return grid === current.grid ? current : { ...current, grid };
}
}
}
export function applyTerminalMetadataStreamEvent(
current: ReadonlyArray<TerminalSummary>,
event: TerminalMetadataStreamEvent,
): ReadonlyArray<TerminalSummary> {
if (event.type === "snapshot") {
return event.terminals;
}
if (event.type === "remove") {
return current.filter(
(terminal) =>
terminal.threadId !== event.threadId || terminal.terminalId !== event.terminalId,
);
}
const next = current.filter(
(terminal) =>
terminal.threadId !== event.terminal.threadId ||
terminal.terminalId !== event.terminal.terminalId,
);
return [...next, event.terminal];
}