@alfe.ai/terminal 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,36 @@
+# `@alfe.ai/terminal`
+
+PTY terminal surface for Alfe's interactive remote-control relay. Each viewer
+session owns a separate shell process in the agent workspace; terminal frames
+travel over the agent's existing outbound WebSocket, with no inbound port or
+SSH daemon.
+
+Part of [Alfe](https://alfe.ai), the operating system for AI agents.
+
+## Runtime contract
+
+- One numeric remote session owns one exact PTY instance. Late data/exit events
+  from an older process cannot affect a reopened session with the same ID.
+- Initial and resize dimensions are integers from 1 to 1,000. Terminal input is
+  valid UTF-8 capped at 64 KiB per frame.
+- PTY output is split into UTF-8-safe frames of at most 64 KiB so terminal
+  floods cannot create relay-sized single messages.
+- If the outbound relay already has 4 MiB queued, output delivery fails closed
+  and the owning PTY is terminated instead of growing an unbounded buffer.
+- Session count defaults to 8 and may be configured from 1 to 64.
+- Shutdown retries a PTY once when its native `kill()` call fails instead of
+  immediately forgetting the still-running process.
+
+## Usage
+
+```ts
+import { TerminalSurface } from "@alfe.ai/terminal";
+
+const surface = new TerminalSurface(
+  { cwd: "/path/to/agent/workspace" },
+  (frame) => relay.sendFrame(frame),
+);
+```
+
+The package uses `@lydell/node-pty`, which publishes matching native binaries
+for supported macOS, Linux, and Windows architectures.

package/dist/index.cjs

@@ -12,6 +12,16 @@ let _alfe_ai_remote = require("@alfe.ai/remote");
 const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
 const DEFAULT_MAX_SESSIONS = 8;
+const MAX_SESSIONS = 64;
+const MAX_DIMENSION = 1e3;
+const MAX_TERMINAL_INPUT_BYTES = 64 * 1024;
+const MAX_TERMINAL_OUTPUT_FRAME_BYTES = 64 * 1024;
+const MAX_SHELL_CHARS = 4096;
+const MAX_CWD_CHARS = 8192;
+const MAX_ENV_VALUE_CHARS = 64 * 1024;
+const MAX_ENV_OVERRIDES = 256;
+const MAX_ENV_OVERRIDE_BYTES = 512 * 1024;
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
 const noopLogger = {
 	info: () => {},
 	warn: () => {},
@@ -27,29 +37,49 @@ var TerminalSurface = class {
 	maxSessions;
 	log;
 	constructor(options, sendFrame) {
-		this.options = options;
 		this.sendFrame = sendFrame;
 		this.log = options.logger ?? noopLogger;
-		this.shell = options.shell ?? process.env.SHELL ?? "/bin/bash";
-		this.cwd = options.cwd ?? process.cwd();
-		this.maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;
-		const baseEnv = {};
+		this.shell = requirePlainString(options.shell ?? process.env.SHELL ?? "/bin/bash", "terminal shell", MAX_SHELL_CHARS);
+		this.cwd = requirePlainString(options.cwd ?? process.cwd(), "terminal working directory", MAX_CWD_CHARS);
+		this.maxSessions = optionalBoundedInteger(options.maxSessions, DEFAULT_MAX_SESSIONS, 1, MAX_SESSIONS, "terminal maxSessions");
+		const baseEnv = Object.create(null);
 		for (const [k, v] of Object.entries(process.env)) if (v !== void 0) baseEnv[k] = v;
-		this.env = {
-			...baseEnv,
-			...options.env ?? {},
-			TERM: "xterm-256color"
-		};
+		const environmentOverrides = Object.entries(options.env ?? {});
+		if (environmentOverrides.length > MAX_ENV_OVERRIDES) throw new TypeError("terminal environment contains too many variables");
+		let environmentBytes = 0;
+		for (const [key, value] of environmentOverrides) {
+			if (key.length > 256 || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key)) throw new TypeError("terminal environment contains an invalid variable name");
+			const admittedValue = requirePlainString(value, "terminal environment value", MAX_ENV_VALUE_CHARS, true);
+			environmentBytes += Buffer.byteLength(key, "utf8") + Buffer.byteLength(admittedValue, "utf8");
+			if (environmentBytes > MAX_ENV_OVERRIDE_BYTES) throw new TypeError("terminal environment exceeds the byte limit");
+			baseEnv[key] = admittedValue;
+		}
+		baseEnv.TERM = "xterm-256color";
+		this.env = baseEnv;
 	}
 	openSession(sessionId, open) {
+		if (!isSessionId(sessionId)) {
+			this.log.warn("Terminal session ID is invalid");
+			return;
+		}
 		if (this.ptys.has(sessionId)) return;
+		if (open.surface !== "terminal") {
+			this.log.warn("Terminal session surface is invalid");
+			this.sendClose(sessionId);
+			return;
+		}
 		if (this.ptys.size >= this.maxSessions) {
-			this.log.warn(`Terminal session limit (${String(this.maxSessions)}) reached — refusing`);
-			this.sendFrame((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.RemoteFrameType.SESSION_CLOSE, sessionId));
+			this.log.warn("Terminal session limit reached");
+			this.sendClose(sessionId);
+			return;
+		}
+		const cols = optionalDimension(open.cols, DEFAULT_COLS);
+		const rows = optionalDimension(open.rows, DEFAULT_ROWS);
+		if (cols === void 0 || rows === void 0) {
+			this.log.warn("Terminal session dimensions are invalid");
+			this.sendClose(sessionId);
 			return;
 		}
-		const cols = open.cols ?? DEFAULT_COLS;
-		const rows = open.rows ?? DEFAULT_ROWS;
 		let ptyProcess;
 		try {
 			ptyProcess = (0, _lydell_node_pty.spawn)(this.shell, [], {
@@ -59,33 +89,55 @@ var TerminalSurface = class {
 				cwd: this.cwd,
 				env: this.env
 			});
-		} catch (err) {
-			this.log.error(`Failed to spawn PTY: ${err.message}`);
-			this.sendFrame((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.RemoteFrameType.SESSION_CLOSE, sessionId));
+		} catch {
+			this.log.error("Could not spawn terminal session");
+			this.sendClose(sessionId);
 			return;
 		}
 		this.ptys.set(sessionId, ptyProcess);
-		this.log.info(`Terminal session ${String(sessionId)} started (${this.shell})`);
+		this.log.info("Terminal session started");
 		ptyProcess.onData((data) => {
-			this.sendFrame((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.RemoteFrameType.TERMINAL_DATA, sessionId, Buffer.from(data, "utf-8")));
+			if (this.ptys.get(sessionId) !== ptyProcess) return;
+			for (const chunk of chunkUtf8(data, MAX_TERMINAL_OUTPUT_FRAME_BYTES)) if (!this.send((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.RemoteFrameType.TERMINAL_DATA, sessionId, chunk))) {
+				this.closeSession(sessionId);
+				return;
+			}
 		});
 		ptyProcess.onExit(() => {
-			this.log.info(`Terminal session ${String(sessionId)} exited`);
+			if (this.ptys.get(sessionId) !== ptyProcess) return;
+			this.log.info("Terminal session exited");
 			this.ptys.delete(sessionId);
-			this.sendFrame((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.RemoteFrameType.SESSION_CLOSE, sessionId));
+			this.sendClose(sessionId);
 		});
 	}
 	handleFrame(frame) {
 		const ptyProcess = this.ptys.get(frame.sessionId);
 		if (!ptyProcess) return;
 		switch (frame.type) {
-			case _alfe_ai_remote.RemoteFrameType.TERMINAL_INPUT:
-				ptyProcess.write(frame.payload.toString("utf-8"));
+			case _alfe_ai_remote.RemoteFrameType.TERMINAL_INPUT: {
+				if (frame.payload.length > MAX_TERMINAL_INPUT_BYTES) {
+					this.log.warn("Terminal input exceeded the byte limit");
+					return;
+				}
+				let input;
+				try {
+					input = utf8Decoder.decode(frame.payload);
+				} catch {
+					this.log.warn("Terminal input was invalid");
+					return;
+				}
+				try {
+					ptyProcess.write(input);
+				} catch {
+					this.log.warn("Could not write terminal input");
+					this.closeSession(frame.sessionId);
+				}
 				break;
+			}
 			case _alfe_ai_remote.RemoteFrameType.TERMINAL_RESIZE: {
-				const r = (0, _alfe_ai_remote.decodeJson)(frame.payload);
-				if (r && r.cols > 0 && r.rows > 0) try {
-					ptyProcess.resize(r.cols, r.rows);
+				const resize = (0, _alfe_ai_remote.decodeTerminalResizePayload)(frame.payload);
+				if (resize) try {
+					ptyProcess.resize(resize.cols, resize.rows);
 				} catch {}
 				break;
 			}
@@ -95,20 +147,66 @@ var TerminalSurface = class {
 	closeSession(sessionId) {
 		const ptyProcess = this.ptys.get(sessionId);
 		if (!ptyProcess) return;
-		this.ptys.delete(sessionId);
 		try {
 			ptyProcess.kill();
-		} catch {}
+			if (this.ptys.get(sessionId) === ptyProcess) this.ptys.delete(sessionId);
+		} catch {
+			this.log.warn("Could not close terminal session");
+		}
 	}
 	/** Kill every live PTY (plugin shutdown). */
 	shutdown() {
-		for (const [sessionId, ptyProcess] of this.ptys) {
-			try {
-				ptyProcess.kill();
-			} catch {}
-			this.ptys.delete(sessionId);
+		for (const sessionId of [...this.ptys.keys()]) {
+			this.closeSession(sessionId);
+			if (this.ptys.has(sessionId)) this.closeSession(sessionId);
+		}
+	}
+	sendClose(sessionId) {
+		this.send((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.RemoteFrameType.SESSION_CLOSE, sessionId));
+	}
+	send(frame) {
+		try {
+			this.sendFrame(frame);
+			return true;
+		} catch {
+			this.log.warn("Could not send terminal frame");
+			return false;
 		}
 	}
 };
+function isSessionId(value) {
+	return Number.isInteger(value) && value >= 0 && value <= 4294967295;
+}
+function optionalDimension(value, fallback) {
+	if (value === void 0) return fallback;
+	return Number.isInteger(value) && value >= 1 && value <= MAX_DIMENSION ? value : void 0;
+}
+function optionalBoundedInteger(value, fallback, minimum, maximum, label) {
+	if (value === void 0) return fallback;
+	if (!Number.isInteger(value) || value < minimum || value > maximum) throw new TypeError(`${label} is invalid`);
+	return value;
+}
+function requirePlainString(value, label, maxChars, allowEmpty = false) {
+	if (typeof value !== "string" || !allowEmpty && value.length === 0 || value.length > maxChars || value.includes("\0")) throw new TypeError(`${label} is invalid`);
+	return value;
+}
+function chunkUtf8(value, maxBytes) {
+	if (value.length === 0) return [];
+	const chunks = [];
+	let characters = [];
+	let bytes = 0;
+	for (const character of value) {
+		const size = Buffer.byteLength(character, "utf8");
+		if (bytes + size > maxBytes && characters.length > 0) {
+			chunks.push(Buffer.from(characters.join(""), "utf8"));
+			characters = [];
+			bytes = 0;
+		}
+		characters.push(character);
+		bytes += size;
+	}
+	if (characters.length > 0) chunks.push(Buffer.from(characters.join(""), "utf8"));
+	return chunks;
+}
 //#endregion
 exports.TerminalSurface = TerminalSurface;

package/dist/index.d.cts

@@ -83,7 +83,6 @@ interface TerminalSurfaceOptions {
 //#endregion
 //#region src/terminal-surface.d.ts
 declare class TerminalSurface implements SurfaceHandler {
-  private readonly options;
   private readonly sendFrame;
   readonly surface: "terminal";
   private readonly ptys;
@@ -98,6 +97,8 @@ declare class TerminalSurface implements SurfaceHandler {
   closeSession(sessionId: number): void;
   /** Kill every live PTY (plugin shutdown). */
   shutdown(): void;
+  private sendClose;
+  private send;
 }
 //#endregion
 export { type Logger, TerminalSurface, type TerminalSurfaceOptions };

package/dist/index.d.ts

@@ -83,7 +83,6 @@ interface TerminalSurfaceOptions {
 //#endregion
 //#region src/terminal-surface.d.ts
 declare class TerminalSurface implements SurfaceHandler {
-  private readonly options;
   private readonly sendFrame;
   readonly surface: "terminal";
   private readonly ptys;
@@ -98,6 +97,8 @@ declare class TerminalSurface implements SurfaceHandler {
   closeSession(sessionId: number): void;
   /** Kill every live PTY (plugin shutdown). */
   shutdown(): void;
+  private sendClose;
+  private send;
 }
 //#endregion
 export { type Logger, TerminalSurface, type TerminalSurfaceOptions };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { spawn } from "@lydell/node-pty";
-import { RemoteFrameType, decodeJson, encodeFrame } from "@alfe.ai/remote";
+import { RemoteFrameType, decodeTerminalResizePayload, encodeFrame } from "@alfe.ai/remote";
 //#region src/terminal-surface.ts
 /**
 * TerminalSurface — the `SurfaceHandler` for the web terminal. Each viewer
@@ -11,6 +11,16 @@ import { RemoteFrameType, decodeJson, encodeFrame } from "@alfe.ai/remote";
 const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
 const DEFAULT_MAX_SESSIONS = 8;
+const MAX_SESSIONS = 64;
+const MAX_DIMENSION = 1e3;
+const MAX_TERMINAL_INPUT_BYTES = 64 * 1024;
+const MAX_TERMINAL_OUTPUT_FRAME_BYTES = 64 * 1024;
+const MAX_SHELL_CHARS = 4096;
+const MAX_CWD_CHARS = 8192;
+const MAX_ENV_VALUE_CHARS = 64 * 1024;
+const MAX_ENV_OVERRIDES = 256;
+const MAX_ENV_OVERRIDE_BYTES = 512 * 1024;
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
 const noopLogger = {
 	info: () => {},
 	warn: () => {},
@@ -26,29 +36,49 @@ var TerminalSurface = class {
 	maxSessions;
 	log;
 	constructor(options, sendFrame) {
-		this.options = options;
 		this.sendFrame = sendFrame;
 		this.log = options.logger ?? noopLogger;
-		this.shell = options.shell ?? process.env.SHELL ?? "/bin/bash";
-		this.cwd = options.cwd ?? process.cwd();
-		this.maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;
-		const baseEnv = {};
+		this.shell = requirePlainString(options.shell ?? process.env.SHELL ?? "/bin/bash", "terminal shell", MAX_SHELL_CHARS);
+		this.cwd = requirePlainString(options.cwd ?? process.cwd(), "terminal working directory", MAX_CWD_CHARS);
+		this.maxSessions = optionalBoundedInteger(options.maxSessions, DEFAULT_MAX_SESSIONS, 1, MAX_SESSIONS, "terminal maxSessions");
+		const baseEnv = Object.create(null);
 		for (const [k, v] of Object.entries(process.env)) if (v !== void 0) baseEnv[k] = v;
-		this.env = {
-			...baseEnv,
-			...options.env ?? {},
-			TERM: "xterm-256color"
-		};
+		const environmentOverrides = Object.entries(options.env ?? {});
+		if (environmentOverrides.length > MAX_ENV_OVERRIDES) throw new TypeError("terminal environment contains too many variables");
+		let environmentBytes = 0;
+		for (const [key, value] of environmentOverrides) {
+			if (key.length > 256 || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key)) throw new TypeError("terminal environment contains an invalid variable name");
+			const admittedValue = requirePlainString(value, "terminal environment value", MAX_ENV_VALUE_CHARS, true);
+			environmentBytes += Buffer.byteLength(key, "utf8") + Buffer.byteLength(admittedValue, "utf8");
+			if (environmentBytes > MAX_ENV_OVERRIDE_BYTES) throw new TypeError("terminal environment exceeds the byte limit");
+			baseEnv[key] = admittedValue;
+		}
+		baseEnv.TERM = "xterm-256color";
+		this.env = baseEnv;
 	}
 	openSession(sessionId, open) {
+		if (!isSessionId(sessionId)) {
+			this.log.warn("Terminal session ID is invalid");
+			return;
+		}
 		if (this.ptys.has(sessionId)) return;
+		if (open.surface !== "terminal") {
+			this.log.warn("Terminal session surface is invalid");
+			this.sendClose(sessionId);
+			return;
+		}
 		if (this.ptys.size >= this.maxSessions) {
-			this.log.warn(`Terminal session limit (${String(this.maxSessions)}) reached — refusing`);
-			this.sendFrame(encodeFrame(RemoteFrameType.SESSION_CLOSE, sessionId));
+			this.log.warn("Terminal session limit reached");
+			this.sendClose(sessionId);
+			return;
+		}
+		const cols = optionalDimension(open.cols, DEFAULT_COLS);
+		const rows = optionalDimension(open.rows, DEFAULT_ROWS);
+		if (cols === void 0 || rows === void 0) {
+			this.log.warn("Terminal session dimensions are invalid");
+			this.sendClose(sessionId);
 			return;
 		}
-		const cols = open.cols ?? DEFAULT_COLS;
-		const rows = open.rows ?? DEFAULT_ROWS;
 		let ptyProcess;
 		try {
 			ptyProcess = spawn(this.shell, [], {
@@ -58,33 +88,55 @@ var TerminalSurface = class {
 				cwd: this.cwd,
 				env: this.env
 			});
-		} catch (err) {
-			this.log.error(`Failed to spawn PTY: ${err.message}`);
-			this.sendFrame(encodeFrame(RemoteFrameType.SESSION_CLOSE, sessionId));
+		} catch {
+			this.log.error("Could not spawn terminal session");
+			this.sendClose(sessionId);
 			return;
 		}
 		this.ptys.set(sessionId, ptyProcess);
-		this.log.info(`Terminal session ${String(sessionId)} started (${this.shell})`);
+		this.log.info("Terminal session started");
 		ptyProcess.onData((data) => {
-			this.sendFrame(encodeFrame(RemoteFrameType.TERMINAL_DATA, sessionId, Buffer.from(data, "utf-8")));
+			if (this.ptys.get(sessionId) !== ptyProcess) return;
+			for (const chunk of chunkUtf8(data, MAX_TERMINAL_OUTPUT_FRAME_BYTES)) if (!this.send(encodeFrame(RemoteFrameType.TERMINAL_DATA, sessionId, chunk))) {
+				this.closeSession(sessionId);
+				return;
+			}
 		});
 		ptyProcess.onExit(() => {
-			this.log.info(`Terminal session ${String(sessionId)} exited`);
+			if (this.ptys.get(sessionId) !== ptyProcess) return;
+			this.log.info("Terminal session exited");
 			this.ptys.delete(sessionId);
-			this.sendFrame(encodeFrame(RemoteFrameType.SESSION_CLOSE, sessionId));
+			this.sendClose(sessionId);
 		});
 	}
 	handleFrame(frame) {
 		const ptyProcess = this.ptys.get(frame.sessionId);
 		if (!ptyProcess) return;
 		switch (frame.type) {
-			case RemoteFrameType.TERMINAL_INPUT:
-				ptyProcess.write(frame.payload.toString("utf-8"));
+			case RemoteFrameType.TERMINAL_INPUT: {
+				if (frame.payload.length > MAX_TERMINAL_INPUT_BYTES) {
+					this.log.warn("Terminal input exceeded the byte limit");
+					return;
+				}
+				let input;
+				try {
+					input = utf8Decoder.decode(frame.payload);
+				} catch {
+					this.log.warn("Terminal input was invalid");
+					return;
+				}
+				try {
+					ptyProcess.write(input);
+				} catch {
+					this.log.warn("Could not write terminal input");
+					this.closeSession(frame.sessionId);
+				}
 				break;
+			}
 			case RemoteFrameType.TERMINAL_RESIZE: {
-				const r = decodeJson(frame.payload);
-				if (r && r.cols > 0 && r.rows > 0) try {
-					ptyProcess.resize(r.cols, r.rows);
+				const resize = decodeTerminalResizePayload(frame.payload);
+				if (resize) try {
+					ptyProcess.resize(resize.cols, resize.rows);
 				} catch {}
 				break;
 			}
@@ -94,20 +146,66 @@ var TerminalSurface = class {
 	closeSession(sessionId) {
 		const ptyProcess = this.ptys.get(sessionId);
 		if (!ptyProcess) return;
-		this.ptys.delete(sessionId);
 		try {
 			ptyProcess.kill();
-		} catch {}
+			if (this.ptys.get(sessionId) === ptyProcess) this.ptys.delete(sessionId);
+		} catch {
+			this.log.warn("Could not close terminal session");
+		}
 	}
 	/** Kill every live PTY (plugin shutdown). */
 	shutdown() {
-		for (const [sessionId, ptyProcess] of this.ptys) {
-			try {
-				ptyProcess.kill();
-			} catch {}
-			this.ptys.delete(sessionId);
+		for (const sessionId of [...this.ptys.keys()]) {
+			this.closeSession(sessionId);
+			if (this.ptys.has(sessionId)) this.closeSession(sessionId);
+		}
+	}
+	sendClose(sessionId) {
+		this.send(encodeFrame(RemoteFrameType.SESSION_CLOSE, sessionId));
+	}
+	send(frame) {
+		try {
+			this.sendFrame(frame);
+			return true;
+		} catch {
+			this.log.warn("Could not send terminal frame");
+			return false;
 		}
 	}
 };
+function isSessionId(value) {
+	return Number.isInteger(value) && value >= 0 && value <= 4294967295;
+}
+function optionalDimension(value, fallback) {
+	if (value === void 0) return fallback;
+	return Number.isInteger(value) && value >= 1 && value <= MAX_DIMENSION ? value : void 0;
+}
+function optionalBoundedInteger(value, fallback, minimum, maximum, label) {
+	if (value === void 0) return fallback;
+	if (!Number.isInteger(value) || value < minimum || value > maximum) throw new TypeError(`${label} is invalid`);
+	return value;
+}
+function requirePlainString(value, label, maxChars, allowEmpty = false) {
+	if (typeof value !== "string" || !allowEmpty && value.length === 0 || value.length > maxChars || value.includes("\0")) throw new TypeError(`${label} is invalid`);
+	return value;
+}
+function chunkUtf8(value, maxBytes) {
+	if (value.length === 0) return [];
+	const chunks = [];
+	let characters = [];
+	let bytes = 0;
+	for (const character of value) {
+		const size = Buffer.byteLength(character, "utf8");
+		if (bytes + size > maxBytes && characters.length > 0) {
+			chunks.push(Buffer.from(characters.join(""), "utf8"));
+			characters = [];
+			bytes = 0;
+		}
+		characters.push(character);
+		bytes += size;
+	}
+	if (characters.length > 0) chunks.push(Buffer.from(characters.join(""), "utf8"));
+	return chunks;
+}
 //#endregion
 export { TerminalSurface };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/terminal",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "PTY terminal surface for the Alfe interactive remote-control relay — a web shell over the agent's outbound WS (no inbound port, no SSH daemon)",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,11 +13,12 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
     "@lydell/node-pty": "1.2.0-beta.3",
-    "@alfe.ai/remote": "^0.1.0"
+    "@alfe.ai/remote": "^0.2.0"
   },
   "license": "UNLICENSED",
   "homepage": "https://alfe.ai",