@rome-os/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rome OS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# Rome Node
+
+Rome Node exposes a computer to Rome instances in the same Cloud account while
+`rome-node connect` runs. Programs run as the OS user who starts the command.
+The computer needs Node.js 24 or later. It does not need a Rome instance.
+
+Build an installation archive from this repository:
+
+```sh
+pnpm --filter @rome-os/node build
+pnpm --filter @rome-os/node pack --pack-destination /tmp
+npm install -g /tmp/rome-os-node-0.1.0.tgz
+```
+
+On the target computer:
+
+```sh
+rome-node connect --name "My computer"
+```
+
+Open the printed authorization URL in a browser on that computer and approve it.
+The browser callback uses a temporary loopback listener. A remote browser needs
+a tunnel to that listener. Ctrl+C disconnects and preserves the credential.
+
+On the caller, configure a previously issued communication token through stdin:
+
+```sh
+rome-node auth --cloud https://romeos.cc < /path/to/private-token-file
+```
+
+This saves the token privately. The caller does not need Rome Core.
+Run commands from an agent, script, or terminal:
+
+```sh
+rome-node help
+rome-node help device run
+rome-node device
+rome-node device describe <device-id>
+rome-node device run <device-id> exec --args '{"command":"git","args":["status"],"cwd":"/workspace"}'
+```
+
+Use `rome-node <command> --help` or `-h` for command-specific help.
+Help includes action arguments, examples, output fields, and failure handling.
+It works offline without credentials and does not start the daemon.
+
+The first device command starts a background CLI daemon. Commands share its
+Gateway connection. `rome-node daemon status` reports its PID, and
+`rome-node daemon stop` closes it. A later command starts it again. Stop the
+daemon before changing credentials. `rome-node daemon serve` runs in the
+foreground for diagnosis. Set `ROME_NODE_CONFIG_DIR` to isolate configurations.
+
+Commands print JSON to stdout and diagnostics to stderr. Errors and nonzero
+remote exit codes produce a nonzero local exit status. An authorized device is
+not necessarily online. Use `describe` to query its current platform and actions.
+
+The package exports the Gateway client, socket adapter, and action response
+contract for other clients. See [the device architecture and operating guide](../../docs/rome-node.md)
+for credential boundaries, file operations, output limits, and disconnection behavior.

package/bin/rome-node.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/entry.js";

package/dist/actions.d.ts

@@ -0,0 +1,20 @@
+export interface ActionRequest {
+    type: "request";
+    action: string;
+    args: unknown;
+}
+export type ActionResponse = {
+    type: "response";
+    ok: true;
+    result: unknown;
+} | {
+    type: "response";
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export declare function actionError(code: string, message: string): ActionResponse;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function parseResponse(value: unknown): ActionResponse | null;

package/dist/actions.js

@@ -0,0 +1,18 @@
+export function actionError(code, message) {
+    return { type: "response", ok: false, error: { code, message } };
+}
+export function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function parseResponse(value) {
+    if (!isRecord(value) || value.type !== "response")
+        return null;
+    if (value.ok === true && Object.hasOwn(value, "result"))
+        return { type: "response", ok: true, result: value.result };
+    if (value.ok === false &&
+        isRecord(value.error) &&
+        typeof value.error.code === "string" &&
+        typeof value.error.message === "string")
+        return actionError(value.error.code, value.error.message);
+    return null;
+}

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+import { type GatewayMessage, type OutboundEnvelope } from "./protocol.js";
+export interface ClientSocket {
+    readyState: number;
+    bufferedAmount: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "close", listener: (event: {
+        code: number;
+    }) => void): void;
+    addEventListener(type: "error", listener: () => void): void;
+}
+export type ConnectionStatus = "connecting" | "online" | "retrying" | "revoked" | "superseded" | "stopped";
+export interface GatewayClientOptions {
+    gatewayUrl: string;
+    deviceToken: string;
+    createSocket(url: string, authorization: string): ClientSocket;
+    onMessage(message: GatewayMessage): void;
+    onStatus?(status: ConnectionStatus): void;
+    random?(): number;
+    beforeConnect?(): Promise<string | null>;
+}
+export declare function connectGateway(options: GatewayClientOptions): {
+    send(envelope: OutboundEnvelope): boolean;
+    stop(): void;
+};

package/dist/client.js

@@ -0,0 +1,143 @@
+import { byteLength, CLOSE, gatewayMessage, MAX_CLIENT_BUFFER_BYTES, MAX_MESSAGE_BYTES, outboundEnvelope, } from "./protocol.js";
+export function connectGateway(options) {
+    let url = new URL(options.gatewayUrl);
+    if (url.protocol !== "wss:" || url.username || url.password || url.search || url.hash)
+        throw new Error("A credential-free WSS URL is required");
+    if (!/^(?:romedev_|romemob_)[A-Za-z0-9_-]{43}$/.test(options.deviceToken))
+        throw new Error("Invalid device token format");
+    let stopped = false;
+    let socket = null;
+    let attempt = 0;
+    let timer;
+    let connectingTimer;
+    let stableTimer;
+    const status = (value) => options.onStatus?.(value);
+    const schedule = () => {
+        if (stopped || timer)
+            return;
+        status("retrying");
+        const delay = Math.min(60_000, 1000 * 2 ** Math.min(attempt++, 6));
+        timer = setTimeout(() => {
+            timer = undefined;
+            void open();
+        }, delay * (0.75 + (options.random ?? Math.random)() * 0.5));
+    };
+    const open = async () => {
+        if (stopped)
+            return;
+        status("connecting");
+        let current;
+        try {
+            if (options.beforeConnect) {
+                const next = await options.beforeConnect();
+                if (stopped)
+                    return;
+                if (next === null) {
+                    stopped = true;
+                    status("revoked");
+                    return;
+                }
+                url = new URL(next);
+                if (url.protocol !== "wss:" || url.username || url.password || url.search || url.hash)
+                    throw new Error("A credential-free WSS URL is required");
+            }
+            current = options.createSocket(url.toString(), `Bearer ${options.deviceToken}`);
+        }
+        catch {
+            schedule();
+            return;
+        }
+        socket = current;
+        let finished = false;
+        const finish = (code) => {
+            if (finished || socket !== current)
+                return;
+            finished = true;
+            clearTimeout(connectingTimer);
+            clearTimeout(stableTimer);
+            socket = null;
+            if (code === CLOSE.revoked || code === CLOSE.superseded) {
+                stopped = true;
+                status(code === CLOSE.revoked ? "revoked" : "superseded");
+            }
+            else
+                schedule();
+        };
+        connectingTimer = setTimeout(() => {
+            finish();
+            current.close();
+        }, 10_000);
+        current.addEventListener("open", () => {
+            if (stopped || socket !== current) {
+                current.close();
+                return;
+            }
+            clearTimeout(connectingTimer);
+            stableTimer = setTimeout(() => {
+                attempt = 0;
+            }, 30_000);
+            status("online");
+        });
+        current.addEventListener("message", ({ data }) => {
+            if (stopped ||
+                socket !== current ||
+                typeof data !== "string" ||
+                byteLength(data) > MAX_MESSAGE_BYTES)
+                return;
+            let message;
+            try {
+                message = gatewayMessage(JSON.parse(data));
+            }
+            catch {
+                return;
+            }
+            if (message)
+                options.onMessage(message);
+        });
+        current.addEventListener("close", ({ code }) => finish(code));
+        current.addEventListener("error", () => {
+            finish();
+            current.close();
+        });
+    };
+    void open();
+    return {
+        send(envelope) {
+            if (stopped || !socket || socket.readyState !== 1 || !outboundEnvelope(envelope))
+                return false;
+            let text;
+            try {
+                text = JSON.stringify(envelope);
+                if (!outboundEnvelope(JSON.parse(text)))
+                    return false;
+            }
+            catch {
+                return false;
+            }
+            const size = byteLength(text);
+            if (size > MAX_MESSAGE_BYTES)
+                return false;
+            if (socket.bufferedAmount + size > MAX_CLIENT_BUFFER_BYTES) {
+                socket.close(CLOSE.outputLimit, "outbound buffer limit");
+                return false;
+            }
+            try {
+                socket.send(text);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        stop() {
+            stopped = true;
+            clearTimeout(timer);
+            clearTimeout(connectingTimer);
+            clearTimeout(stableTimer);
+            const previous = socket;
+            socket = null;
+            previous?.close(1000, "client stopped");
+            status("stopped");
+        },
+    };
+}

package/dist/cloud.d.ts

@@ -0,0 +1,7 @@
+export declare class CloudError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function cloudOrigin(value: string): string;
+export declare function cloudRequest(origin: string, path: string, token: string, method?: string): Promise<unknown>;
+export declare function gatewayConfig(origin: string, token: string): Promise<string>;

package/dist/cloud.js

@@ -0,0 +1,53 @@
+import { isRecord } from "./actions.js";
+export class CloudError extends Error {
+    code;
+    constructor(code) {
+        super(code === "invalid_device_session"
+            ? "Device authorization is invalid."
+            : "Rome Cloud is unavailable. Retry later.");
+        this.code = code;
+    }
+}
+export function cloudOrigin(value) {
+    const url = new URL(value);
+    if (url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/" ||
+        (url.protocol !== "https:" &&
+            !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))))
+        throw new Error("Use an HTTPS Cloud origin. HTTP is allowed only on loopback.");
+    return url.origin;
+}
+export async function cloudRequest(origin, path, token, method = "GET") {
+    let response;
+    try {
+        response = await fetch(new URL(path, cloudOrigin(origin)), {
+            method,
+            headers: { Authorization: `Bearer ${token}` },
+            redirect: "error",
+            signal: AbortSignal.timeout(10_000),
+            cache: "no-store",
+        });
+    }
+    catch {
+        throw new CloudError("cloud_unavailable");
+    }
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        if (response.status === 401 && isRecord(body) && body.error === "invalid_device_session")
+            throw new CloudError("invalid_device_session");
+        throw new CloudError("cloud_unavailable");
+    }
+    return body;
+}
+export async function gatewayConfig(origin, token) {
+    const body = await cloudRequest(origin, "/v1/gateway/config", token);
+    if (!isRecord(body) || typeof body.gatewayUrl !== "string")
+        throw new CloudError("invalid_response");
+    const url = new URL(body.gatewayUrl);
+    if (url.protocol !== "wss:" || url.username || url.password || url.search || url.hash)
+        throw new CloudError("invalid_response");
+    return url.toString();
+}

package/dist/connect.d.ts

@@ -0,0 +1,2 @@
+export declare function connectComputer(origin: string, name: string, signal: AbortSignal): Promise<void>;
+export declare const defaultDeviceName: () => string;

package/dist/connect.js

@@ -0,0 +1,114 @@
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { rm } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { isRecord } from "./actions.js";
+import { cloudOrigin, cloudRequest, CloudError, gatewayConfig } from "./cloud.js";
+import { connectGateway } from "./client.js";
+import { createNodeSocket } from "./socket.js";
+import { loginDevice } from "./login.js";
+import { readPrivateJson, writePrivateJson } from "./storage.js";
+import { createExecutor } from "./executor.js";
+import { validId } from "./protocol.js";
+import { configRoot } from "./local.js";
+export async function connectComputer(origin, name, signal) {
+    const cloudUrl = cloudOrigin(origin);
+    const path = join(configRoot(), "credential.json");
+    const stored = await readPrivateJson(path);
+    let session = isRecord(stored) &&
+        stored.cloudUrl === cloudUrl &&
+        typeof stored.token === "string" &&
+        /^romedev_[A-Za-z0-9_-]{43}$/.test(stored.token) &&
+        validId(stored.deviceId) &&
+        typeof stored.name === "string"
+        ? { cloudUrl, token: stored.token, deviceId: stored.deviceId, name: stored.name }
+        : null;
+    let gatewayUrl = "";
+    let attempt = 0;
+    while (!signal.aborted) {
+        if (!session) {
+            process.stderr.write("While connect is running, Rome instances in your account can execute programs and read or change files as your OS user.\n");
+            session = { ...(await loginDevice(cloudUrl, name, signal)), name };
+            await writePrivateJson(path, session);
+        }
+        try {
+            gatewayUrl = await gatewayConfig(cloudUrl, session.token);
+            break;
+        }
+        catch (error) {
+            if (error instanceof CloudError && error.code === "invalid_device_session") {
+                await rm(path, { force: true });
+                session = null;
+                continue;
+            }
+            process.stderr.write("Rome Cloud is unavailable; keeping credentials and retrying.\n");
+            await delay(Math.min(60_000, 1000 * 2 ** Math.min(attempt++, 6)), undefined, {
+                signal,
+            }).catch(() => { });
+        }
+    }
+    if (signal.aborted || !session)
+        return;
+    const devices = await cloudRequest(cloudUrl, "/api/account/devices", session.token).catch(() => null);
+    if (isRecord(devices) && Array.isArray(devices.items)) {
+        const device = devices.items.find((item) => isRecord(item) && item.id === session?.deviceId);
+        if (isRecord(device) && typeof device.device_name === "string") {
+            session.name = device.device_name;
+            await writePrivateJson(path, session);
+        }
+    }
+    if (signal.aborted)
+        return;
+    const active = session;
+    process.stderr.write(`Device: ${active.name}\nDevice ID: ${active.deviceId}\n`);
+    await new Promise((resolve, reject) => {
+        const executor = createExecutor(active.name, (message) => connection.send(message), [
+            active.token,
+        ]);
+        const finish = (error) => {
+            signal.removeEventListener("abort", abort);
+            executor.disconnect();
+            connection.stop();
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const abort = () => finish();
+        const connection = connectGateway({
+            gatewayUrl,
+            deviceToken: active.token,
+            createSocket: createNodeSocket,
+            beforeConnect: async () => {
+                try {
+                    return await gatewayConfig(cloudUrl, active.token);
+                }
+                catch (error) {
+                    if (error instanceof CloudError && error.code === "invalid_device_session")
+                        return null;
+                    throw error;
+                }
+            },
+            onMessage: (message) => {
+                if ("from" in message)
+                    void executor.receive(message);
+            },
+            onStatus: (status) => {
+                process.stderr.write(`Connection: ${status}\n`);
+                if (status !== "online" && status !== "connecting")
+                    executor.disconnect();
+                if (status === "revoked" || status === "superseded") {
+                    queueMicrotask(() => finish(new Error(status === "revoked"
+                        ? "Authorization revoked. Run rome-node connect again to authorize."
+                        : "Another connection replaced this device. This process has stopped.")));
+                }
+            },
+        });
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+}
+export const defaultDeviceName = () => hostname()
+    .replace(/[\u0000-\u001f\u007f]/g, "")
+    .slice(0, 80) || "Computer";

package/dist/connector.d.ts

@@ -0,0 +1,24 @@
+import { type ActionResponse } from "./actions.js";
+import { connectGateway } from "./client.js";
+import type { CallerCredential } from "./local.js";
+export interface DeviceConnectorOptions {
+    credential: CallerCredential;
+    connect?: typeof connectGateway;
+    waitMs?: number;
+}
+export declare class DeviceConnector {
+    private options;
+    private connection?;
+    private initializing?;
+    private status;
+    private stopped;
+    private pending;
+    private ready;
+    constructor(options: DeviceConnectorOptions);
+    private ensure;
+    private initialize;
+    list(): Promise<unknown>;
+    private receive;
+    run(target: string, action: string, args: unknown): Promise<ActionResponse>;
+    stop(): void;
+}

package/dist/connector.js

@@ -0,0 +1,148 @@
+import { randomUUID } from "node:crypto";
+import { actionError, isRecord, parseResponse, } from "./actions.js";
+import { connectGateway } from "./client.js";
+import { cloudRequest, CloudError, gatewayConfig } from "./cloud.js";
+import { byteLength, MAX_MESSAGE_BYTES, validId } from "./protocol.js";
+import { createNodeSocket } from "./socket.js";
+export class DeviceConnector {
+    options;
+    connection;
+    initializing;
+    status = "stopped";
+    stopped = false;
+    pending = new Map();
+    ready = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    async ensure() {
+        if (this.stopped || this.status === "superseded" || this.status === "revoked")
+            throw new Error("connector_stopped");
+        if (this.connection)
+            return;
+        if (this.initializing)
+            return this.initializing;
+        this.initializing = this.initialize();
+        try {
+            await this.initializing;
+        }
+        finally {
+            this.initializing = undefined;
+        }
+    }
+    async initialize() {
+        const { cloudUrl, token } = this.options.credential;
+        const gatewayUrl = await gatewayConfig(cloudUrl, token);
+        if (this.stopped)
+            throw new Error("connector_stopped");
+        this.connection = (this.options.connect ?? connectGateway)({
+            gatewayUrl,
+            deviceToken: token,
+            createSocket: createNodeSocket,
+            beforeConnect: async () => {
+                try {
+                    return await gatewayConfig(cloudUrl, token);
+                }
+                catch (error) {
+                    if (error instanceof CloudError && error.code === "invalid_device_session")
+                        return null;
+                    throw error;
+                }
+            },
+            onMessage: (message) => this.receive(message),
+            onStatus: (status) => {
+                this.status = status;
+                if (status !== "online") {
+                    for (const pending of this.pending.values())
+                        pending.finish(actionError("unknown_outcome", "The connection was lost. Execution may have occurred. Do not automatically retry."));
+                }
+                for (const wake of this.ready)
+                    wake();
+            },
+        });
+    }
+    async list() {
+        if (this.stopped)
+            throw new Error("connector_stopped");
+        const { cloudUrl, token } = this.options.credential;
+        const body = await cloudRequest(cloudUrl, "/api/account/devices", token);
+        if (!isRecord(body) || !Array.isArray(body.items))
+            throw new CloudError("invalid_response");
+        return { items: body.items };
+    }
+    receive(message) {
+        const pending = this.pending.get(message.id);
+        if (!pending)
+            return;
+        if ("type" in message) {
+            pending.finish(actionError(message.code, "The Gateway could not forward the request."));
+            return;
+        }
+        if (message.from !== pending.target)
+            return;
+        const response = parseResponse(message.payload);
+        if (response)
+            pending.finish(response);
+    }
+    async run(target, action, args) {
+        if (!validId(target) || !action || action.length > 128)
+            return actionError("invalid_request", "A device ID and action are required.");
+        try {
+            await this.ensure();
+        }
+        catch {
+            return actionError("gateway_unavailable", "The device connection is unavailable.");
+        }
+        if (this.status !== "online")
+            await new Promise((resolve) => {
+                const finish = () => {
+                    clearTimeout(timer);
+                    this.ready.delete(wake);
+                    resolve();
+                };
+                const wake = () => {
+                    if (["online", "revoked", "superseded", "stopped"].includes(this.status))
+                        finish();
+                };
+                const timer = setTimeout(finish, 10_000);
+                this.ready.add(wake);
+                wake();
+            });
+        if (this.status !== "online")
+            return actionError("gateway_unavailable", "The device connection is offline. No operation was sent.");
+        if (this.pending.size >= 128)
+            return actionError("busy", "Too many device requests are pending.");
+        const id = randomUUID();
+        const envelope = {
+            id,
+            to: target,
+            payload: { type: "request", action, args },
+        };
+        try {
+            if (byteLength(JSON.stringify(envelope)) > MAX_MESSAGE_BYTES)
+                return actionError("message_too_large", "The request exceeds 128 KiB.");
+        }
+        catch {
+            return actionError("invalid_request", "Action arguments must be JSON.");
+        }
+        return new Promise((resolve) => {
+            const finish = (response) => {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                resolve(response);
+            };
+            const timer = setTimeout(() => finish(actionError("unknown_outcome", "The local wait limit was reached. The remote program was not canceled. Do not automatically retry.")), this.options.waitMs ?? 60_000);
+            this.pending.set(id, { target, finish });
+            if (!this.connection?.send(envelope))
+                finish(actionError("unknown_outcome", "The request could not be submitted reliably. Do not automatically retry."));
+        });
+    }
+    stop() {
+        this.stopped = true;
+        this.connection?.stop();
+        for (const pending of this.pending.values())
+            pending.finish(actionError("unknown_outcome", "The CLI daemon is shutting down. Execution may have occurred."));
+        for (const wake of this.ready)
+            wake();
+    }
+}

package/dist/daemon.d.ts

@@ -0,0 +1,11 @@
+interface DaemonState {
+    token: string;
+    port: number;
+    pid: number;
+}
+export declare function daemonStatus(): Promise<DaemonState | null>;
+export declare function startDaemon(): Promise<DaemonState>;
+export declare function stopDaemon(): Promise<void>;
+export declare function callDaemon(path: "/devices" | "/run", body?: unknown): Promise<Response>;
+export declare function serveDaemon(): Promise<void>;
+export {};