@aria-cli/tools 1.0.10 → 1.0.12

package/dist-cjs/definitions/process/process-registry.js

@@ -0,0 +1,231 @@
+"use strict";
+// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
+// https://github.com/openclaw/openclaw
+// Modified for ARIA — stripped OpenClaw runtime (PI_BASH_JOB_TTL_MS env, gateway refs),
+// rewired imports to local session-slug
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionSlug = createSessionSlug;
+exports.addSession = addSession;
+exports.getSession = getSession;
+exports.getFinishedSession = getFinishedSession;
+exports.deleteSession = deleteSession;
+exports.appendOutput = appendOutput;
+exports.drainSession = drainSession;
+exports.markExited = markExited;
+exports.markBackgrounded = markBackgrounded;
+exports.tail = tail;
+exports.trimWithCap = trimWithCap;
+exports.listRunningSessions = listRunningSessions;
+exports.listFinishedSessions = listFinishedSessions;
+exports.clearFinished = clearFinished;
+exports.resetProcessRegistryForTests = resetProcessRegistryForTests;
+exports.setJobTtlMs = setJobTtlMs;
+const session_slug_js_1 = require("./session-slug.js");
+const DEFAULT_JOB_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const MIN_JOB_TTL_MS = 60 * 1000; // 1 minute
+const MAX_JOB_TTL_MS = 3 * 60 * 60 * 1000; // 3 hours
+const DEFAULT_PENDING_OUTPUT_CHARS = 30_000;
+function clampTtl(value) {
+    if (!value || Number.isNaN(value)) {
+        return DEFAULT_JOB_TTL_MS;
+    }
+    return Math.min(Math.max(value, MIN_JOB_TTL_MS), MAX_JOB_TTL_MS);
+}
+let jobTtlMs = DEFAULT_JOB_TTL_MS;
+const runningSessions = new Map();
+const finishedSessions = new Map();
+let sweeper = null;
+function isSessionIdTaken(id) {
+    return runningSessions.has(id) || finishedSessions.has(id);
+}
+function createSessionSlug() {
+    return (0, session_slug_js_1.createSessionSlug)(isSessionIdTaken);
+}
+function addSession(session) {
+    runningSessions.set(session.id, session);
+    startSweeper();
+}
+function getSession(id) {
+    return runningSessions.get(id);
+}
+function getFinishedSession(id) {
+    return finishedSessions.get(id);
+}
+function deleteSession(id) {
+    runningSessions.delete(id);
+    finishedSessions.delete(id);
+}
+function appendOutput(session, stream, chunk) {
+    session.pendingStdout ??= [];
+    session.pendingStderr ??= [];
+    session.pendingStdoutChars ??= sumPendingChars(session.pendingStdout);
+    session.pendingStderrChars ??= sumPendingChars(session.pendingStderr);
+    const buffer = stream === "stdout" ? session.pendingStdout : session.pendingStderr;
+    const bufferChars = stream === "stdout" ? session.pendingStdoutChars : session.pendingStderrChars;
+    const pendingCap = Math.min(session.pendingMaxOutputChars ?? DEFAULT_PENDING_OUTPUT_CHARS, session.maxOutputChars);
+    buffer.push(chunk);
+    let pendingChars = bufferChars + chunk.length;
+    if (pendingChars > pendingCap) {
+        session.truncated = true;
+        pendingChars = capPendingBuffer(buffer, pendingChars, pendingCap);
+    }
+    if (stream === "stdout") {
+        session.pendingStdoutChars = pendingChars;
+    }
+    else {
+        session.pendingStderrChars = pendingChars;
+    }
+    session.totalOutputChars += chunk.length;
+    const aggregated = trimWithCap(session.aggregated + chunk, session.maxOutputChars);
+    session.truncated =
+        session.truncated || aggregated.length < session.aggregated.length + chunk.length;
+    session.aggregated = aggregated;
+    session.tail = tail(session.aggregated, 2000);
+}
+function drainSession(session) {
+    const stdout = session.pendingStdout.join("");
+    const stderr = session.pendingStderr.join("");
+    session.pendingStdout = [];
+    session.pendingStderr = [];
+    session.pendingStdoutChars = 0;
+    session.pendingStderrChars = 0;
+    return { stdout, stderr };
+}
+function markExited(session, exitCode, exitSignal, status) {
+    session.exited = true;
+    session.exitCode = exitCode;
+    session.exitSignal = exitSignal;
+    session.tail = tail(session.aggregated, 2000);
+    moveToFinished(session, status);
+}
+function markBackgrounded(session) {
+    session.backgrounded = true;
+}
+function moveToFinished(session, status) {
+    runningSessions.delete(session.id);
+    // Clean up child process stdio streams to prevent FD leaks
+    if (session.child) {
+        session.child.stdin?.destroy?.();
+        session.child.stdout?.destroy?.();
+        session.child.stderr?.destroy?.();
+        session.child.removeAllListeners();
+        delete session.child;
+    }
+    // Clean up stdin wrapper
+    if (session.stdin) {
+        if (typeof session.stdin.destroy === "function") {
+            session.stdin.destroy();
+        }
+        else if (typeof session.stdin.end === "function") {
+            session.stdin.end();
+        }
+        try {
+            session.stdin.destroyed = true;
+        }
+        catch {
+            // Ignore if read-only
+        }
+        delete session.stdin;
+    }
+    if (!session.backgrounded) {
+        return;
+    }
+    finishedSessions.set(session.id, {
+        id: session.id,
+        command: session.command,
+        startedAt: session.startedAt,
+        endedAt: Date.now(),
+        cwd: session.cwd,
+        status,
+        exitCode: session.exitCode,
+        exitSignal: session.exitSignal,
+        aggregated: session.aggregated,
+        tail: session.tail,
+        truncated: session.truncated,
+        totalOutputChars: session.totalOutputChars,
+    });
+}
+function tail(text, max = 2000) {
+    if (text.length <= max) {
+        return text;
+    }
+    return text.slice(text.length - max);
+}
+function sumPendingChars(buffer) {
+    let total = 0;
+    for (const chunk of buffer) {
+        total += chunk.length;
+    }
+    return total;
+}
+function capPendingBuffer(buffer, pendingChars, cap) {
+    if (pendingChars <= cap) {
+        return pendingChars;
+    }
+    const last = buffer.at(-1);
+    if (last && last.length >= cap) {
+        buffer.length = 0;
+        buffer.push(last.slice(last.length - cap));
+        return cap;
+    }
+    while (buffer.length && buffer[0] !== undefined && pendingChars - buffer[0].length >= cap) {
+        pendingChars -= buffer[0].length;
+        buffer.shift();
+    }
+    if (buffer.length && buffer[0] !== undefined && pendingChars > cap) {
+        const overflow = pendingChars - cap;
+        buffer[0] = buffer[0].slice(overflow);
+        pendingChars = cap;
+    }
+    return pendingChars;
+}
+function trimWithCap(text, max) {
+    if (text.length <= max) {
+        return text;
+    }
+    return text.slice(text.length - max);
+}
+function listRunningSessions() {
+    return Array.from(runningSessions.values()).filter((s) => s.backgrounded);
+}
+function listFinishedSessions() {
+    return Array.from(finishedSessions.values());
+}
+function clearFinished() {
+    finishedSessions.clear();
+}
+function resetProcessRegistryForTests() {
+    runningSessions.clear();
+    finishedSessions.clear();
+    stopSweeper();
+}
+function setJobTtlMs(value) {
+    if (value === undefined || Number.isNaN(value)) {
+        return;
+    }
+    jobTtlMs = clampTtl(value);
+    stopSweeper();
+    startSweeper();
+}
+function pruneFinishedSessions() {
+    const cutoff = Date.now() - jobTtlMs;
+    for (const [id, session] of finishedSessions.entries()) {
+        if (session.endedAt < cutoff) {
+            finishedSessions.delete(id);
+        }
+    }
+}
+function startSweeper() {
+    if (sweeper) {
+        return;
+    }
+    sweeper = setInterval(pruneFinishedSessions, Math.max(30_000, jobTtlMs / 6));
+    sweeper.unref?.();
+}
+function stopSweeper() {
+    if (!sweeper) {
+        return;
+    }
+    clearInterval(sweeper);
+    sweeper = null;
+}

package/dist-cjs/definitions/process/process.d.ts

@@ -0,0 +1,9 @@
+/**
+ * process tool — ARIA Tool wrapper for background shell process management.
+ *
+ * Supports spawn/read/write/kill/list/send_key actions.
+ * Uses node:child_process (no native deps).
+ * Process registry forked from OpenClaw (MIT).
+ */
+import type { Tool } from "../../types.js";
+export declare const processTool: Tool;

package/dist-cjs/definitions/process/process.js

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * process tool — ARIA Tool wrapper for background shell process management.
+ *
+ * Supports spawn/read/write/kill/list/send_key actions.
+ * Uses node:child_process (no native deps).
+ * Process registry forked from OpenClaw (MIT).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processTool = void 0;
+const node_child_process_1 = require("node:child_process");
+const shell_js_1 = require("../../executors/shell.js");
+const process_registry_js_1 = require("./process-registry.js");
+const pty_keys_js_1 = require("./pty-keys.js");
+// ── Constants ───────────────────────────────────────────────────────
+const MAX_OUTPUT_CHARS = 200_000; // 200KB ring buffer cap per process
+const DEFAULT_SPAWN_TIMEOUT_MS = 30_000;
+const MAX_SPAWN_TIMEOUT_MS = 300_000; // 5 minutes
+const OUTPUT_SETTLE_MS = 200; // wait for initial output after spawn
+// ── Action handlers ─────────────────────────────────────────────────
+function handleSpawn(input, cwd) {
+    return new Promise((resolve) => {
+        const command = input.command;
+        if (!command) {
+            resolve({ success: false, message: "spawn requires 'command' parameter" });
+            return;
+        }
+        const sessionId = (0, process_registry_js_1.createSessionSlug)();
+        const timeout = Math.min(input.timeout ?? DEFAULT_SPAWN_TIMEOUT_MS, MAX_SPAWN_TIMEOUT_MS);
+        const child = (0, node_child_process_1.spawn)("sh", ["-c", command], {
+            cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: (0, shell_js_1.sanitizeEnv)(),
+            detached: false,
+        });
+        const session = {
+            id: sessionId,
+            command,
+            pid: child.pid,
+            startedAt: Date.now(),
+            cwd,
+            maxOutputChars: MAX_OUTPUT_CHARS,
+            totalOutputChars: 0,
+            pendingStdout: [],
+            pendingStderr: [],
+            pendingStdoutChars: 0,
+            pendingStderrChars: 0,
+            aggregated: "",
+            tail: "",
+            exited: false,
+            truncated: false,
+            backgrounded: true,
+            child,
+            stdin: child.stdin
+                ? {
+                    write: (data, cb) => child.stdin.write(data, cb),
+                    end: () => child.stdin.end(),
+                    destroy: () => child.stdin.destroy(),
+                    get destroyed() {
+                        return child.stdin.destroyed;
+                    },
+                }
+                : undefined,
+        };
+        (0, process_registry_js_1.addSession)(session);
+        (0, process_registry_js_1.markBackgrounded)(session);
+        child.stdout?.on("data", (chunk) => {
+            (0, process_registry_js_1.appendOutput)(session, "stdout", chunk.toString());
+        });
+        child.stderr?.on("data", (chunk) => {
+            (0, process_registry_js_1.appendOutput)(session, "stderr", chunk.toString());
+        });
+        child.on("error", (err) => {
+            (0, process_registry_js_1.markExited)(session, null, null, "failed");
+            // Error after we already resolved is fine — the process just failed later
+        });
+        child.on("exit", (code, signal) => {
+            if (session.exited)
+                return;
+            const status = signal ? "killed" : code === 0 ? "completed" : "failed";
+            (0, process_registry_js_1.markExited)(session, code, signal, status);
+        });
+        // Set up timeout to kill if it runs too long without interaction
+        if (timeout > 0) {
+            const timer = setTimeout(() => {
+                if (!session.exited) {
+                    try {
+                        child.kill("SIGTERM");
+                    }
+                    catch {
+                        // Process may have already exited
+                    }
+                }
+            }, timeout);
+            timer.unref();
+            // Clear timeout if process exits before timeout
+            child.on("exit", () => clearTimeout(timer));
+        }
+        // Wait briefly for initial output
+        setTimeout(() => {
+            const { stdout, stderr } = (0, process_registry_js_1.drainSession)(session);
+            const initialOutput = [stdout && `stdout: ${stdout}`, stderr && `stderr: ${stderr}`]
+                .filter(Boolean)
+                .join("\n");
+            resolve({
+                success: true,
+                message: [
+                    `Process spawned with session_id: ${sessionId}`,
+                    `PID: ${child.pid}`,
+                    `Command: ${command}`,
+                    initialOutput && `\nInitial output:\n${initialOutput}`,
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+                data: { session_id: sessionId, pid: child.pid },
+            });
+        }, OUTPUT_SETTLE_MS);
+    });
+}
+function handleRead(input) {
+    const sessionId = input.session_id;
+    if (!sessionId) {
+        return { success: false, message: "read requires 'session_id' parameter" };
+    }
+    const session = (0, process_registry_js_1.getSession)(sessionId);
+    if (session) {
+        const { stdout, stderr } = (0, process_registry_js_1.drainSession)(session);
+        const hasOutput = stdout || stderr;
+        return {
+            success: true,
+            message: [
+                `Session: ${sessionId} (running, PID: ${session.pid})`,
+                hasOutput ? "" : "(no new output since last read)",
+                stdout && `stdout:\n${stdout}`,
+                stderr && `stderr:\n${stderr}`,
+            ]
+                .filter((s) => typeof s === "string" && s !== "")
+                .join("\n"),
+            data: {
+                session_id: sessionId,
+                status: "running",
+                pid: session.pid,
+                stdout,
+                stderr,
+                total_output_chars: session.totalOutputChars,
+                truncated: session.truncated,
+            },
+        };
+    }
+    const finished = (0, process_registry_js_1.getFinishedSession)(sessionId);
+    if (finished) {
+        return {
+            success: true,
+            message: [
+                `Session: ${sessionId} (${finished.status})`,
+                `Exit code: ${finished.exitCode ?? "N/A"}`,
+                finished.exitSignal && `Signal: ${finished.exitSignal}`,
+                `Output:\n${finished.tail}`,
+                finished.truncated && "(output was truncated)",
+            ]
+                .filter(Boolean)
+                .join("\n"),
+            data: {
+                session_id: sessionId,
+                status: finished.status,
+                exit_code: finished.exitCode,
+                exit_signal: finished.exitSignal,
+                output: finished.tail,
+                total_output_chars: finished.totalOutputChars,
+                truncated: finished.truncated,
+            },
+        };
+    }
+    return { success: false, message: `No session found with id: ${sessionId}` };
+}
+async function handleWrite(input) {
+    const sessionId = input.session_id;
+    if (!sessionId) {
+        return { success: false, message: "write requires 'session_id' parameter" };
+    }
+    if (input.input === undefined || input.input === null) {
+        return { success: false, message: "write requires 'input' parameter" };
+    }
+    const session = (0, process_registry_js_1.getSession)(sessionId);
+    if (!session) {
+        const finished = (0, process_registry_js_1.getFinishedSession)(sessionId);
+        if (finished) {
+            return {
+                success: false,
+                message: `Session ${sessionId} has already exited (${finished.status})`,
+            };
+        }
+        return { success: false, message: `No session found with id: ${sessionId}` };
+    }
+    if (!session.stdin || session.stdin.destroyed) {
+        return { success: false, message: `Session ${sessionId} stdin is not available` };
+    }
+    return new Promise((resolve) => {
+        session.stdin.write(input.input, (err) => {
+            if (err) {
+                resolve({
+                    success: false,
+                    message: `Failed to write to session ${sessionId}: ${err.message}`,
+                });
+                return;
+            }
+            resolve({
+                success: true,
+                message: `Wrote ${input.input.length} chars to session ${sessionId}`,
+                data: { session_id: sessionId, bytes_written: input.input.length },
+            });
+        });
+    });
+}
+function handleKill(input) {
+    const sessionId = input.session_id;
+    if (!sessionId) {
+        return { success: false, message: "kill requires 'session_id' parameter" };
+    }
+    const session = (0, process_registry_js_1.getSession)(sessionId);
+    if (!session) {
+        const finished = (0, process_registry_js_1.getFinishedSession)(sessionId);
+        if (finished) {
+            return {
+                success: false,
+                message: `Session ${sessionId} has already exited (${finished.status})`,
+            };
+        }
+        return { success: false, message: `No session found with id: ${sessionId}` };
+    }
+    const signal = (input.signal ?? "SIGTERM");
+    if (session.child) {
+        try {
+            session.child.kill(signal);
+        }
+        catch {
+            // Process may have already exited
+        }
+    }
+    return {
+        success: true,
+        message: `Sent ${signal} to session ${sessionId} (PID: ${session.pid})`,
+        data: { session_id: sessionId, signal },
+    };
+}
+function handleList() {
+    const running = (0, process_registry_js_1.listRunningSessions)().map((s) => ({
+        session_id: s.id,
+        command: s.command,
+        pid: s.pid,
+        status: s.exited ? "exited" : "running",
+        started_at: new Date(s.startedAt).toISOString(),
+        runtime_ms: Date.now() - s.startedAt,
+        total_output_chars: s.totalOutputChars,
+    }));
+    const finished = (0, process_registry_js_1.listFinishedSessions)().map((s) => ({
+        session_id: s.id,
+        command: s.command,
+        status: s.status,
+        exit_code: s.exitCode,
+        started_at: new Date(s.startedAt).toISOString(),
+        ended_at: new Date(s.endedAt).toISOString(),
+        runtime_ms: s.endedAt - s.startedAt,
+        total_output_chars: s.totalOutputChars,
+    }));
+    const all = [...running, ...finished];
+    if (all.length === 0) {
+        return { success: true, message: "No active or recent sessions.", data: { sessions: [] } };
+    }
+    const lines = all.map((s) => `  ${s.session_id}: ${s.command} [${s.status}] (${s.runtime_ms}ms)`);
+    return {
+        success: true,
+        message: `Sessions (${all.length}):\n${lines.join("\n")}`,
+        data: { sessions: all },
+    };
+}
+async function handleSendKey(input) {
+    const sessionId = input.session_id;
+    if (!sessionId) {
+        return { success: false, message: "send_key requires 'session_id' parameter" };
+    }
+    if (!input.key) {
+        return { success: false, message: "send_key requires 'key' parameter" };
+    }
+    const session = (0, process_registry_js_1.getSession)(sessionId);
+    if (!session) {
+        const finished = (0, process_registry_js_1.getFinishedSession)(sessionId);
+        if (finished) {
+            return {
+                success: false,
+                message: `Session ${sessionId} has already exited (${finished.status})`,
+            };
+        }
+        return { success: false, message: `No session found with id: ${sessionId}` };
+    }
+    if (!session.stdin || session.stdin.destroyed) {
+        return { success: false, message: `Session ${sessionId} stdin is not available` };
+    }
+    const { data: keyData, warnings } = (0, pty_keys_js_1.encodeKeySequence)({ keys: [input.key] });
+    if (!keyData) {
+        return {
+            success: false,
+            message: `Could not encode key: ${input.key}${warnings.length ? ` (${warnings.join(", ")})` : ""}`,
+        };
+    }
+    return new Promise((resolve) => {
+        session.stdin.write(keyData, (err) => {
+            if (err) {
+                resolve({
+                    success: false,
+                    message: `Failed to send key to session ${sessionId}: ${err.message}`,
+                });
+                return;
+            }
+            resolve({
+                success: true,
+                message: `Sent key '${input.key}' to session ${sessionId}${warnings.length ? ` (warnings: ${warnings.join(", ")})` : ""}`,
+                data: { session_id: sessionId, key: input.key, warnings },
+            });
+        });
+    });
+}
+// ── Tool definition ─────────────────────────────────────────────────
+exports.processTool = {
+    name: "process",
+    description: "Manage background shell processes. Supports spawning long-running commands, reading their output, writing input, and killing them. Each process gets a human-readable session ID.",
+    category: "shell",
+    parameters: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["spawn", "read", "write", "kill", "list", "send_key"],
+                description: "Action to perform",
+            },
+            command: {
+                type: "string",
+                description: "Shell command to run (for spawn)",
+            },
+            session_id: {
+                type: "string",
+                description: "Session ID (from spawn result)",
+            },
+            input: {
+                type: "string",
+                description: "Input to write to stdin (for write)",
+            },
+            key: {
+                type: "string",
+                description: "Special key to send (for send_key): Enter, Tab, Ctrl+C, Up, Down, etc.",
+            },
+            timeout: {
+                type: "number",
+                description: "Timeout in ms (for spawn, default 30000)",
+            },
+            signal: {
+                type: "string",
+                description: "Signal to send (for kill, default SIGTERM)",
+            },
+        },
+        required: ["action"],
+    },
+    riskLevel: "dangerous",
+    isReadOnly: false,
+    loadingTier: "always",
+    async execute(rawInput, context) {
+        const input = rawInput;
+        const cwd = context.workingDir;
+        switch (input.action) {
+            case "spawn":
+                return handleSpawn(input, cwd);
+            case "read":
+                return handleRead(input);
+            case "write":
+                return handleWrite(input);
+            case "kill":
+                return handleKill(input);
+            case "list":
+                return handleList();
+            case "send_key":
+                return handleSendKey(input);
+            default:
+                return {
+                    success: false,
+                    message: `Unknown action: ${input.action}. Valid actions: spawn, read, write, kill, list, send_key`,
+                };
+        }
+    },
+};

package/dist-cjs/definitions/process/pty-keys.d.ts

@@ -0,0 +1,13 @@
+export declare const BRACKETED_PASTE_START = "\u001B[200~";
+export declare const BRACKETED_PASTE_END = "\u001B[201~";
+export type KeyEncodingRequest = {
+    keys?: string[];
+    hex?: string[];
+    literal?: string;
+};
+export type KeyEncodingResult = {
+    data: string;
+    warnings: string[];
+};
+export declare function encodeKeySequence(request: KeyEncodingRequest): KeyEncodingResult;
+export declare function encodePaste(text: string, bracketed?: boolean): string;