@rivet-dev/agentos-node-pty 0.2.8-rc.3

package/README.md

@@ -0,0 +1,5 @@
+# AgentOS node-pty
+
+`@rivet-dev/agentos-node-pty` implements the `@lydell/node-pty` JavaScript API
+on AgentOS kernel PTYs. It is intended for packages running inside an AgentOS
+VM and does not load a native Node addon.

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+export interface IDisposable {
+    dispose(): void;
+}
+export interface IPtyForkOptions {
+    name?: string;
+    cols?: number;
+    rows?: number;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    encoding?: BufferEncoding | null;
+    handleFlowControl?: boolean;
+    flowControlPause?: string;
+    flowControlResume?: string;
+    uid?: number;
+    gid?: number;
+}
+export type IWindowsPtyForkOptions = IPtyForkOptions;
+export interface IPty {
+    readonly pid: number;
+    readonly cols: number;
+    readonly rows: number;
+    readonly process: string;
+    handleFlowControl: boolean;
+    readonly onData: (listener: (data: string) => unknown) => IDisposable;
+    readonly onExit: (listener: (event: {
+        exitCode: number;
+        signal?: number;
+    }) => unknown) => IDisposable;
+    resize(columns: number, rows: number): void;
+    clear(): void;
+    write(data: string | Buffer): void;
+    kill(signal?: string): void;
+    pause(): void;
+    resume(): void;
+}
+export declare function spawn(file: string, args: string[] | string, options?: IPtyForkOptions | IWindowsPtyForkOptions): IPty;

package/dist/index.js

@@ -0,0 +1,159 @@
+import { spawn as spawnChild } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { StringDecoder } from "node:string_decoder";
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+const DEFAULT_MAX_LISTENERS = 100;
+function positiveInteger(value, fallback, label) {
+    const result = value ?? fallback;
+    if (!Number.isInteger(result) || result <= 0) {
+        throw Object.assign(new RangeError(`${label} must be a positive integer`), {
+            code: "EINVAL",
+        });
+    }
+    return result;
+}
+function maxListeners() {
+    const configured = Number(process.env.AGENTOS_NODE_PTY_MAX_LISTENERS);
+    return Number.isInteger(configured) && configured > 0
+        ? configured
+        : DEFAULT_MAX_LISTENERS;
+}
+function addBoundedListener(listeners, listener) {
+    if (listeners.size >= maxListeners()) {
+        throw Object.assign(new Error(`node-pty listener limit exceeded (${maxListeners()}); raise AGENTOS_NODE_PTY_MAX_LISTENERS to allow more`), { code: "ERR_AGENTOS_NODE_PTY_LISTENER_LIMIT" });
+    }
+    listeners.add(listener);
+    return { dispose: () => listeners.delete(listener) };
+}
+function signalNumber(signal) {
+    return signal ? osConstants.signals[signal] : undefined;
+}
+export function spawn(file, args, options = {}) {
+    if (typeof args === "string") {
+        throw Object.assign(new Error("pre-escaped Windows command lines are not supported by AgentOS node-pty"), { code: "ENOSYS" });
+    }
+    if (options.uid !== undefined || options.gid !== undefined) {
+        throw Object.assign(new Error("node-pty uid/gid overrides are not supported by AgentOS"), {
+            code: "ENOSYS",
+        });
+    }
+    let cols = positiveInteger(options.cols, DEFAULT_COLS, "cols");
+    let rows = positiveInteger(options.rows, DEFAULT_ROWS, "rows");
+    const encoding = options.encoding === undefined ? "utf8" : options.encoding;
+    if (encoding === null) {
+        throw Object.assign(new Error("binary node-pty output is not supported"), {
+            code: "ENOSYS",
+        });
+    }
+    const decoder = new StringDecoder(encoding);
+    const dataListeners = new Set();
+    const exitListeners = new Set();
+    let exited = false;
+    let handleFlowControl = options.handleFlowControl ?? false;
+    const flowControlPause = options.flowControlPause ?? "\x13";
+    const flowControlResume = options.flowControlResume ?? "\x11";
+    const child = spawnChild(file, args, {
+        cwd: options.cwd,
+        env: {
+            ...process.env,
+            ...options.env,
+            TERM: options.name ?? "xterm-256color",
+            COLUMNS: String(cols),
+            LINES: String(rows),
+        },
+        stdio: ["pipe", "pipe", "pipe"],
+        agentosPty: { cols, rows },
+    });
+    const emitData = (chunk) => {
+        const text = typeof chunk === "string" ? chunk : decoder.write(chunk);
+        if (!text)
+            return;
+        for (const listener of [...dataListeners])
+            listener(text);
+    };
+    const emitExit = (exitCode, signal) => {
+        if (exited)
+            return;
+        exited = true;
+        const trailing = decoder.end();
+        if (trailing) {
+            for (const listener of [...dataListeners])
+                listener(trailing);
+        }
+        for (const listener of [...exitListeners])
+            listener({ exitCode, signal });
+        dataListeners.clear();
+        exitListeners.clear();
+    };
+    child.stdout?.on("data", emitData);
+    child.stderr?.on("data", emitData);
+    child.once("error", (error) => {
+        console.error("AgentOS node-pty child process failed", error);
+        emitExit(1);
+    });
+    child.once("exit", (code, signal) => emitExit(code ?? 0, signalNumber(signal)));
+    return {
+        get pid() {
+            return child.pid ?? -1;
+        },
+        get cols() {
+            return cols;
+        },
+        get rows() {
+            return rows;
+        },
+        get process() {
+            return file;
+        },
+        get handleFlowControl() {
+            return handleFlowControl;
+        },
+        set handleFlowControl(value) {
+            handleFlowControl = value;
+        },
+        onData(listener) {
+            return addBoundedListener(dataListeners, listener);
+        },
+        onExit(listener) {
+            return addBoundedListener(exitListeners, listener);
+        },
+        resize(columns, nextRows) {
+            const nextCols = positiveInteger(columns, DEFAULT_COLS, "columns");
+            const normalizedRows = positiveInteger(nextRows, DEFAULT_ROWS, "rows");
+            if (typeof child.resizePty !== "function") {
+                throw Object.assign(new Error("AgentOS child process PTY resize bridge is unavailable"), {
+                    code: "ENOTTY",
+                });
+            }
+            child.resizePty(nextCols, normalizedRows);
+            cols = nextCols;
+            rows = normalizedRows;
+        },
+        clear() { },
+        write(data) {
+            if (handleFlowControl && data === flowControlPause) {
+                child.stdout?.pause();
+                child.stderr?.pause();
+                return;
+            }
+            if (handleFlowControl && data === flowControlResume) {
+                child.stdout?.resume();
+                child.stderr?.resume();
+                return;
+            }
+            child.stdin?.write(data);
+        },
+        kill(signal = "SIGHUP") {
+            child.kill(signal);
+        },
+        pause() {
+            child.stdout?.pause();
+            child.stderr?.pause();
+        },
+        resume() {
+            child.stdout?.resume();
+            child.stderr?.resume();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "@rivet-dev/agentos-node-pty",
+	"version": "0.2.8-rc.3",
+	"description": "AgentOS-backed node-pty compatibility layer",
+	"type": "module",
+	"license": "Apache-2.0",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc",
+		"check-types": "tsc --noEmit",
+		"test": "pnpm build && node --test tests/*.test.mjs"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"devDependencies": {
+		"@types/node": "^22.10.2",
+		"typescript": "^5.7.2"
+	}
+}