@aliou/pi-processes 0.6.3 → 0.7.0

package/src/tools/index.ts

@@ -1,4 +1,4 @@
-import { ToolBody, ToolCallHeader, ToolFooter } from "@aliou/pi-utils-ui";
+import { ToolBody } from "@aliou/pi-utils-ui";
 import { StringEnum } from "@mariozechner/pi-ai";
 import type {
   AgentToolResult,
@@ -10,17 +10,27 @@ 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";
+import { executeAction, renderActionCall, renderActionResult } from "./actions";
+
+const DEBUG_PREVIEW_ENABLED = process.env.PI_PROCESSES_DEBUG_PREVIEW === "1";
+
+const PROCESS_ACTIONS = [
+  "start",
+  "list",
+  "output",
+  "logs",
+  "kill",
+  "clear",
+  "write",
+  ...(DEBUG_PREVIEW_ENABLED ? (["debug_preview"] as const) : []),
+] as const;
 
 const ProcessesParams = Type.Object({
-  action: StringEnum(
-    ["start", "list", "output", "logs", "kill", "clear", "write"] as const,
-    {
-      description:
-        "Action: start (run command), list (show all), output (get recent output), logs (get log file paths), kill (terminate), clear (remove finished), write (write to stdin)",
-    },
-  ),
+  action: StringEnum(PROCESS_ACTIONS, {
+    description: DEBUG_PREVIEW_ENABLED
+      ? "Action: start (run command), list (show all), output (get recent output), logs (get log file paths), kill (terminate), clear (remove finished), write (write to stdin), debug_preview (temporary UI preview, no side effects)"
+      : "Action: start (run command), list (show all), output (get recent output), logs (get log file paths), kill (terminate), clear (remove finished), write (write to stdin)",
+  }),
   command: Type.Optional(
     Type.String({ description: "Command to run (required for start)" }),
   ),
@@ -33,7 +43,7 @@ const ProcessesParams = Type.Object({
   id: Type.Optional(
     Type.String({
       description:
-        "Process ID or name to match (required for output/kill/logs/write). Can be proc_N or friendly name.",
+        "Process ID, returned by start and list actions (required for output/kill/logs/write)",
     }),
   ),
   input: Type.Optional(
@@ -65,6 +75,41 @@ const ProcessesParams = Type.Object({
         "Get a turn to react when process is killed by external signal (default: false). Note: killing via tool never triggers a turn.",
     }),
   ),
+  ...(DEBUG_PREVIEW_ENABLED
+    ? {
+        preview: Type.Optional(
+          StringEnum(["start", "list", "output", "logs", "error"] as const, {
+            description:
+              "For action=debug_preview only: which rendered result variant to preview (default: start)",
+          }),
+        ),
+      }
+    : {}),
+  logWatches: Type.Optional(
+    Type.Array(
+      Type.Object(
+        {
+          pattern: Type.String({
+            description:
+              "Regular expression pattern to match against process output lines",
+          }),
+          stream: Type.Optional(
+            StringEnum(["stdout", "stderr", "both"] as const, {
+              description:
+                "Which stream to watch (default: both). Use stdout/stderr to reduce noise.",
+            }),
+          ),
+          repeat: Type.Optional(
+            Type.Boolean({
+              description:
+                "Trigger every time this pattern matches (default: false, one-time)",
+            }),
+          ),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+  ),
 });
 
 type ProcessesParamsType = Static<typeof ProcessesParams>;
@@ -78,16 +123,32 @@ export function setupProcessesTools(pi: ExtensionAPI, manager: ProcessManager) {
   - 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)
+  - logWatches (optional): Runtime output watches that trigger immediate alerts while running
+    - pattern: regex string to match per output line
+    - stream: stdout | stderr | both (default both)
+    - repeat: false by default (single-fire). Set true for repeat alerts
 - list: Show all managed processes with their IDs and names
-- output: Get recent stdout/stderr (requires 'id' - can be proc_N or name match)
+- output: Get recent stdout/stderr (requires 'id')
 - 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")
+- kill: Terminate a process (requires 'id')
 - clear: Remove all finished processes from the list
 - write: Write to process stdin (requires 'id' and 'input', optional 'end' to close stdin)
-
+${
+  DEBUG_PREVIEW_ENABLED
+    ? "- debug_preview: Temporary renderer preview for process tool UIs (no process side effects)\n  - preview: start | list | output | logs | error (default: start)\n"
+    : ""
+}
 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).`,
+    promptSnippet:
+      "Manage background processes without blocking the conversation",
+    promptGuidelines: [
+      "Use this tool for long-running commands such as dev servers, test watchers, build watchers, and log tails instead of bash.",
+      "Avoid shell background patterns such as &, nohup, disown, or setsid when the process tool fits.",
+      "After starting a process, continue other work instead of waiting for it.",
+      "Use the pi-processes skill for examples and best practices when a task depends on background processes.",
+    ],
 
     parameters: ProcessesParams,
 
@@ -96,53 +157,7 @@ Note: User always sees process updates in the UI. The notify flags control wheth
     },
 
     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.action === "write") &&
-        args.id
-      ) {
-        mainArg = args.id;
-      }
-
-      if (args.action === "write" && args.input) {
-        optionArgs.push({ label: "input", value: args.input });
-        if (args.end) {
-          optionArgs.push({ label: "end", value: "true" });
-        }
-      }
-
-      return new ToolCallHeader(
-        {
-          toolName: "Process",
-          action: args.action,
-          mainArg,
-          optionArgs,
-          longArgs,
-        },
-        theme,
-      );
+      return renderActionCall(args, theme);
     },
 
     renderResult(
@@ -150,199 +165,39 @@ Note: User always sees process updates in the UI. The notify flags control wheth
       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,
-        );
+      if (options.isPartial) {
+        return new Text(theme.fg("muted", "Process: running..."), 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));
-
-        // Collapsed summary
-        const previewSource =
-          details.output.stdout.length > 0
-            ? details.output.stdout
-            : details.output.stderr;
-        const preview = previewSource
-          .slice(-2)
-          .map((l) => stripAnsi(l))
-          .join("\n");
-        fields.push({
-          label: "Output",
-          value: preview
-            ? `${theme.fg("muted", preview)}`
-            : theme.fg("muted", "(empty)"),
-          showCollapsed: true,
-        });
-      } 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));
+      const { details } = result;
 
-        // Collapsed summary: first 3 processes
-        const summary = details.processes
-          .slice(0, 3)
-          .map((p) => {
-            const s =
-              p.status === "running"
-                ? theme.fg("accent", "running")
-                : p.status === "exited" && p.success
-                  ? theme.fg("success", "exit(0)")
-                  : p.status === "exited"
-                    ? theme.fg("error", `exit(${p.exitCode ?? "?"})`)
-                    : theme.fg("muted", p.status);
-            return `${theme.fg("accent", `"${p.name}"`)} [${s}]`;
-          })
-          .join(", ");
-        const more =
-          details.processes.length > 3
-            ? theme.fg("muted", ` +${details.processes.length - 3} more`)
-            : "";
-        fields.push({
-          label: "Processes",
-          value: summary + more,
-          showCollapsed: true,
-        });
-      } 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,
-        });
+      // Framework sets details to {} when tool throws.
+      // Detect by checking for missing expected fields.
+      if (!details?.action) {
+        const textBlock = result.content.find((c) => c.type === "text");
+        const errorMsg =
+          (textBlock?.type === "text" && textBlock.text) ||
+          "Tool execution failed";
+        return new Text(theme.fg("error", errorMsg), 0, 0);
       }
 
-      const footerItems: Array<{
-        label: string;
-        value: string;
-        tone: "accent" | "success" | "error" | "warning" | "muted";
-      }> = [];
       if (!details.success) {
-        footerItems.push({
-          label: "status",
-          value: "error",
-          tone: "error",
-        });
+        return new ToolBody(
+          {
+            fields: [
+              {
+                label: "Error",
+                value: theme.fg("error", details.message),
+                showCollapsed: true,
+              },
+            ],
+          },
+          options,
+          theme,
+        );
       }
-      const footer =
-        footerItems.length > 0
-          ? new ToolFooter(theme, { items: footerItems })
-          : undefined;
 
-      return new ToolBody({ fields, footer }, options, theme);
+      return renderActionResult(result, options, theme);
     },
   });
 }

package/src/utils/command-executor.ts

@@ -1,3 +1,6 @@
+// Uses node:child_process directly instead of pi.exec() because process
+// management requires long-lived streaming processes with stdin/stdout piping
+// and detached process groups, which pi.exec() does not support.
 import { type ChildProcess, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { isAbsolute } from "node:path";

package/src/utils/format.ts

@@ -1,3 +1,4 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
 import type { ProcessInfo } from "../constants";
 
 export function formatRuntime(
@@ -40,3 +41,34 @@ export function truncateCmd(cmd: string, max = 40): string {
   if (cmd.length <= max) return cmd;
   return `${cmd.slice(0, max - 3)}...`;
 }
+
+export function formatTimestamp(ts: number | null): string {
+  if (!ts) return "-";
+  return new Date(ts).toISOString().replace("T", " ").slice(0, 19);
+}
+
+export function formatStatusTag(
+  process: {
+    status: string;
+    success: boolean | null;
+    exitCode: number | null;
+  },
+  theme: Theme,
+): string {
+  switch (process.status) {
+    case "running":
+      return theme.fg("accent", "running");
+    case "terminating":
+      return theme.fg("warning", "terminating");
+    case "terminate_timeout":
+      return theme.fg("error", "terminate_timeout");
+    case "killed":
+      return theme.fg("warning", "killed");
+    case "exited":
+      return process.success
+        ? theme.fg("success", "exit(0)")
+        : theme.fg("error", `exit(${process.exitCode ?? "?"})`);
+    default:
+      return theme.fg("muted", process.status);
+  }
+}

package/src/utils/index.ts

@@ -1,3 +1,9 @@
 export { hasAnsi, stripAnsi } from "./ansi";
-export { formatRuntime, formatStatus, truncateCmd } from "./format";
+export {
+  formatRuntime,
+  formatStatus,
+  formatStatusTag,
+  formatTimestamp,
+  truncateCmd,
+} from "./format";
 export { isProcessGroupAlive, killProcessGroup } from "./process-group";