@mjakl/pi-processes 0.8.0

package/src/manager.ts

@@ -0,0 +1,513 @@
+import { EventEmitter } from "node:events";
+import {
+  appendFileSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  type KillResult,
+  LIVE_STATUSES,
+  type ManagerEvent,
+  type ProcessInfo,
+  type ProcessStatus,
+  type ResolveProcessResult,
+} from "./constants";
+import { isProcessGroupAlive, killProcessGroup } from "./utils";
+import { spawnCommand } from "./utils/command-executor";
+
+interface ManagedProcess extends ProcessInfo {
+  lastSignalSent: NodeJS.Signals | null;
+  combinedFile: string;
+  triggerAgentTurnOnEnd: boolean;
+}
+
+interface ProcessManagerOptions {
+  getConfiguredShellPath?: () => string | undefined;
+}
+
+export class ProcessManager {
+  private processes: Map<string, ManagedProcess> = new Map();
+  private counter = 0;
+  private logDir: string;
+  private events = new EventEmitter();
+  private watcher: ReturnType<typeof setInterval> | null = null;
+  private getConfiguredShellPath: () => string | undefined;
+
+  constructor(options?: ProcessManagerOptions) {
+    this.logDir = join(tmpdir(), `pi-processes-${Date.now()}`);
+    mkdirSync(this.logDir, { recursive: true });
+    this.getConfiguredShellPath =
+      options?.getConfiguredShellPath ?? (() => undefined);
+  }
+
+  onEvent(listener: (event: ManagerEvent) => void): () => void {
+    this.events.on("event", listener);
+    return () => this.events.off("event", listener);
+  }
+
+  private emit(event: ManagerEvent): void {
+    this.events.emit("event", event);
+  }
+
+  private transition(managed: ManagedProcess, next: ProcessStatus): void {
+    if (managed.status === next) return;
+    managed.status = next;
+
+    this.emit({ type: "processes_changed" });
+
+    if (next === "exited" || next === "killed") {
+      this.emit({
+        type: "process_ended",
+        info: this.toProcessInfo(managed),
+        triggerAgentTurn: managed.triggerAgentTurnOnEnd,
+      });
+    }
+
+    this.ensureWatcherRunning();
+    this.stopWatcherIfIdle();
+  }
+
+  private ensureWatcherRunning(): void {
+    if (this.watcher) return;
+    if (!this.hasAliveishProcesses()) return;
+
+    this.watcher = setInterval(() => {
+      this.livenessTick();
+    }, 5000);
+  }
+
+  private stopWatcherIfIdle(): void {
+    if (!this.watcher) return;
+    if (this.hasAliveishProcesses()) return;
+
+    clearInterval(this.watcher);
+    this.watcher = null;
+  }
+
+  private hasAliveishProcesses(): boolean {
+    for (const p of this.processes.values()) {
+      if (LIVE_STATUSES.has(p.status)) return true;
+    }
+    return false;
+  }
+
+  private livenessTick(): void {
+    for (const managed of this.processes.values()) {
+      if (!LIVE_STATUSES.has(managed.status)) continue;
+      if (!managed.pid || managed.pid <= 0) continue;
+
+      const alive = isProcessGroupAlive(managed.pid);
+      if (alive) continue;
+
+      if (!managed.endTime) {
+        managed.endTime = Date.now();
+      }
+
+      if (managed.lastSignalSent) {
+        managed.success = false;
+        managed.exitCode = null;
+        this.transition(managed, "killed");
+      } else {
+        managed.success = false;
+        managed.exitCode = null;
+        this.transition(managed, "exited");
+      }
+    }
+  }
+
+  start(name: string, command: string, cwd: string): ProcessInfo {
+    const id = `proc_${++this.counter}`;
+    const stdoutFile = join(this.logDir, `${id}-stdout.log`);
+    const stderrFile = join(this.logDir, `${id}-stderr.log`);
+    const combinedFile = join(this.logDir, `${id}-combined.log`);
+
+    appendFileSync(stdoutFile, "");
+    appendFileSync(stderrFile, "");
+    appendFileSync(combinedFile, "");
+
+    const child = spawnCommand(command, cwd, this.getConfiguredShellPath());
+
+    child.unref();
+
+    const managed: ManagedProcess = {
+      id,
+      name,
+      pid: child.pid ?? -1,
+      command,
+      cwd,
+      startTime: Date.now(),
+      endTime: null,
+      status: "running",
+      exitCode: null,
+      success: null,
+      stdoutFile,
+      stderrFile,
+      lastSignalSent: null,
+      combinedFile,
+      triggerAgentTurnOnEnd: true,
+    };
+
+    this.processes.set(id, managed);
+
+    if (!child.pid) {
+      try {
+        appendFileSync(stderrFile, "Spawn error: missing pid\n");
+      } catch {
+        // Ignore
+      }
+      managed.exitCode = -1;
+      managed.success = false;
+      managed.endTime = Date.now();
+      this.transition(managed, "exited");
+      return this.toProcessInfo(managed);
+    }
+
+    child.stdout?.on("data", (data: Buffer) => {
+      try {
+        appendFileSync(stdoutFile, data);
+        const lines = data.toString().split("\n");
+        // The last element after split is either empty (if data ended with \n)
+        // or a partial line. We write all parts with the prefix and newline.
+        const tagged = lines
+          .map((line, i) =>
+            i < lines.length - 1 ? `1:${line}\n` : line ? `1:${line}\n` : "",
+          )
+          .join("");
+        if (tagged) appendFileSync(combinedFile, tagged);
+      } catch {
+        // Ignore
+      }
+    });
+
+    child.stderr?.on("data", (data: Buffer) => {
+      try {
+        appendFileSync(stderrFile, data);
+        const lines = data.toString().split("\n");
+        const tagged = lines
+          .map((line, i) =>
+            i < lines.length - 1 ? `2:${line}\n` : line ? `2:${line}\n` : "",
+          )
+          .join("");
+        if (tagged) appendFileSync(combinedFile, tagged);
+      } catch {
+        // Ignore
+      }
+    });
+
+    child.on("close", (code, signal) => {
+      if (managed.endTime) return;
+
+      managed.exitCode = code;
+      managed.endTime = Date.now();
+      managed.success = code === 0;
+
+      if (signal) {
+        this.transition(managed, "killed");
+      } else {
+        this.transition(managed, "exited");
+      }
+    });
+
+    child.on("error", (err) => {
+      try {
+        appendFileSync(stderrFile, `Process error: ${err.message}\n`);
+      } catch {
+        // Ignore
+      }
+
+      if (!managed.endTime) {
+        managed.exitCode = -1;
+        managed.success = false;
+        managed.endTime = Date.now();
+        this.transition(managed, "exited");
+      }
+    });
+
+    this.emit({ type: "process_started", info: this.toProcessInfo(managed) });
+    this.ensureWatcherRunning();
+
+    return this.toProcessInfo(managed);
+  }
+
+  list(): ProcessInfo[] {
+    return Array.from(this.processes.values())
+      .map((p) => this.toProcessInfo(p))
+      .reverse();
+  }
+
+  get(id: string): ProcessInfo | null {
+    const managed = this.processes.get(id);
+    return managed ? this.toProcessInfo(managed) : null;
+  }
+
+  resolve(query: string): ResolveProcessResult {
+    const byId = this.processes.get(query);
+    if (byId) {
+      return { ok: true, info: this.toProcessInfo(byId) };
+    }
+
+    const queryLower = query.toLowerCase();
+    const matches = Array.from(this.processes.values())
+      .filter((managed) => managed.name.toLowerCase() === queryLower)
+      .map((managed) => this.toProcessInfo(managed));
+
+    if (matches.length === 1) {
+      return { ok: true, info: matches[0] };
+    }
+
+    if (matches.length > 1) {
+      return { ok: false, reason: "ambiguous", matches };
+    }
+
+    return { ok: false, reason: "not_found" };
+  }
+
+  getOutput(
+    id: string,
+    tailLines = 100,
+  ): { stdout: string[]; stderr: string[]; status: string } | null {
+    const managed = this.processes.get(id);
+    if (!managed) return null;
+
+    return {
+      stdout: this.readTailLines(managed.stdoutFile, tailLines),
+      stderr: this.readTailLines(managed.stderrFile, tailLines),
+      status: managed.status,
+    };
+  }
+
+  getCombinedOutput(
+    id: string,
+    tailLines = 100,
+  ): { type: "stdout" | "stderr"; text: string }[] | null {
+    const managed = this.processes.get(id);
+    if (!managed) return null;
+
+    const rawLines = this.readTailLines(managed.combinedFile, tailLines);
+    return rawLines.map((line) => {
+      if (line.startsWith("2:")) {
+        return { type: "stderr", text: line.slice(2) };
+      }
+      // Default to stdout (handles "1:" prefix and any malformed lines).
+      return {
+        type: "stdout",
+        text: line.startsWith("1:") ? line.slice(2) : line,
+      };
+    });
+  }
+
+  getFullOutput(id: string): { stdout: string; stderr: string } | null {
+    const managed = this.processes.get(id);
+    if (!managed) return null;
+
+    try {
+      return {
+        stdout: readFileSync(managed.stdoutFile, "utf-8"),
+        stderr: readFileSync(managed.stderrFile, "utf-8"),
+      };
+    } catch {
+      return { stdout: "", stderr: "" };
+    }
+  }
+
+  getLogFiles(
+    id: string,
+  ): { stdoutFile: string; stderrFile: string; combinedFile: string } | null {
+    const managed = this.processes.get(id);
+    if (!managed) return null;
+    return {
+      stdoutFile: managed.stdoutFile,
+      stderrFile: managed.stderrFile,
+      combinedFile: managed.combinedFile,
+    };
+  }
+
+  async kill(
+    id: string,
+    opts?: {
+      signal?: NodeJS.Signals;
+      timeoutMs?: number;
+      notifyOnEnd?: boolean;
+    },
+  ): Promise<KillResult> {
+    const managed = this.processes.get(id);
+    if (!managed) {
+      return {
+        ok: false,
+        info: {
+          id,
+          name: "(unknown)",
+          pid: -1,
+          command: "",
+          cwd: "",
+          startTime: 0,
+          endTime: null,
+          status: "exited",
+          exitCode: null,
+          success: false,
+          stdoutFile: "",
+          stderrFile: "",
+        },
+        reason: "not_found",
+      };
+    }
+
+    const signal = opts?.signal ?? "SIGTERM";
+    const timeoutMs = opts?.timeoutMs ?? 3000;
+
+    managed.triggerAgentTurnOnEnd = opts?.notifyOnEnd === true;
+
+    if (!LIVE_STATUSES.has(managed.status)) {
+      return { ok: true, info: this.toProcessInfo(managed) };
+    }
+
+    this.transition(managed, "terminating");
+
+    try {
+      killProcessGroup(managed.pid, signal);
+      managed.lastSignalSent = signal;
+    } catch (error) {
+      const err = error as NodeJS.ErrnoException;
+      if (err.code === "ESRCH") {
+        managed.lastSignalSent = signal;
+      } else if (err.code !== "EPERM") {
+        return {
+          ok: false,
+          info: this.toProcessInfo(managed),
+          reason: "error",
+        };
+      }
+    }
+
+    const graceMs = signal === "SIGKILL" ? 200 : timeoutMs;
+
+    await new Promise((r) => setTimeout(r, graceMs));
+
+    const alive = isProcessGroupAlive(managed.pid);
+
+    if (alive) {
+      this.transition(managed, "terminate_timeout");
+      return {
+        ok: false,
+        info: this.toProcessInfo(managed),
+        reason: "timeout",
+      };
+    }
+
+    if (!managed.endTime) {
+      managed.endTime = Date.now();
+      managed.exitCode = null;
+      managed.success = false;
+    }
+
+    this.transition(managed, "killed");
+    return { ok: true, info: this.toProcessInfo(managed) };
+  }
+
+  clearFinished(): number {
+    let cleared = 0;
+    for (const [id, managed] of this.processes) {
+      if (LIVE_STATUSES.has(managed.status)) {
+        continue;
+      }
+
+      try {
+        rmSync(managed.stdoutFile, { force: true });
+        rmSync(managed.stderrFile, { force: true });
+        rmSync(managed.combinedFile, { force: true });
+      } catch {
+        // Ignore
+      }
+
+      this.processes.delete(id);
+      cleared++;
+    }
+
+    if (cleared > 0) {
+      this.emit({ type: "processes_changed" });
+    }
+
+    this.stopWatcherIfIdle();
+    return cleared;
+  }
+
+  private shutdownKillAll(): void {
+    for (const p of this.processes.values()) {
+      if (!LIVE_STATUSES.has(p.status)) continue;
+      try {
+        killProcessGroup(p.pid, "SIGKILL");
+      } catch {
+        // Ignore - process may already be dead
+      }
+    }
+  }
+
+  private stopWatcher(): void {
+    if (this.watcher) {
+      clearInterval(this.watcher);
+      this.watcher = null;
+    }
+  }
+
+  cleanup(): void {
+    this.stopWatcher();
+    this.shutdownKillAll();
+
+    try {
+      rmSync(this.logDir, { recursive: true, force: true });
+    } catch {
+      // Ignore
+    }
+  }
+
+  getFileSize(id: string): { stdout: number; stderr: number } | null {
+    const managed = this.processes.get(id);
+    if (!managed) return null;
+
+    try {
+      return {
+        stdout: statSync(managed.stdoutFile).size,
+        stderr: statSync(managed.stderrFile).size,
+      };
+    } catch {
+      return { stdout: 0, stderr: 0 };
+    }
+  }
+
+  private readTailLines(filePath: string, lines: number): string[] {
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      const allLines = content.split("\n");
+      if (allLines.length > 0 && allLines[allLines.length - 1] === "") {
+        allLines.pop();
+      }
+      return allLines.slice(-lines);
+    } catch {
+      return [];
+    }
+  }
+
+  private toProcessInfo(managed: ManagedProcess): ProcessInfo {
+    return {
+      id: managed.id,
+      name: managed.name,
+      pid: managed.pid,
+      command: managed.command,
+      cwd: managed.cwd,
+      startTime: managed.startTime,
+      endTime: managed.endTime,
+      status: managed.status,
+      exitCode: managed.exitCode,
+      success: managed.success,
+      stdoutFile: managed.stdoutFile,
+      stderrFile: managed.stderrFile,
+    };
+  }
+}
+
+export type { ProcessInfo, ProcessStatus, ManagerEvent, KillResult };

package/src/tools/actions/clear.ts

@@ -0,0 +1,20 @@
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+
+export function executeClear(manager: ProcessManager): ExecuteResult {
+  const cleared = manager.clearFinished();
+  const message =
+    cleared > 0
+      ? `Cleared ${cleared} finished process(es)`
+      : "No finished processes to clear";
+
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "clear",
+      success: true,
+      message,
+      cleared,
+    },
+  };
+}

package/src/tools/actions/index.ts

@@ -0,0 +1,48 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { executeClear } from "./clear";
+import { executeKill } from "./kill";
+import { executeList } from "./list";
+import { executeLogs } from "./logs";
+import { executeOutput } from "./output";
+import { executeStart } from "./start";
+
+interface ActionParams {
+  action: string;
+  command?: string;
+  name?: string;
+  id?: string;
+  force?: boolean;
+  continueAfterStart?: boolean;
+}
+
+export async function executeAction(
+  params: ActionParams,
+  manager: ProcessManager,
+  ctx: ExtensionContext,
+): Promise<ExecuteResult> {
+  switch (params.action) {
+    case "start":
+      return executeStart(params, manager, ctx);
+    case "list":
+      return executeList(manager);
+    case "output":
+      return executeOutput(params, manager);
+    case "logs":
+      return executeLogs(params, manager);
+    case "kill":
+      return executeKill(params, manager);
+    case "clear":
+      return executeClear(manager);
+    default:
+      return {
+        content: [{ type: "text", text: `Unknown action: ${params.action}` }],
+        details: {
+          action: params.action,
+          success: false,
+          message: `Unknown action: ${params.action}`,
+        },
+      };
+  }
+}

package/src/tools/actions/kill.ts

@@ -0,0 +1,107 @@
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+
+interface KillParams {
+  id?: string;
+  force?: boolean;
+}
+
+function notFoundResult(id: string): ExecuteResult {
+  const message = `Process not found: ${id}`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "kill",
+      success: false,
+      message,
+    },
+  };
+}
+
+function ambiguousResult(
+  id: string,
+  matches: Array<{ id: string; name: string }>,
+): ExecuteResult {
+  const choices = matches
+    .map((match) => `${match.id} ("${match.name}")`)
+    .join(", ");
+  const message =
+    `Process name is ambiguous: ${id}. ` +
+    `Use an exact process ID instead. Matches: ${choices}`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "kill",
+      success: false,
+      message,
+    },
+  };
+}
+
+export async function executeKill(
+  params: KillParams,
+  manager: ProcessManager,
+): Promise<ExecuteResult> {
+  if (!params.id) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: id" }],
+      details: {
+        action: "kill",
+        success: false,
+        message: "Missing required parameter: id",
+      },
+    };
+  }
+
+  const resolved = manager.resolve(params.id);
+  if (!resolved.ok) {
+    return resolved.reason === "ambiguous"
+      ? ambiguousResult(params.id, resolved.matches ?? [])
+      : notFoundResult(params.id);
+  }
+
+  const proc = resolved.info;
+  const force = params.force ?? false;
+  const signal = force ? "SIGKILL" : "SIGTERM";
+  const timeoutMs = force ? 200 : 3000;
+  const result = await manager.kill(proc.id, { signal, timeoutMs });
+
+  if (result.ok) {
+    const verb = force ? "Force-killed" : "Terminated";
+    const message = `${verb} "${proc.name}" (${proc.id})`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "kill",
+        success: true,
+        message,
+      },
+    };
+  }
+
+  if (result.reason === "timeout") {
+    const message = force
+      ? `SIGKILL timed out for "${proc.name}" (${proc.id})`
+      : `SIGTERM timed out for "${proc.name}" (${proc.id}). Re-run process kill with id="${proc.id}" force=true to send SIGKILL.`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "kill",
+        success: false,
+        message,
+      },
+    };
+  }
+
+  const message = force
+    ? `Failed to force-kill "${proc.name}" (${proc.id})`
+    : `Failed to terminate "${proc.name}" (${proc.id})`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "kill",
+      success: false,
+      message,
+    },
+  };
+}