@aliou/pi-processes 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# Processes Extension
+
+Manage background processes from Pi. Start long-running commands (dev servers, build watchers, log tailers) without blocking the conversation.
+
+## Features
+
+- **Tool**: `processes` with actions: `start`, `list`, `output`, `logs`, `kill`, `clear`
+- **Command**: `/processes` - interactive panel to view and manage processes
+- Auto-cleanup on session exit
+- File-based logging (logs written to temp files, not memory)
+- Friendly process names (auto-inferred or custom)
+
+## Usage
+
+### Tool (for agent)
+
+```
+processes start "pnpm dev" name="backend-dev"
+processes start "pnpm build" name="build" notifyOnSuccess=true
+processes start "pnpm test" notifyOnFailure=true
+processes list
+processes output id="backend"
+processes logs id="proc_1"
+processes kill id="backend"
+processes clear
+```
+
+**Notification parameters** (for `start` action):
+- `notifyOnSuccess` (default: false) - Get notified when process completes successfully. Use for builds/tests where you need confirmation.
+- `notifyOnFailure` (default: true) - Get notified when process crashes/fails. Use to be alerted of unexpected failures.
+- `notifyOnKill` (default: false) - Get notified if killed by external signal. Note: killing via tool never notifies.
+
+**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 notifications in UI. Notification preferences only control whether the agent is informed.
+
+### Command (interactive)
+
+Run `/processes` to open the panel:
+- `j/k` - select process
+- `J/K` - scroll logs
+- `x` - kill selected process
+- `c` - clear finished processes
+- `q` - quit
+
+## Test Scripts
+
+Test scripts in `test/` directory:
+
+```bash
+./test/test-output.sh          # Continuous output (80 chars/sec)
+./test/test-exit-success.sh 5  # Exits successfully after 5s
+./test/test-exit-failure.sh 5  # Exits with code 1 after 5s
+./test/test-exit-crash.sh 5    # Exits with code 137 after 5s
+```
+
+## Future Improvements
+
+- [ ] **Expandable log view**: Allow toggling between collapsed (current fixed height) and expanded (full height) log view in the `/processes` panel.
+
+- [ ] **Copy log file path**: Add keyboard shortcut to copy the stdout/stderr log file path to clipboard for easy access.
+
+- [ ] **Open logs in editor**: Add keyboard shortcut to open log files directly in the configured editor (`$EDITOR` or VS Code).

package/commands/index.ts

@@ -0,0 +1,488 @@
+import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
+import { type Component, matchesKey, visibleWidth } from "@mariozechner/pi-tui";
+import type { ProcessInfo, ProcessManager } from "../manager";
+
+// Max visible processes in the list (scrollable if more)
+const MAX_VISIBLE_PROCESSES = 8;
+// Max log lines shown
+const MAX_LOG_LINES = 12;
+
+function formatRuntime(startTime: number, endTime: number | null): string {
+  const end = endTime ?? Date.now();
+  const ms = end - startTime;
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  }
+  return `${seconds}s`;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes >= 1024 * 1024) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+  }
+  if (bytes >= 1024) {
+    return `${(bytes / 1024).toFixed(1)}KB`;
+  }
+  return `${bytes}B`;
+}
+
+function truncate(str: string, maxLen: number): string {
+  if (maxLen <= 3) return str.slice(0, maxLen);
+  if (str.length <= maxLen) return str;
+  return `${str.slice(0, maxLen - 3)}...`;
+}
+
+class ProcessesComponent implements Component {
+  private tui: { requestRender: () => void };
+  private theme: Theme;
+  private onClose: () => void;
+  private manager: ProcessManager;
+
+  private selectedIndex = 0;
+  private processScrollOffset = 0;
+  private logScrollOffset = 0;
+  private scrollInfo = { above: 0, below: 0 };
+  private cachedLines: string[] = [];
+  private cachedWidth = 0;
+  private refreshInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    tui: { requestRender: () => void },
+    theme: Theme,
+    onClose: () => void,
+    manager: ProcessManager,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.onClose = onClose;
+    this.manager = manager;
+
+    this.refreshInterval = setInterval(() => {
+      this.invalidate();
+      this.tui.requestRender();
+    }, 1000);
+  }
+
+  handleInput(data: string): boolean {
+    const processes = this.manager.list();
+
+    // Navigation
+    if (matchesKey(data, "down") || data === "j") {
+      if (processes.length > 0) {
+        this.selectedIndex = Math.min(
+          this.selectedIndex + 1,
+          processes.length - 1,
+        );
+        this.logScrollOffset = 0;
+        this.ensureProcessVisible(processes.length);
+        this.invalidate();
+        this.tui.requestRender();
+      }
+      return true;
+    }
+
+    if (matchesKey(data, "up") || data === "k") {
+      if (processes.length > 0) {
+        this.selectedIndex = Math.max(this.selectedIndex - 1, 0);
+        this.logScrollOffset = 0;
+        this.ensureProcessVisible(processes.length);
+        this.invalidate();
+        this.tui.requestRender();
+      }
+      return true;
+    }
+
+    // Scroll logs
+    if (data === "J") {
+      this.logScrollOffset = Math.max(0, this.logScrollOffset - 5);
+      this.invalidate();
+      this.tui.requestRender();
+      return true;
+    }
+
+    if (data === "K") {
+      this.logScrollOffset += 5;
+      this.invalidate();
+      this.tui.requestRender();
+      return true;
+    }
+
+    // Kill selected process
+    if (data === "x" || data === "X") {
+      if (processes.length > 0 && this.selectedIndex < processes.length) {
+        const proc = processes[this.selectedIndex];
+        if (proc && proc.status === "running") {
+          this.manager.kill(proc.id);
+          this.invalidate();
+          this.tui.requestRender();
+        }
+      }
+      return true;
+    }
+
+    // Clear finished processes
+    if (data === "c" || data === "C") {
+      const cleared = this.manager.clearFinished();
+      if (cleared > 0) {
+        // Adjust selection if needed
+        const remaining = this.manager.list();
+        if (this.selectedIndex >= remaining.length) {
+          this.selectedIndex = Math.max(0, remaining.length - 1);
+        }
+        this.ensureProcessVisible(remaining.length);
+        this.invalidate();
+        this.tui.requestRender();
+      }
+      return true;
+    }
+
+    // Close
+    if (matchesKey(data, "escape") || data === "q" || data === "Q") {
+      if (this.refreshInterval) {
+        clearInterval(this.refreshInterval);
+        this.refreshInterval = null;
+      }
+      this.onClose();
+      return true;
+    }
+
+    return true;
+  }
+
+  private ensureProcessVisible(totalProcesses: number): void {
+    const visibleCount = Math.min(MAX_VISIBLE_PROCESSES, totalProcesses);
+    if (this.selectedIndex < this.processScrollOffset) {
+      this.processScrollOffset = this.selectedIndex;
+    } else if (this.selectedIndex >= this.processScrollOffset + visibleCount) {
+      this.processScrollOffset = this.selectedIndex - visibleCount + 1;
+    }
+    this.processScrollOffset = Math.max(
+      0,
+      Math.min(this.processScrollOffset, totalProcesses - visibleCount),
+    );
+  }
+
+  invalidate(): void {
+    this.cachedWidth = 0;
+    this.cachedLines = [];
+  }
+
+  render(width: number): string[] {
+    if (width === this.cachedWidth && this.cachedLines.length > 0) {
+      return this.cachedLines;
+    }
+
+    const theme = this.theme;
+    const dim = (s: string) => theme.fg("dim", s);
+    const accent = (s: string) => theme.fg("accent", s);
+    const warning = (s: string) => theme.fg("warning", s);
+    const bold = (s: string) => theme.bold(s);
+    const border = (s: string) => theme.fg("dim", s);
+
+    const lines: string[] = [];
+    const processes = this.manager.list();
+    const innerWidth = width - 2; // 1 char padding each side
+
+    // Helper to pad line
+    const padLine = (content: string): string => {
+      const len = visibleWidth(content);
+      return ` ${content}${" ".repeat(Math.max(0, innerWidth - len))} `;
+    };
+
+    // Top border with title
+    const title = " Background Processes ";
+    const titleLen = title.length;
+    const borderLen = Math.max(0, width - titleLen);
+    const leftBorder = Math.floor(borderLen / 2);
+    const rightBorder = borderLen - leftBorder;
+    lines.push(
+      border("─".repeat(leftBorder)) +
+        accent(bold(title)) +
+        border("─".repeat(rightBorder)),
+    );
+
+    if (processes.length === 0) {
+      lines.push(padLine(""));
+      lines.push(padLine(dim("No background processes")));
+      lines.push(padLine(dim("Use the processes tool to start commands")));
+      lines.push(padLine(""));
+    } else {
+      // Calculate column widths
+      const prefixWidth = 2; // "> " or "  "
+      const idWidth = 9;
+      const nameWidth = 15;
+      const statusWidth = 14;
+      const timeWidth = 8;
+      const sizeWidth = 8;
+      const cmdWidth = Math.max(
+        20,
+        innerWidth -
+          prefixWidth -
+          idWidth -
+          nameWidth -
+          statusWidth -
+          timeWidth -
+          sizeWidth,
+      );
+
+      // Header with scroll indicator if needed
+      const hasProcessScroll = processes.length > MAX_VISIBLE_PROCESSES;
+      const headerSuffix = hasProcessScroll
+        ? dim(
+            ` [${this.processScrollOffset + 1}-${Math.min(this.processScrollOffset + MAX_VISIBLE_PROCESSES, processes.length)}/${processes.length}]`,
+          )
+        : "";
+
+      lines.push(padLine(""));
+      const header =
+        "  " +
+        dim("ID".padEnd(idWidth)) +
+        dim("Name".padEnd(nameWidth)) +
+        dim("Command".padEnd(cmdWidth)) +
+        dim("Status".padEnd(statusWidth)) +
+        dim("Time".padEnd(timeWidth)) +
+        dim("Size".padStart(sizeWidth)) +
+        headerSuffix;
+      lines.push(padLine(header));
+      lines.push(border("─".repeat(width)));
+
+      // Process rows (limited to MAX_VISIBLE_PROCESSES)
+      const visibleProcessCount = Math.min(
+        MAX_VISIBLE_PROCESSES,
+        processes.length,
+      );
+      const startIdx = this.processScrollOffset;
+      const endIdx = startIdx + visibleProcessCount;
+
+      for (let i = startIdx; i < endIdx; i++) {
+        const proc = processes[i];
+        if (!proc) continue;
+        const isSelected = i === this.selectedIndex;
+        const sizes = this.manager.getFileSize(proc.id);
+        const totalSize = sizes ? sizes.stdout + sizes.stderr : 0;
+
+        const statusText = this.formatStatus(proc);
+        const statusPadding =
+          statusWidth + (statusText.length - visibleWidth(statusText));
+
+        const row =
+          (isSelected
+            ? accent(proc.id.padEnd(idWidth))
+            : proc.id.padEnd(idWidth)) +
+          truncate(proc.name, nameWidth - 1).padEnd(nameWidth) +
+          truncate(proc.command, cmdWidth - 1).padEnd(cmdWidth) +
+          statusText.padEnd(statusPadding) +
+          formatRuntime(proc.startTime, proc.endTime).padEnd(timeWidth) +
+          formatBytes(totalSize).padStart(sizeWidth);
+
+        if (isSelected) {
+          lines.push(padLine(`${accent(">")} ${row}`));
+        } else {
+          lines.push(padLine(`  ${row}`));
+        }
+      }
+
+      // Pad process list to fixed height
+      for (let i = visibleProcessCount; i < MAX_VISIBLE_PROCESSES; i++) {
+        lines.push(padLine(""));
+      }
+
+      // Output section for selected process
+      if (this.selectedIndex < processes.length) {
+        const selected = processes[this.selectedIndex];
+        if (!selected) {
+          this.cachedLines = lines;
+          this.cachedWidth = width;
+          return this.cachedLines;
+        }
+        const output = this.manager.getOutput(selected.id, 200);
+        const sizes = this.manager.getFileSize(selected.id);
+
+        lines.push(border("─".repeat(width)));
+
+        // Output header with size info
+        const logTitle = `Output: ${accent(selected.name)} ${dim(`(${selected.id})`)}`;
+        const sizeInfo = sizes
+          ? dim(
+              ` stdout: ${formatBytes(sizes.stdout)}, stderr: ${formatBytes(sizes.stderr)}`,
+            )
+          : "";
+        lines.push(padLine(logTitle + sizeInfo));
+        lines.push(padLine(""));
+
+        let renderedLines = 0;
+
+        if (output) {
+          const logLines: { type: "stdout" | "stderr"; text: string }[] = [];
+          for (const line of output.stdout) {
+            logLines.push({ type: "stdout", text: line });
+          }
+          for (const line of output.stderr) {
+            logLines.push({ type: "stderr", text: line });
+          }
+
+          if (logLines.length === 0) {
+            lines.push(padLine(dim("(no output yet)")));
+            renderedLines = 1;
+          } else {
+            const startIdx = Math.max(
+              0,
+              logLines.length - MAX_LOG_LINES - this.logScrollOffset,
+            );
+            const endIdx = Math.max(0, logLines.length - this.logScrollOffset);
+            const visibleLines = logLines.slice(startIdx, endIdx);
+
+            // Track scroll info for footer
+            this.scrollInfo.above = startIdx;
+            this.scrollInfo.below =
+              this.logScrollOffset > 0 ? logLines.length - endIdx : 0;
+
+            for (const line of visibleLines) {
+              const displayLine = truncate(line.text, innerWidth - 2);
+              if (line.type === "stderr") {
+                lines.push(padLine(warning(displayLine)));
+              } else {
+                lines.push(padLine(displayLine));
+              }
+              renderedLines++;
+            }
+          }
+        }
+
+        // Pad to fixed height
+        while (renderedLines < MAX_LOG_LINES) {
+          lines.push(padLine(""));
+          renderedLines++;
+        }
+      }
+    }
+
+    // Footer divider
+    lines.push(border("─".repeat(width)));
+
+    // Footer with controls
+    const footerLeft =
+      `${dim("j/k")} select  ` +
+      `${dim("x")} kill  ` +
+      `${dim("c")} clear  ` +
+      `${dim("q")} quit`;
+
+    let footerRight = "";
+    if (this.scrollInfo.above > 0 || this.scrollInfo.below > 0) {
+      const parts: string[] = [];
+      if (this.scrollInfo.above > 0) {
+        parts.push(`↑${this.scrollInfo.above}`);
+      }
+      if (this.scrollInfo.below > 0) {
+        parts.push(`↓${this.scrollInfo.below}`);
+      }
+      footerRight = `${dim("J/K")} scroll ${dim(parts.join(" "))}`;
+    }
+
+    const footerLeftLen = visibleWidth(footerLeft);
+    const footerRightLen = visibleWidth(footerRight);
+    const footerGap = Math.max(2, innerWidth - footerLeftLen - footerRightLen);
+    const footer = footerLeft + " ".repeat(footerGap) + footerRight;
+
+    lines.push(padLine(footer));
+
+    // Bottom border
+    lines.push(border("─".repeat(width)));
+
+    this.cachedLines = lines;
+    this.cachedWidth = width;
+
+    return this.cachedLines;
+  }
+
+  private formatStatus(proc: ProcessInfo): string {
+    const theme = this.theme;
+    const dim = (s: string) => theme.fg("dim", s);
+    const success = (s: string) => theme.fg("success", s);
+    const warning = (s: string) => theme.fg("warning", s);
+    const error = (s: string) => theme.fg("error", s);
+
+    const icon = this.getStatusIcon(proc.status, proc.success);
+
+    switch (proc.status) {
+      case "running":
+        return success(`${icon} running`);
+      case "exited":
+        if (proc.success) {
+          return dim(`${icon} exit(0)`);
+        }
+        return error(`${icon} exit(${proc.exitCode ?? "?"})`);
+      case "killed":
+        return warning(`${icon} killed`);
+      default:
+        return proc.status;
+    }
+  }
+
+  private getStatusIcon(
+    status: ProcessInfo["status"],
+    success: boolean | null,
+  ): string {
+    switch (status) {
+      case "running":
+        return "\u25CF"; // filled circle
+      case "exited":
+        return success ? "\u2713" : "\u2717"; // check or x
+      case "killed":
+        return "\u2717"; // x mark
+      default:
+        return "?";
+    }
+  }
+}
+
+const WIDGET_ID = "processes-status";
+
+export function setupProcessesCommands(
+  pi: ExtensionAPI,
+  manager: ProcessManager,
+) {
+  pi.registerCommand("processes", {
+    description: "View and manage background processes",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/processes requires interactive mode", "error");
+        return;
+      }
+      await ctx.ui.custom((tui, theme, _keybindings, done) => {
+        return new ProcessesComponent(
+          tui,
+          theme,
+          () => done(undefined),
+          manager,
+        );
+      });
+    },
+  });
+
+  pi.registerCommand("processes:clear", {
+    description: "Clear finished processes and hide widget",
+    handler: async (_args, ctx) => {
+      const cleared = manager.clearFinished();
+      const remaining = manager.list();
+
+      // Hide widget if no processes remain
+      if (remaining.length === 0 && ctx.hasUI) {
+        ctx.ui.setWidget(WIDGET_ID, undefined);
+      }
+
+      if (cleared > 0) {
+        ctx.ui.notify(`Cleared ${cleared} finished process(es)`, "info");
+      } else {
+        ctx.ui.notify("No finished processes to clear", "info");
+      }
+    },
+  });
+}

package/constants.ts

@@ -0,0 +1,2 @@
+// Custom message type for process update notifications
+export const MESSAGE_TYPE_PROCESS_UPDATE = "ad-process:update";

package/hooks/cleanup.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ProcessManager } from "../manager";
+
+export function setupCleanupHook(pi: ExtensionAPI, manager: ProcessManager) {
+  pi.on("session_shutdown", async () => {
+    manager.cleanup();
+  });
+}

package/hooks/index.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ProcessManager } from "../manager";
+import { setupCleanupHook } from "./cleanup";
+import { setupMessageRenderer } from "./message-renderer";
+import { setupProcessEndHook } from "./process-end";
+import { setupProcessWidget } from "./widget";
+
+export function setupProcessesHooks(pi: ExtensionAPI, manager: ProcessManager) {
+  setupCleanupHook(pi, manager);
+  setupProcessEndHook(pi, manager);
+
+  // Set up widget AFTER process-end so it chains onto the existing callback
+  setupProcessWidget(pi, manager);
+
+  setupMessageRenderer(pi);
+}

package/hooks/message-renderer.ts

@@ -0,0 +1,83 @@
+import type {
+  ExtensionAPI,
+  MessageRenderOptions,
+  Theme,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { MESSAGE_TYPE_PROCESS_UPDATE } from "../constants";
+
+interface ProcessUpdateDetails {
+  processId: string;
+  processName: string;
+  command: string;
+  status: "exited" | "killed";
+  exitCode: number | null;
+  success: boolean;
+  runtime: string;
+}
+
+interface ProcessUpdateMessage {
+  customType: string;
+  content: string | Array<{ type: string; text?: string }>;
+  details?: ProcessUpdateDetails;
+}
+
+function getContentText(
+  content: string | Array<{ type: string; text?: string }>,
+): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  return content
+    .filter((c) => c.type === "text" && c.text)
+    .map((c) => c.text as string)
+    .join("");
+}
+
+export function setupMessageRenderer(pi: ExtensionAPI) {
+  pi.registerMessageRenderer<ProcessUpdateDetails>(
+    MESSAGE_TYPE_PROCESS_UPDATE,
+    (
+      message: ProcessUpdateMessage,
+      _options: MessageRenderOptions,
+      theme: Theme,
+    ) => {
+      const details = message.details;
+
+      if (!details) {
+        return new Text(getContentText(message.content), 0, 0);
+      }
+
+      let icon: string;
+      let color: "success" | "error" | "warning";
+
+      if (details.status === "killed") {
+        icon = "\u2717"; // x mark
+        color = "warning";
+      } else if (details.success) {
+        icon = "\u2713"; // check mark
+        color = "success";
+      } else {
+        icon = "\u2717"; // x mark
+        color = "error";
+      }
+
+      const statusText =
+        details.status === "killed"
+          ? "terminated"
+          : details.success
+            ? "completed"
+            : `exited(${details.exitCode ?? "?"})`;
+
+      const text =
+        theme.fg(color, `${icon} `) +
+        theme.fg("accent", `"${details.processName}"`) +
+        theme.fg("muted", ` (${details.processId})`) +
+        " " +
+        theme.fg(color, statusText) +
+        theme.fg("muted", ` ${details.runtime}`);
+
+      return new Text(text, 0, 0);
+    },
+  );
+}