@aliou/pi-processes 0.4.5 → 0.4.6

package/src/tools/actions/kill.ts

@@ -0,0 +1,76 @@
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+
+interface KillParams {
+  id?: string;
+}
+
+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 proc = manager.find(params.id);
+  if (!proc) {
+    const message = `Process not found: ${params.id}`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "kill",
+        success: false,
+        message,
+      },
+    };
+  }
+
+  const result = await manager.kill(proc.id, {
+    signal: "SIGTERM",
+    timeoutMs: 3000,
+  });
+
+  if (result.ok) {
+    const message = `Terminated "${proc.name}" (${proc.id})`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "kill",
+        success: true,
+        message,
+      },
+    };
+  }
+
+  if (result.reason === "timeout") {
+    const message =
+      `SIGTERM timed out for "${proc.name}" (${proc.id}). ` +
+      "Run /process:list and press x on terminate_timeout to force kill (SIGKILL).";
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "kill",
+        success: false,
+        message,
+      },
+    };
+  }
+
+  const message = `Failed to terminate "${proc.name}" (${proc.id})`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "kill",
+      success: false,
+      message,
+    },
+  };
+}

package/src/tools/actions/list.ts

@@ -0,0 +1,37 @@
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { formatRuntime, formatStatus, truncateCmd } from "../../utils";
+
+export function executeList(manager: ProcessManager): ExecuteResult {
+  const processes = manager.list();
+
+  if (processes.length === 0) {
+    return {
+      content: [{ type: "text", text: "No background processes running" }],
+      details: {
+        action: "list",
+        success: true,
+        message: "No background processes running",
+        processes: [],
+      },
+    };
+  }
+
+  const summary = processes
+    .map(
+      (p) =>
+        `${p.id} "${p.name}": ${truncateCmd(p.command)} [${formatStatus(p)}] ${formatRuntime(p.startTime, p.endTime)}`,
+    )
+    .join("\n");
+
+  const message = `${processes.length} process(es):\n${summary}`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "list",
+      success: true,
+      message,
+      processes,
+    },
+  };
+}

package/src/tools/actions/logs.ts

@@ -0,0 +1,59 @@
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+
+interface LogsParams {
+  id?: string;
+}
+
+export function executeLogs(
+  params: LogsParams,
+  manager: ProcessManager,
+): ExecuteResult {
+  if (!params.id) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: id" }],
+      details: {
+        action: "logs",
+        success: false,
+        message: "Missing required parameter: id",
+      },
+    };
+  }
+
+  const proc = manager.find(params.id);
+  if (!proc) {
+    const message = `Process not found: ${params.id}`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "logs",
+        success: false,
+        message,
+      },
+    };
+  }
+
+  const logFiles = manager.getLogFiles(proc.id);
+  if (!logFiles) {
+    const message = `Could not get log files for: ${proc.id}`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "logs",
+        success: false,
+        message,
+      },
+    };
+  }
+
+  const message = `Log files for "${proc.name}" (${proc.id}):\n  stdout: ${logFiles.stdoutFile}\n  stderr: ${logFiles.stderrFile}\n\nUse the read tool to inspect these files.`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "logs",
+      success: true,
+      message,
+      logFiles,
+    },
+  };
+}

package/src/tools/actions/output.ts

@@ -0,0 +1,144 @@
+import { configLoader } from "../../config";
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { formatStatus, stripAnsi } from "../../utils";
+
+const MAX_BYTES = 50 * 1024; // 50KB
+
+interface OutputParams {
+  id?: string;
+}
+
+export function executeOutput(
+  params: OutputParams,
+  manager: ProcessManager,
+): ExecuteResult {
+  if (!params.id) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: id" }],
+      details: {
+        action: "output",
+        success: false,
+        message: "Missing required parameter: id",
+      },
+    };
+  }
+
+  const proc = manager.find(params.id);
+  if (!proc) {
+    const message = `Process not found: ${params.id}`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "output",
+        success: false,
+        message,
+      },
+    };
+  }
+
+  const { defaultTailLines } = configLoader.getConfig().output;
+  const output = manager.getOutput(proc.id, defaultTailLines);
+  if (!output) {
+    const message = `Could not read output for: ${proc.id}`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "output",
+        success: false,
+        message,
+      },
+    };
+  }
+
+  const logFiles = manager.getLogFiles(proc.id);
+  const stdoutLines = output.stdout.length;
+  const stderrLines = output.stderr.length;
+  const message = `"${proc.name}" (${proc.id}) [${formatStatus(proc)}]: ${stdoutLines} stdout lines, ${stderrLines} stderr lines`;
+
+  // Build the full text content (ANSI-stripped), then truncate from the tail
+  // like bash does, so the agent sees the most recent output.
+  const outputParts: string[] = [message];
+  if (output.stdout.length > 0) {
+    outputParts.push("\nstdout:");
+    outputParts.push(...output.stdout.map(stripAnsi));
+  }
+  if (output.stderr.length > 0) {
+    outputParts.push("\nstderr:");
+    outputParts.push(...output.stderr.map(stripAnsi));
+  }
+
+  const fullText = outputParts.join("\n");
+  const { maxOutputLines } = configLoader.getConfig().output;
+  const contentText = truncateTail(fullText, logFiles, maxOutputLines);
+
+  return {
+    content: [{ type: "text", text: contentText }],
+    details: {
+      action: "output",
+      success: true,
+      message,
+      output,
+    },
+  };
+}
+
+/**
+ * Truncate text from the tail (keep last N lines / MAX_BYTES), matching
+ * the behaviour of pi's built-in bash tool.  When truncated, appends a
+ * notice pointing the agent to the full log files.
+ */
+function truncateTail(
+  text: string,
+  logFiles: { stdoutFile: string; stderrFile: string } | null,
+  maxLines: number,
+): string {
+  const totalBytes = Buffer.byteLength(text, "utf-8");
+  const lines = text.split("\n");
+  const totalLines = lines.length;
+
+  if (totalLines <= maxLines && totalBytes <= MAX_BYTES) {
+    return text;
+  }
+
+  // Work backwards, collecting lines that fit
+  const kept: string[] = [];
+  let keptBytes = 0;
+  let hitBytes = false;
+
+  for (let i = lines.length - 1; i >= 0 && kept.length < maxLines; i--) {
+    const line = lines[i] ?? "";
+    const lineBytes =
+      Buffer.byteLength(line, "utf-8") + (kept.length > 0 ? 1 : 0);
+
+    if (keptBytes + lineBytes > MAX_BYTES) {
+      hitBytes = true;
+      break;
+    }
+
+    kept.unshift(line);
+    keptBytes += lineBytes;
+  }
+
+  let result = kept.join("\n");
+
+  // Append a notice so the agent knows output was truncated
+  const shownLines = kept.length;
+  const startLine = totalLines - shownLines + 1;
+  const sizeNote = hitBytes ? ` (${formatSize(MAX_BYTES)} limit)` : "";
+  result += `\n\n[Showing lines ${startLine}-${totalLines} of ${totalLines}${sizeNote}.`;
+
+  if (logFiles) {
+    result += ` Full logs: ${logFiles.stdoutFile} , ${logFiles.stderrFile}`;
+  }
+
+  result += "]";
+
+  return result;
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/src/tools/actions/start.ts

@@ -0,0 +1,55 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+
+interface StartParams {
+  name?: string;
+  command?: string;
+  alertOnSuccess?: boolean;
+  alertOnFailure?: boolean;
+  alertOnKill?: boolean;
+}
+
+export function executeStart(
+  params: StartParams,
+  manager: ProcessManager,
+  ctx: ExtensionContext,
+): ExecuteResult {
+  if (!params.name) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: name" }],
+      details: {
+        action: "start",
+        success: false,
+        message: "Missing required parameter: name",
+      },
+    };
+  }
+  if (!params.command) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: command" }],
+      details: {
+        action: "start",
+        success: false,
+        message: "Missing required parameter: command",
+      },
+    };
+  }
+
+  const proc = manager.start(params.name, params.command, ctx.cwd, {
+    alertOnSuccess: params.alertOnSuccess,
+    alertOnFailure: params.alertOnFailure,
+    alertOnKill: params.alertOnKill,
+  });
+
+  const message = `Started "${proc.name}" (${proc.id}, PID: ${proc.pid})\nLogs: ${proc.stdoutFile}`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "start",
+      success: true,
+      message,
+      process: proc,
+    },
+  };
+}

package/src/tools/index.ts

@@ -0,0 +1,280 @@
+import { ToolBody, ToolCallHeader, ToolFooter } from "@aliou/pi-utils-ui";
+import { StringEnum } from "@mariozechner/pi-ai";
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  Theme,
+  ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { type Static, Type } from "@sinclair/typebox";
+import type { ProcessesDetails } from "../constants";
+import type { ProcessManager } from "../manager";
+import { formatRuntime, hasAnsi, stripAnsi, truncateCmd } from "../utils";
+import { executeAction } from "./actions";
+
+const ProcessesParams = Type.Object({
+  action: StringEnum(
+    ["start", "list", "output", "logs", "kill", "clear"] as const,
+    {
+      description:
+        "Action: start (run command), list (show all), output (get recent output), logs (get log file paths), kill (terminate), clear (remove finished)",
+    },
+  ),
+  command: Type.Optional(
+    Type.String({ description: "Command to run (required for start)" }),
+  ),
+  name: Type.Optional(
+    Type.String({
+      description:
+        "Friendly name for the process (required for start, e.g. 'backend-dev', 'test-runner')",
+    }),
+  ),
+  id: Type.Optional(
+    Type.String({
+      description:
+        "Process ID or name to match (required for output/kill/logs). Can be proc_N or friendly name.",
+    }),
+  ),
+  alertOnSuccess: Type.Optional(
+    Type.Boolean({
+      description:
+        "Get a turn to react when process completes successfully (default: false). Use for builds/tests where you need confirmation.",
+    }),
+  ),
+  alertOnFailure: Type.Optional(
+    Type.Boolean({
+      description:
+        "Get a turn to react when process fails/crashes (default: true). Use to be alerted of unexpected failures.",
+    }),
+  ),
+  alertOnKill: Type.Optional(
+    Type.Boolean({
+      description:
+        "Get a turn to react when process is killed by external signal (default: false). Note: killing via tool never triggers a turn.",
+    }),
+  ),
+});
+
+type ProcessesParamsType = Static<typeof ProcessesParams>;
+
+export function setupProcessesTools(pi: ExtensionAPI, manager: ProcessManager) {
+  pi.registerTool<typeof ProcessesParams, ProcessesDetails>({
+    name: "process",
+    label: "Process",
+    description: `Manage background processes. Actions:
+- start: Run command in background (requires 'name' and 'command')
+  - alertOnSuccess (default: false): Get a turn to react when process completes successfully
+  - alertOnFailure (default: true): Get a turn to react when process crashes/fails
+  - alertOnKill (default: false): Get a turn to react if killed by external signal (killing via tool never triggers a turn)
+- list: Show all managed processes with their IDs and names
+- output: Get recent stdout/stderr (requires 'id' - can be proc_N or name match)
+- logs: Get log file paths to inspect with read tool (requires 'id')
+- kill: Terminate a process (requires 'id' - can be proc_N or name match like "backend")
+- clear: Remove all finished processes from the list
+
+Important: You DON'T need to poll or wait for processes. Notifications arrive automatically based on your preferences. Start processes and continue with other work - you'll be informed if something requires attention.
+
+Note: User always sees process updates in the UI. The notify flags control whether YOU (the agent) get a turn to react (e.g. check results, fix code, restart).`,
+
+    parameters: ProcessesParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      return executeAction(params, manager, ctx);
+    },
+
+    renderCall(args: ProcessesParamsType, theme: Theme) {
+      const longArgs: Array<{ label?: string; value: string }> = [];
+      const optionArgs: Array<{ label: string; value: string }> = [];
+      let mainArg: string | undefined;
+
+      if (args.action === "start") {
+        if (args.name) {
+          mainArg = `"${args.name}"`;
+        }
+
+        if (args.command) {
+          if (!mainArg && args.command.length <= 60) {
+            mainArg = args.command;
+          } else if (args.command.length <= 60) {
+            optionArgs.push({ label: "command", value: args.command });
+          } else {
+            longArgs.push({ label: "command", value: args.command });
+          }
+        }
+      }
+
+      if (
+        (args.action === "output" ||
+          args.action === "kill" ||
+          args.action === "logs") &&
+        args.id
+      ) {
+        mainArg = args.id;
+      }
+
+      return new ToolCallHeader(
+        {
+          toolName: "Process",
+          action: args.action,
+          mainArg,
+          optionArgs,
+          longArgs,
+        },
+        theme,
+      );
+    },
+
+    renderResult(
+      result: AgentToolResult<ProcessesDetails>,
+      options: ToolRenderResultOptions,
+      theme: Theme,
+    ) {
+      const { details } = result;
+
+      if (!details) {
+        const text = result.content[0];
+        return new Text(
+          text?.type === "text" && text.text ? text.text : "No result",
+          0,
+          0,
+        );
+      }
+
+      const fields: Array<
+        { label: string; value: string; showCollapsed?: boolean } | Text
+      > = [];
+
+      if (!details.success) {
+        fields.push({
+          label: "Error",
+          value: theme.fg("error", details.message),
+          showCollapsed: true,
+        });
+      } else if (details.action === "start" && details.process) {
+        const process = details.process;
+        fields.push({
+          label: "Status",
+          value:
+            theme.fg("success", "Started") +
+            ` ${theme.fg("accent", `"${process.name}"`)} (${process.id}, PID: ${process.pid})`,
+          showCollapsed: true,
+        });
+      } else if (details.action === "output" && details.output) {
+        const lines: string[] = [theme.fg("muted", details.message)];
+        let hadAnsi = false;
+
+        if (details.output.stdout.length > 0) {
+          lines.push("", theme.fg("accent", "stdout:"));
+          for (const line of details.output.stdout.slice(-20)) {
+            if (!hadAnsi && hasAnsi(line)) hadAnsi = true;
+            lines.push(stripAnsi(line));
+          }
+          if (details.output.stdout.length > 20) {
+            lines.push(
+              theme.fg(
+                "muted",
+                `... (${details.output.stdout.length - 20} more lines)`,
+              ),
+            );
+          }
+        }
+
+        if (details.output.stderr.length > 0) {
+          lines.push("", theme.fg("warning", "stderr:"));
+          for (const line of details.output.stderr.slice(-10)) {
+            if (!hadAnsi && hasAnsi(line)) hadAnsi = true;
+            lines.push(theme.fg("warning", stripAnsi(line)));
+          }
+          if (details.output.stderr.length > 10) {
+            lines.push(
+              theme.fg(
+                "muted",
+                `... (${details.output.stderr.length - 10} more lines)`,
+              ),
+            );
+          }
+        }
+
+        if (hadAnsi) {
+          lines.push(
+            "",
+            theme.fg("muted", "ANSI escape codes were stripped from output"),
+          );
+        }
+
+        fields.push(new Text(lines.join("\n"), 0, 0));
+      } else if (
+        details.action === "list" &&
+        details.processes &&
+        details.processes.length > 0
+      ) {
+        const lines: string[] = [
+          theme.fg("success", `${details.processes.length} process(es):`),
+        ];
+
+        for (const process of details.processes) {
+          let status: string;
+          switch (process.status) {
+            case "running":
+              status = theme.fg("accent", "running");
+              break;
+            case "terminating":
+              status = theme.fg("warning", "terminating");
+              break;
+            case "terminate_timeout":
+              status = theme.fg("error", "terminate_timeout");
+              break;
+            case "killed":
+              status = theme.fg("warning", "killed");
+              break;
+            case "exited":
+              status = process.success
+                ? theme.fg("success", "exit(0)")
+                : theme.fg("error", `exit(${process.exitCode ?? "?"})`);
+              break;
+            default:
+              status = theme.fg("muted", process.status);
+          }
+
+          lines.push(
+            `  ${process.id} ${theme.fg("accent", `"${process.name}"`)}: ${truncateCmd(process.command)} [${status}] ${formatRuntime(process.startTime, process.endTime)}`,
+          );
+        }
+
+        fields.push(new Text(lines.join("\n"), 0, 0));
+      } else if (details.action === "logs" && details.logFiles) {
+        fields.push(
+          new Text(
+            [
+              theme.fg("success", "Log files:"),
+              `  stdout: ${theme.fg("accent", details.logFiles.stdoutFile)}`,
+              `  stderr: ${theme.fg("accent", details.logFiles.stderrFile)}`,
+            ].join("\n"),
+            0,
+            0,
+          ),
+        );
+      } else {
+        fields.push({
+          label: "Result",
+          value: details.message,
+          showCollapsed: true,
+        });
+      }
+
+      const footer = new ToolFooter(theme, {
+        items: [
+          { label: "action", value: details.action, tone: "accent" },
+          {
+            label: "status",
+            value: details.success ? "ok" : "error",
+            tone: details.success ? "success" : "error",
+          },
+        ],
+      });
+
+      return new ToolBody({ fields, footer }, options, theme);
+    },
+  });
+}

package/src/utils/ansi.ts

@@ -0,0 +1,36 @@
+/**
+ * Strip ANSI escape codes from a string.
+ *
+ * Removes:
+ * - All CSI sequences (\x1b[...X) - SGR, cursor movement, erase, scroll, etc.
+ * - OSC 8 hyperlinks (\x1b]8;;URL\x07)
+ * - APC sequences (\x1b_...\x07 or \x1b_...\x1b\\)
+ */
+/**
+ * Check if a string contains ANSI escape codes.
+ */
+export function hasAnsi(str: string): boolean {
+  return str.includes(String.fromCodePoint(0x001b));
+}
+
+export function stripAnsi(str: string): string {
+  // ESC = \u001b, BEL = \u0007
+  const ESC = String.fromCodePoint(0x001b);
+  const BEL = String.fromCodePoint(0x0007);
+
+  if (!str.includes(ESC)) {
+    return str;
+  }
+
+  // Strip all CSI sequences (ESC[...X where X is any letter)
+  let clean = str.replace(new RegExp(`${ESC}\\[[0-9;]*[A-Za-z]`, "gu"), "");
+  // Strip OSC 8 hyperlinks: ESC]8;;URL<BEL> and ESC]8;;<BEL>
+  clean = clean.replace(new RegExp(`${ESC}\\]8;;[^${BEL}]*${BEL}`, "gu"), "");
+  // Strip APC sequences: ESC_...<BEL> or ESC_...<ESC>\\ (used for cursor marker)
+  clean = clean.replace(
+    new RegExp(`${ESC}_[^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "gu"),
+    "",
+  );
+
+  return clean;
+}