@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, 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

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.