@aria-cli/tools 1.0.0

package/src/definitions/process/process.ts

@@ -0,0 +1,456 @@
+/**
+ * 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 { spawn as nodeSpawn } from "node:child_process";
+import type { JSONSchema7 } from "json-schema";
+import type { Tool, ToolResult } from "../../types.js";
+import { sanitizeEnv } from "../../executors/shell.js";
+import {
+  createSessionSlug,
+  addSession,
+  getSession,
+  getFinishedSession,
+  appendOutput,
+  drainSession,
+  markExited,
+  markBackgrounded,
+  listRunningSessions,
+  listFinishedSessions,
+  type ProcessSession,
+} from "./process-registry.js";
+import { encodeKeySequence } from "./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
+
+// ── Input type ──────────────────────────────────────────────────────
+
+interface ProcessInput {
+  action: "spawn" | "read" | "write" | "kill" | "list" | "send_key";
+  command?: string;
+  session_id?: string;
+  input?: string;
+  key?: string;
+  timeout?: number;
+  signal?: string;
+}
+
+// ── Action handlers ─────────────────────────────────────────────────
+
+function handleSpawn(input: ProcessInput, cwd: string): Promise<ToolResult> {
+  return new Promise((resolve) => {
+    const command = input.command;
+    if (!command) {
+      resolve({ success: false, message: "spawn requires 'command' parameter" });
+      return;
+    }
+
+    const sessionId = createSessionSlug();
+    const timeout = Math.min(input.timeout ?? DEFAULT_SPAWN_TIMEOUT_MS, MAX_SPAWN_TIMEOUT_MS);
+
+    const child = nodeSpawn("sh", ["-c", command], {
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: sanitizeEnv(),
+      detached: false,
+    });
+
+    const session: ProcessSession = {
+      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: string, cb?: (err?: Error | null) => void) => child.stdin.write(data, cb),
+            end: () => child.stdin.end(),
+            destroy: () => child.stdin.destroy(),
+            get destroyed() {
+              return child.stdin.destroyed;
+            },
+          }
+        : undefined,
+    };
+
+    addSession(session);
+    markBackgrounded(session);
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      appendOutput(session, "stdout", chunk.toString());
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      appendOutput(session, "stderr", chunk.toString());
+    });
+
+    child.on("error", (err: Error) => {
+      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";
+      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 } = 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: ProcessInput): ToolResult {
+  const sessionId = input.session_id;
+  if (!sessionId) {
+    return { success: false, message: "read requires 'session_id' parameter" };
+  }
+
+  const session = getSession(sessionId);
+  if (session) {
+    const { stdout, stderr } = 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): s is string => 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 = 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: ProcessInput): Promise<ToolResult> {
+  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 = getSession(sessionId);
+  if (!session) {
+    const finished = 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<ToolResult>((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: ProcessInput): ToolResult {
+  const sessionId = input.session_id;
+  if (!sessionId) {
+    return { success: false, message: "kill requires 'session_id' parameter" };
+  }
+
+  const session = getSession(sessionId);
+  if (!session) {
+    const finished = 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") as NodeJS.Signals;
+
+  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(): ToolResult {
+  const running = 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 = 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: ProcessInput): Promise<ToolResult> {
+  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 = getSession(sessionId);
+  if (!session) {
+    const finished = 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 } = encodeKeySequence({ keys: [input.key] });
+
+  if (!keyData) {
+    return {
+      success: false,
+      message: `Could not encode key: ${input.key}${warnings.length ? ` (${warnings.join(", ")})` : ""}`,
+    };
+  }
+
+  return new Promise<ToolResult>((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 ─────────────────────────────────────────────────
+
+export const processTool: Tool = {
+  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"],
+  } as JSONSchema7,
+  riskLevel: "dangerous",
+  isReadOnly: false,
+  loadingTier: "always",
+
+  async execute(rawInput: unknown, context) {
+    const input = rawInput as ProcessInput;
+    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 as { action: string }).action}. Valid actions: spawn, read, write, kill, list, send_key`,
+        };
+    }
+  },
+};