@haemmid/pi-processes 0.9.0

package/src/tools/actions/list.ts

@@ -0,0 +1,48 @@
+import { type ExecuteResult, LIVE_STATUSES } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import {
+  formatRuntime,
+  formatStatus,
+  sanitizeLine,
+  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} "${sanitizeLine(p.name)}": ${truncateCmd(sanitizeLine(p.command))} [${formatStatus(p)}] ${formatRuntime(p.startTime, p.endTime)}`,
+    )
+    .join("\n");
+
+  const hasLiveProcess = processes.some((process) =>
+    LIVE_STATUSES.has(process.status),
+  );
+  const waitNotice = hasLiveProcess
+    ? "\n\nUse process output/logs only when you need a one-off status snapshot. Do not poll repeatedly just to wait."
+    : "";
+  const message = `${processes.length} process(es):\n${summary}${waitNotice}`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "list",
+      success: true,
+      message,
+      processes,
+    },
+  };
+}

package/src/tools/actions/logs.ts

@@ -0,0 +1,86 @@
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { sanitizeLine } from "../../utils";
+
+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 resolved = manager.resolve(params.id);
+  if (!resolved.ok) {
+    if (resolved.reason === "ambiguous") {
+      const choices = (resolved.matches ?? [])
+        .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
+        .join(", ");
+      const message =
+        `Process name is ambiguous: ${params.id}. ` +
+        `Use an exact process ID instead. Matches: ${choices}`;
+      return {
+        content: [{ type: "text", text: message }],
+        details: {
+          action: "logs",
+          success: false,
+          message,
+        },
+      };
+    }
+
+    const message = `Process not found: ${params.id}`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "logs",
+        success: false,
+        message,
+      },
+    };
+  }
+
+  const proc = resolved.info;
+  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 "${sanitizeLine(proc.name)}" (${proc.id}):`,
+    `  stdout: ${logFiles.stdoutFile}`,
+    `  stderr: ${logFiles.stderrFile}`,
+    `  combined: ${logFiles.combinedFile}`,
+    "",
+    "Use the read tool to inspect these files.",
+  ].join("\n");
+
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "logs",
+      success: true,
+      message,
+      logFiles,
+    },
+  };
+}

package/src/tools/actions/output.ts

@@ -0,0 +1,186 @@
+import { configLoader } from "../../config";
+import {
+  type ExecuteResult,
+  LIVE_STATUSES,
+  type ResolveProcessResult,
+} from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { formatStatus, sanitizeLine } from "../../utils";
+
+const MAX_BYTES = 50 * 1024; // 50KB
+
+interface OutputParams {
+  id?: string;
+}
+
+function resolveProcessResult(
+  result: ResolveProcessResult,
+  action: "output" | "logs",
+  id: string,
+): ExecuteResult | null {
+  if (result.ok) return null;
+
+  if (result.reason === "ambiguous") {
+    const choices = (result.matches ?? [])
+      .map((match) => `${match.id} ("${sanitizeLine(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,
+        success: false,
+        message,
+      },
+    };
+  }
+
+  const message = `Process not found: ${id}`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action,
+      success: false,
+      message,
+    },
+  };
+}
+
+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 resolved = manager.resolve(params.id);
+  if (!resolved.ok) {
+    return resolveProcessResult(resolved, "output", params.id) as ExecuteResult;
+  }
+
+  const proc = resolved.info;
+  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 = `"${sanitizeLine(proc.name)}" (${proc.id}) [${formatStatus(proc)}]: ${stdoutLines} stdout lines, ${stderrLines} stderr lines`;
+
+  // Build sanitized text content, 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(sanitizeLine));
+  }
+  if (output.stderr.length > 0) {
+    outputParts.push("\nstderr:");
+    outputParts.push(...output.stderr.map(sanitizeLine));
+  }
+  if (LIVE_STATUSES.has(proc.status)) {
+    outputParts.push(
+      "",
+      "[Process is still active. This was a one-off snapshot; use process list to check status.]",
+    );
+  }
+
+  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;
+    combinedFile: 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/restart.ts

@@ -0,0 +1,113 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { formatTimestamp, sanitizeLine } from "../../utils";
+import { executeKill } from "./kill";
+
+interface RestartParams {
+  name?: string;
+  command?: string;
+  cwd?: string;
+  force?: boolean;
+}
+
+export async function executeRestart(
+  params: RestartParams,
+  manager: ProcessManager,
+  ctx: ExtensionContext,
+): Promise<ExecuteResult> {
+  if (!params.name) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: name" }],
+      details: {
+        action: "restart",
+        success: false,
+        message: "Missing required parameter: name",
+      },
+    };
+  }
+  if (!params.command) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: command" }],
+      details: {
+        action: "restart",
+        success: false,
+        message: "Missing required parameter: command",
+      },
+    };
+  }
+
+  // Resolve existing process
+  const existing = manager.resolve(params.name);
+  if (!existing.ok) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `No process named "${params.name}" is running. Use process start instead.`,
+        },
+      ],
+      details: {
+        action: "restart",
+        success: false,
+        message: `No process named "${params.name}" is running.`,
+      },
+    };
+  }
+
+  // Kill existing process (awaited, safe)
+  const killResult = await executeKill(
+    { id: existing.info.id, force: params.force },
+    manager,
+  );
+  if (!killResult.details.success) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Failed to kill existing process: ${killResult.details.message}`,
+        },
+      ],
+      details: {
+        action: "restart",
+        success: false,
+        message: `Failed to kill existing process: ${killResult.details.message}`,
+      },
+    };
+  }
+
+  // Start new process
+  const proc = manager.start(
+    params.name,
+    params.command,
+    params.cwd ?? ctx.cwd,
+  );
+
+  if (proc === null) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `A process named "${params.name}" is already running. Use process kill first.`,
+        },
+      ],
+      details: {
+        action: "restart",
+        success: false,
+        message: `A process named "${params.name}" is already running.`,
+      },
+    };
+  }
+
+  const startedAt = formatTimestamp(proc.startTime);
+  const message = `Restarted "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})\nStarted at: ${startedAt}\nLogs: ${proc.stdoutFile}`;
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "restart",
+      success: true,
+      message,
+      process: proc,
+    },
+  };
+}

package/src/tools/actions/start.ts

@@ -0,0 +1,87 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { formatTimestamp, sanitizeLine } from "../../utils";
+
+interface StartParams {
+  name?: string;
+  command?: string;
+  cwd?: string;
+}
+
+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",
+      },
+    };
+  }
+
+  try {
+    const proc = manager.start(
+      params.name,
+      params.command,
+      params.cwd ?? ctx.cwd,
+    );
+
+    if (proc === null) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `A process named "${params.name}" is already running. Use process kill first, or process restart to replace it.`,
+          },
+        ],
+        details: {
+          action: "start",
+          success: false,
+          message: `A process named "${params.name}" is already running.`,
+        },
+      };
+    }
+
+    const startedAt = formatTimestamp(proc.startTime);
+    const message = `Started "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})\nStarted at: ${startedAt}\nLogs: ${proc.stdoutFile}`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "start",
+        success: true,
+        message,
+        process: proc,
+      },
+    };
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? `Failed to start process: ${error.message}`
+        : "Failed to start process";
+
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "start",
+        success: false,
+        message,
+      },
+    };
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,82 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { ProcessesDetails } from "../constants";
+import type { ProcessManager } from "../manager";
+import { executeAction } from "./actions";
+
+const ProcessesParams = Type.Object({
+  action: Type.Union(
+    [
+      Type.Literal("start"),
+      Type.Literal("list"),
+      Type.Literal("output"),
+      Type.Literal("logs"),
+      Type.Literal("kill"),
+      Type.Literal("clear"),
+      Type.Literal("restart"),
+    ],
+    {
+      description:
+        "Action: start (run command), list (show all), output (get recent output), logs (get log file paths), kill (terminate or force-kill), clear (remove finished), restart (kill existing and start new)",
+    },
+  ),
+  command: Type.Optional(
+    Type.String({ description: "Command to run (required for start/restart)" }),
+  ),
+  name: Type.Optional(
+    Type.String({
+      description:
+        "Friendly name for the process (required for start/restart, e.g. 'backend-dev', 'test-runner')",
+    }),
+  ),
+  cwd: Type.Optional(
+    Type.String({
+      description:
+        "Working directory for the command (for start/restart action). Defaults to the session working directory. Prefer this over 'cd dir && command' shell wrappers.",
+    }),
+  ),
+  id: Type.Optional(
+    Type.String({
+      description:
+        "Exact process ID or exact friendly name to match (required for output/kill/logs).",
+    }),
+  ),
+  force: Type.Optional(
+    Type.Boolean({
+      description:
+        "Force-kill the process with SIGKILL for kill action. Use after a normal terminate times out, or when you need an immediate hard stop.",
+    }),
+  ),
+});
+
+export function setupProcessesTools(pi: ExtensionAPI, manager: ProcessManager) {
+  pi.registerTool<typeof ProcessesParams, ProcessesDetails>({
+    name: "process",
+    label: "Process",
+    description: `Manage background processes.
+
+Actions: start, list, output, logs, kill, clear, restart.
+- start/restart require 'name' and 'command' — restart kills existing process first
+- output/logs/kill require 'id' (exact process ID or exact friendly name)
+- kill supports optional 'force=true' for SIGKILL
+- restart is preferred over start+kill: it safely awaits kill before starting new process
+
+Processes continue in the background. Use process output or process logs for a one-off snapshot when you need to inspect status. Do not poll repeatedly just to wait.
+Tool-triggered kills never notify.`,
+    promptSnippet:
+      "Start and manage long-running processes without blocking the conversation; use process output/logs for one-off status snapshots.",
+    promptGuidelines: [
+      "Use the process tool instead of bash for dev servers, watch mode, log tails, port-forwards, or commands that should keep running.",
+      "After process start, the agent continues its turn — use process output/logs to check status if needed.",
+      "Use process output or process logs only for a one-off inspection, explicit user request, or debugging.",
+      "Use process restart to replace an existing process — it safely awaits kill before starting the new one.",
+      "Do not poll process output/list repeatedly just to wait for a process to finish.",
+    ],
+
+    parameters: ProcessesParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      return executeAction(params, manager, ctx);
+    },
+  });
+}

package/src/utils/ansi.ts

@@ -0,0 +1,67 @@
+/**
+ * Strip ANSI escape codes and other terminal control characters from a string.
+ *
+ * Removes:
+ * - All CSI sequences (\x1b[...X) - SGR, cursor movement, erase, scroll, etc.
+ * - OSC sequences (\x1b]...\x07 or \x1b]...\x1b\\)
+ * - APC sequences (\x1b_...\x07 or \x1b_...\x1b\\)
+ * - Remaining C0 control chars except tab/newline
+ */
+
+const ESC = String.fromCodePoint(0x001b);
+const BEL = String.fromCodePoint(0x0007);
+
+/**
+ * Check if a string contains terminal escape codes.
+ */
+export function hasAnsi(str: string): boolean {
+  return str.includes(ESC);
+}
+
+/**
+ * Strip terminal escape sequences from a string while preserving normal text,
+ * whitespace, and line breaks.
+ */
+export function stripAnsi(str: string): string {
+  let clean = str;
+
+  if (str.includes(ESC)) {
+    // Strip all CSI sequences (ESC[...X where X is any letter)
+    clean = clean.replace(new RegExp(`${ESC}\\[[0-9;]*[A-Za-z]`, "gu"), "");
+    // Strip OSC sequences: ESC]...<BEL> or ESC]...<ESC>\\
+    clean = clean.replace(
+      new RegExp(`${ESC}\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "gu"),
+      "",
+    );
+    // Strip APC sequences: ESC_...<BEL> or ESC_...<ESC>\\ (used for cursor marker)
+    clean = clean.replace(
+      new RegExp(`${ESC}_[^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "gu"),
+      "",
+    );
+  }
+
+  // Strip terminal control chars like carriage return/backspace that can
+  // corrupt TUI layout when rendered back into pi.
+  return Array.from(clean)
+    .filter((char) => {
+      const code = char.codePointAt(0) ?? 0;
+      const isDisallowedC0 =
+        (code >= 0x00 && code <= 0x08) ||
+        (code >= 0x0b && code <= 0x1f) ||
+        code === 0x7f;
+      return !isDisallowedC0;
+    })
+    .join("");
+}
+
+/**
+ * Sanitize process output for single-line TUI rendering.
+ *
+ * This is stricter than stripAnsi(): after terminal escapes are removed, any
+ * remaining control bytes (carriage returns, backspaces, BEL, embedded
+ * newlines, etc.) are dropped so process output cannot move the cursor or
+ * alter Pi's surrounding TUI.
+ */
+export function sanitizeLine(str: string): string {
+  return stripAnsi(str).replace(/\t/g, "  ");
+}