@aliou/pi-processes 0.3.4 → 0.4.0

package/config.ts

@@ -0,0 +1,62 @@
+/**
+ * Configuration for the processes extension.
+ *
+ * Global: ~/.pi/agent/extensions/processes.json
+ * Memory: ephemeral overrides via /process:settings
+ */
+
+import { ConfigLoader } from "@aliou/pi-utils-settings";
+
+export interface ProcessesConfig {
+  processList?: {
+    /** Max visible processes in the /process:list TUI list. */
+    maxVisibleProcesses?: number;
+    /** Max log preview lines shown below the selected process. */
+    maxPreviewLines?: number;
+  };
+  output?: {
+    /** Default number of tail lines returned to the agent. */
+    defaultTailLines?: number;
+    /** Hard cap on output lines returned to the agent. */
+    maxOutputLines?: number;
+  };
+  widget?: {
+    /** Show the status widget below the editor. */
+    showStatusWidget?: boolean;
+  };
+}
+
+export interface ResolvedProcessesConfig {
+  processList: {
+    maxVisibleProcesses: number;
+    maxPreviewLines: number;
+  };
+  output: {
+    defaultTailLines: number;
+    maxOutputLines: number;
+  };
+  widget: {
+    showStatusWidget: boolean;
+  };
+}
+
+const DEFAULT_CONFIG: ResolvedProcessesConfig = {
+  processList: {
+    maxVisibleProcesses: 8,
+    maxPreviewLines: 12,
+  },
+  output: {
+    defaultTailLines: 100,
+    maxOutputLines: 200,
+  },
+  widget: {
+    showStatusWidget: true,
+  },
+};
+
+export const configLoader = new ConfigLoader<
+  ProcessesConfig,
+  ResolvedProcessesConfig
+>("process", DEFAULT_CONFIG, {
+  scopes: ["global", "memory"],
+});

package/constants/index.ts

@@ -0,0 +1,11 @@
+export type {
+  ExecuteResult,
+  KillResult,
+  ManagerEvent,
+  ProcessesDetails,
+  ProcessInfo,
+  ProcessStatus,
+  StartOptions,
+} from "./types";
+
+export { LIVE_STATUSES, MESSAGE_TYPE_PROCESS_UPDATE } from "./types";

package/constants/types.ts

@@ -0,0 +1,65 @@
+// Custom message type for process update notifications
+export const MESSAGE_TYPE_PROCESS_UPDATE = "ad-process:update";
+
+export type ProcessStatus =
+  | "running"
+  | "terminating"
+  | "terminate_timeout"
+  | "exited"
+  | "killed";
+
+export const LIVE_STATUSES: ReadonlySet<ProcessStatus> = new Set([
+  "running",
+  "terminating",
+  "terminate_timeout",
+]);
+
+export interface ProcessInfo {
+  id: string;
+  name: string;
+  pid: number; // On Unix, this is also the PGID (process group leader)
+  command: string;
+  cwd: string;
+  startTime: number;
+  endTime: number | null;
+  status: ProcessStatus;
+  exitCode: number | null;
+  success: boolean | null; // null if running, true if exit code 0, false otherwise
+  stdoutFile: string;
+  stderrFile: string;
+  alertOnSuccess: boolean;
+  alertOnFailure: boolean;
+  alertOnKill: boolean;
+}
+
+export type ManagerEvent =
+  | { type: "process_started"; info: ProcessInfo }
+  | { type: "process_status_changed"; info: ProcessInfo; prev: ProcessStatus }
+  | { type: "process_ended"; info: ProcessInfo }
+  | { type: "processes_changed" };
+
+export type KillResult =
+  | { ok: true; info: ProcessInfo }
+  | { ok: false; info: ProcessInfo; reason: "not_found" | "timeout" | "error" };
+
+export interface StartOptions {
+  alertOnSuccess?: boolean;
+  alertOnFailure?: boolean;
+  alertOnKill?: boolean;
+}
+
+export interface ProcessesDetails {
+  action: string;
+  success: boolean;
+  message: string;
+  process?: ProcessInfo;
+  processes?: ProcessInfo[];
+  output?: { stdout: string[]; stderr: string[]; status: string };
+  logFiles?: { stdoutFile: string; stderrFile: string };
+  cleared?: number;
+}
+
+export interface ExecuteResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: ProcessesDetails;
+}

package/hooks/index.ts

@@ -10,7 +10,9 @@ export function setupProcessesHooks(pi: ExtensionAPI, manager: ProcessManager) {
   setupProcessEndHook(pi, manager);
 
   // Set up widget AFTER process-end so it chains onto the existing callback
-  setupProcessWidget(pi, manager);
+  const widget = setupProcessWidget(pi, manager);
 
   setupMessageRenderer(pi);
+
+  return widget;
 }

package/hooks/widget.ts

@@ -3,6 +3,7 @@ import type {
   ExtensionContext,
 } from "@mariozechner/pi-coding-agent";
 import { visibleWidth } from "@mariozechner/pi-tui";
+import { configLoader } from "../config";
 import type { ProcessInfo } from "../constants";
 import type { ProcessManager } from "../manager";
 
@@ -106,6 +107,11 @@ export function setupProcessWidget(pi: ExtensionAPI, manager: ProcessManager) {
   function updateWidget() {
     if (!latestContext?.hasUI) return;
 
+    if (!configLoader.getConfig().widget.showStatusWidget) {
+      latestContext.ui.setWidget(WIDGET_ID, undefined);
+      return;
+    }
+
     const processes = manager.list();
     const maxWidth = process.stdout.columns || 120;
     const lines = renderWidget(processes, latestContext.ui.theme, maxWidth);

package/index.ts

@@ -1,10 +1,12 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { setupProcessesCommands } from "./commands";
+import { registerProcessesSettings } from "./commands/settings-command";
+import { configLoader } from "./config";
 import { setupProcessesHooks } from "./hooks";
 import { ProcessManager } from "./manager";
 import { setupProcessesTools } from "./tools";
 
-export default function (pi: ExtensionAPI) {
+export default async function (pi: ExtensionAPI) {
   if (process.platform === "win32") {
     pi.on("session_start", async (_event, ctx) => {
       if (!ctx.hasUI) return;
@@ -13,9 +15,13 @@ export default function (pi: ExtensionAPI) {
     return;
   }
 
+  await configLoader.load();
   const manager = new ProcessManager();
 
-  setupProcessesHooks(pi, manager);
-  setupProcessesTools(pi, manager);
-  setupProcessesCommands(pi, manager);
+  const { update: updateWidget } = setupProcessesHooks(pi, manager);
+  const commands = setupProcessesCommands(pi, manager);
+  setupProcessesTools(pi, manager, commands);
+  registerProcessesSettings(pi, () => {
+    updateWidget();
+  });
 }

package/manager.ts

@@ -23,6 +23,7 @@ import { isProcessGroupAlive, killProcessGroup } from "./utils";
 interface ManagedProcess extends ProcessInfo {
   process: ChildProcess;
   lastSignalSent: NodeJS.Signals | null;
+  combinedFile: string;
 }
 
 export class ProcessManager {
@@ -122,9 +123,11 @@ export class ProcessManager {
     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 = spawn("/bin/bash", ["-lc", command], {
       cwd,
@@ -148,6 +151,7 @@ export class ProcessManager {
       success: null,
       stdoutFile,
       stderrFile,
+      combinedFile,
       alertOnSuccess: options?.alertOnSuccess ?? false,
       alertOnFailure: options?.alertOnFailure ?? true,
       alertOnKill: options?.alertOnKill ?? false,
@@ -173,6 +177,15 @@ export class ProcessManager {
     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
       }
@@ -181,6 +194,13 @@ export class ProcessManager {
     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
       }
@@ -262,6 +282,26 @@ export class ProcessManager {
     };
   }
 
+  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;
@@ -374,6 +414,7 @@ export class ProcessManager {
       try {
         rmSync(managed.stdoutFile, { force: true });
         rmSync(managed.stderrFile, { force: true });
+        rmSync(managed.combinedFile, { force: true });
       } catch {
         // Ignore
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-processes",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "type": "module",
   "private": false,
   "keywords": [
@@ -25,12 +25,16 @@
   "files": [
     "*.ts",
     "commands",
+    "components",
+    "constants",
     "hooks",
     "tools",
+    "utils",
     "README.md"
   ],
   "dependencies": {
-    "@sinclair/typebox": "^0.34.41"
+    "@sinclair/typebox": "^0.34.41",
+    "@aliou/pi-utils-settings": "0.2.1"
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": ">=0.51.0"

package/tools/actions/kill.ts

@@ -53,7 +53,7 @@ export async function executeKill(
   if (result.reason === "timeout") {
     const message =
       `SIGTERM timed out for "${proc.name}" (${proc.id}). ` +
-      "Run /processes and press x on terminate_timeout to force kill (SIGKILL).";
+      "Run /process:list and press x on terminate_timeout to force kill (SIGKILL).";
     return {
       content: [{ type: "text", text: message }],
       details: {

package/tools/actions/output.ts

@@ -1,8 +1,8 @@
+import { configLoader } from "../../config";
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { formatStatus, stripAnsi } from "../../utils";
 
-const MAX_LINES = 200;
 const MAX_BYTES = 50 * 1024; // 50KB
 
 interface OutputParams {
@@ -37,7 +37,8 @@ export function executeOutput(
     };
   }
 
-  const output = manager.getOutput(proc.id);
+  const { defaultTailLines } = configLoader.getConfig().output;
+  const output = manager.getOutput(proc.id, defaultTailLines);
   if (!output) {
     const message = `Could not read output for: ${proc.id}`;
     return {
@@ -68,7 +69,8 @@ export function executeOutput(
   }
 
   const fullText = outputParts.join("\n");
-  const contentText = truncateTail(fullText, logFiles);
+  const { maxOutputLines } = configLoader.getConfig().output;
+  const contentText = truncateTail(fullText, logFiles, maxOutputLines);
 
   return {
     content: [{ type: "text", text: contentText }],
@@ -89,12 +91,13 @@ export function executeOutput(
 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 <= MAX_LINES && totalBytes <= MAX_BYTES) {
+  if (totalLines <= maxLines && totalBytes <= MAX_BYTES) {
     return text;
   }
 
@@ -103,7 +106,7 @@ function truncateTail(
   let keptBytes = 0;
   let hitBytes = false;
 
-  for (let i = lines.length - 1; i >= 0 && kept.length < MAX_LINES; i--) {
+  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);

package/tools/index.ts

@@ -57,10 +57,16 @@ const ProcessesParams = Type.Object({
 
 type ProcessesParamsType = Static<typeof ProcessesParams>;
 
-export function setupProcessesTools(pi: ExtensionAPI, manager: ProcessManager) {
+import type { ProcessCommands } from "../commands";
+
+export function setupProcessesTools(
+  pi: ExtensionAPI,
+  manager: ProcessManager,
+  commands: ProcessCommands,
+) {
   pi.registerTool<typeof ProcessesParams, ProcessesDetails>({
-    name: "processes",
-    label: "Processes",
+    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
@@ -79,22 +85,33 @@ Note: User always sees process updates in the UI. The notify flags control wheth
     parameters: ProcessesParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      return executeAction(params, manager, ctx);
+      const result = await executeAction(params, manager, ctx);
+      // Auto-stream logs when a process is started successfully.
+      if (
+        params.action === "start" &&
+        result.details?.success &&
+        result.details.process &&
+        ctx.hasUI
+      ) {
+        commands.streamProcess(result.details.process.id, ctx.ui);
+      }
+      return result;
     },
 
     renderCall(args: ProcessesParamsType, theme: Theme): Text {
-      let text = theme.fg("toolTitle", theme.bold("processes "));
+      let text = theme.fg("toolTitle", theme.bold("Process "));
       text += theme.fg("accent", args.action);
 
       switch (args.action) {
-        case "start":
+        case "start": {
           if (args.name) {
             text += ` ${theme.fg("accent", `"${args.name}"`)}`;
           }
           if (args.command) {
-            text += ` ${theme.fg("muted", args.command.slice(0, 40))}`;
+            text += `\n${theme.fg("muted", `$ ${args.command}`)}`;
           }
-          break;
+          return new Text(text, 0, 0);
+        }
         case "output":
         case "kill":
         case "logs":

package/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;
+}

package/utils/format.ts

@@ -0,0 +1,42 @@
+import type { ProcessInfo } from "../constants";
+
+export 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`;
+}
+
+export function formatStatus(proc: ProcessInfo): string {
+  switch (proc.status) {
+    case "running":
+      return "running";
+    case "terminating":
+      return "terminating";
+    case "terminate_timeout":
+      return "terminate_timeout";
+    case "killed":
+      return "killed";
+    case "exited":
+      return proc.success ? "exit(0)" : `exit(${proc.exitCode ?? "?"})`;
+    default:
+      return proc.status;
+  }
+}
+
+export function truncateCmd(cmd: string, max = 40): string {
+  if (cmd.length <= max) return cmd;
+  return `${cmd.slice(0, max - 3)}...`;
+}

package/utils/index.ts

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

package/utils/process-group.ts

@@ -0,0 +1,22 @@
+/**
+ * Check if a process group is still alive.
+ * Uses signal 0 to test existence without actually sending a signal.
+ */
+export function isProcessGroupAlive(pgid: number): boolean {
+  try {
+    process.kill(-pgid, 0);
+    return true;
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException;
+    // EPERM: exists, but we can't signal it
+    return err.code === "EPERM";
+  }
+}
+
+/**
+ * Send a signal to an entire process group.
+ * Negative PID targets the process group.
+ */
+export function killProcessGroup(pgid: number, signal: NodeJS.Signals): void {
+  process.kill(-pgid, signal);
+}