@mjakl/pi-processes 0.8.0

package/src/tools/index.ts

@@ -0,0 +1,347 @@
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  Theme,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { type Static, Type } from "typebox";
+import type { ProcessesDetails } from "../constants";
+import type { ProcessManager } from "../manager";
+import { formatRuntime, hasAnsi, stripAnsi, truncateCmd } from "../utils";
+import { executeAction } from "./actions";
+import { ToolBody, ToolCallHeader, ToolFooter } from "./tool-rendering";
+
+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"),
+    ],
+    {
+      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)",
+    },
+  ),
+  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:
+        "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.",
+    }),
+  ),
+  continueAfterStart: Type.Optional(
+    Type.Boolean({
+      description:
+        "For start only. Leave unset/false when the next step is to wait for process completion; process start will end this agent turn and the extension will resume you on exit. Set true only when you have immediate, specific, non-polling work to do after starting.",
+    }),
+  ),
+});
+
+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, list, output, logs, kill, clear.
+- start requires 'name' and 'command'
+- output/logs/kill require 'id' (exact process ID or exact friendly name)
+- kill supports optional 'force=true' for SIGKILL
+- start supports optional 'continueAfterStart=true' only when there is immediate non-polling work to do
+
+Important behavior:
+- By default, 'start' ends the current agent turn. If the next step is waiting, call 'start' by itself and wait for the automatic process-end notification instead of calling 'list', 'output', or 'logs' repeatedly.
+- Set 'continueAfterStart=true' only when you have specific useful work to do immediately after starting the process; do not use it to poll.
+- This tool is event-driven: the agent is notified automatically when a process exits, fails, or is externally killed.
+- Tool-triggered kills never notify.
+- Use 'output' or 'logs' only on demand: when the user asks, when you need a one-off diagnostic snapshot, or when investigating a problem.
+
+Preferred pattern: start the process once, let the turn stop, and resume from the automatic notification instead of polling.`,
+    promptSnippet:
+      "Start and manage background processes without blocking the conversation; process start waits for notifications by default",
+    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, do not call process list/output/logs just to wait. If the next step is waiting, call process start by itself; by default it ends the turn and the extension will resume the agent when the process exits.",
+      "Set process continueAfterStart=true only when there is immediate, specific, non-polling work to do after start.",
+      "Use process output or process logs only for a one-off inspection, explicit user request, or debugging.",
+    ],
+
+    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;
+      }
+
+      if (args.action === "kill" && args.force) {
+        optionArgs.push({ label: "force", value: "true" });
+      }
+
+      if (args.action === "start" && args.continueAfterStart) {
+        optionArgs.push({ label: "continueAfterStart", value: "true" });
+      }
+
+      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));
+
+        // 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));
+
+        // 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)}`,
+              `  combined: ${theme.fg("accent", details.logFiles.combinedFile)}`,
+            ].join("\n"),
+            0,
+            0,
+          ),
+        );
+      } else {
+        fields.push({
+          label: "Result",
+          value: details.message,
+          showCollapsed: true,
+        });
+      }
+
+      const footerItems: Array<{
+        label: string;
+        value: string;
+        tone: "accent" | "success" | "error" | "warning" | "muted";
+      }> = [];
+      if (!details.success) {
+        footerItems.push({
+          label: "status",
+          value: "error",
+          tone: "error",
+        });
+      }
+      const footer =
+        footerItems.length > 0
+          ? new ToolFooter(theme, { items: footerItems })
+          : undefined;
+
+      return new ToolBody({ fields, footer }, options, theme);
+    },
+  });
+}

package/src/tools/tool-rendering.ts

@@ -0,0 +1,164 @@
+import type {
+  Theme,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+
+type Tone = "muted" | "accent" | "success" | "warning" | "error" | "dim";
+
+export interface ToolCallHeaderOptionArg {
+  label: string;
+  value: string;
+  tone?: Tone;
+}
+
+export interface ToolCallHeaderLongArg {
+  label?: string;
+  value: string;
+}
+
+export interface ToolCallHeaderConfig {
+  toolName: string;
+  action?: string;
+  mainArg?: string;
+  optionArgs?: ToolCallHeaderOptionArg[];
+  longArgs?: ToolCallHeaderLongArg[];
+  showColon?: boolean;
+}
+
+export class ToolCallHeader implements Component {
+  constructor(
+    private config: ToolCallHeaderConfig,
+    private theme: Theme,
+  ) {}
+
+  handleInput(_data: string): void {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const title =
+      (this.config.showColon ?? Boolean(this.config.action))
+        ? `${this.config.toolName}:`
+        : this.config.toolName;
+    const parts = [this.theme.fg("toolTitle", this.theme.bold(title))];
+
+    if (this.config.action) {
+      parts.push(this.theme.fg("accent", this.config.action));
+    }
+    if (this.config.mainArg) {
+      parts.push(this.theme.fg("accent", this.config.mainArg));
+    }
+
+    for (const option of this.config.optionArgs ?? []) {
+      const label = option.label.trim().toLowerCase();
+      const tone = option.tone ?? "dim";
+      parts.push(
+        `${this.theme.fg("muted", `${label}=`)}${this.theme.fg(tone, option.value)}`,
+      );
+    }
+
+    const lines = [parts.join(" ")];
+    for (const arg of this.config.longArgs ?? []) {
+      if (!arg.value) continue;
+      const label = arg.label
+        ? `${this.theme.fg("muted", `${arg.label.trim().toLowerCase()}:`)} `
+        : "";
+      lines.push(`${label}${this.theme.fg("dim", arg.value)}`);
+    }
+
+    return new Text(lines.join("\n"), 0, 0).render(width);
+  }
+}
+
+export type ToolBodyField =
+  | { label: string; value: string; showCollapsed?: boolean }
+  | (Component & { showCollapsed?: boolean });
+
+export interface ToolBodyConfig {
+  fields: ToolBodyField[];
+  footer?: Component;
+  includeSpacerBeforeFooter?: boolean;
+}
+
+export class ToolBody implements Component {
+  constructor(
+    private config: ToolBodyConfig,
+    private options: ToolRenderResultOptions,
+    private theme: Theme,
+  ) {}
+
+  handleInput(_data: string): void {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const fields = this.options.expanded
+      ? this.config.fields
+      : this.config.fields.filter((field) => field.showCollapsed === true);
+    const lines: string[] = [];
+
+    for (const field of fields) {
+      if (isComponent(field)) {
+        lines.push(...field.render(width));
+      } else {
+        lines.push(
+          ...new Text(
+            `${this.theme.fg("muted", `${field.label}: `)}${field.value}`,
+            0,
+            0,
+          ).render(width),
+        );
+      }
+    }
+
+    if (this.config.footer) {
+      if (this.config.includeSpacerBeforeFooter ?? true) lines.push("");
+      lines.push(...this.config.footer.render(width));
+    }
+
+    return lines;
+  }
+}
+
+export interface ToolFooterItem {
+  label?: string;
+  value: string;
+  tone?: Exclude<Tone, "dim">;
+}
+
+export interface ToolFooterConfig {
+  items: ToolFooterItem[];
+  separator?: " - " | " | ";
+  truncate?: boolean;
+}
+
+export class ToolFooter implements Component {
+  constructor(
+    private theme: Theme,
+    private config: ToolFooterConfig,
+  ) {}
+
+  handleInput(_data: string): void {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const line = this.config.items
+      .filter((item) => item.value.length > 0)
+      .map((item) => {
+        const text = item.label ? `${item.label}: ${item.value}` : item.value;
+        return this.theme.fg(item.tone ?? "muted", text);
+      })
+      .join(this.config.separator ?? " - ");
+
+    return [
+      (this.config.truncate ?? true) ? truncateToWidth(line, width) : line,
+    ];
+  }
+}
+
+function isComponent(field: ToolBodyField): field is Component {
+  return "render" in field && typeof field.render === "function";
+}

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

package/src/utils/command-executor.ts

@@ -0,0 +1,56 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
+
+interface ResolveShellExecutableOptions {
+  configuredShell?: string;
+  knownPaths: string[];
+}
+
+const DEFAULT_KNOWN_SHELL_PATHS = [
+  "/run/current-system/sw/bin/bash",
+  "/bin/bash",
+  "/usr/bin/bash",
+  "/usr/local/bin/bash",
+];
+
+function isExistingAbsolutePath(shell: string | undefined): shell is string {
+  return typeof shell === "string" && isAbsolute(shell) && existsSync(shell);
+}
+
+export function resolveShellExecutable({
+  configuredShell,
+  knownPaths,
+}: ResolveShellExecutableOptions): string {
+  if (isExistingAbsolutePath(configuredShell)) {
+    return configuredShell;
+  }
+
+  for (const path of knownPaths) {
+    if (isExistingAbsolutePath(path)) {
+      return path;
+    }
+  }
+
+  throw new Error(
+    "Unable to resolve shell executable. Checked configured shell and known shell paths.",
+  );
+}
+
+export function spawnCommand(
+  command: string,
+  cwd: string,
+  configuredShell?: string,
+): ChildProcess {
+  const shellExecutable = resolveShellExecutable({
+    configuredShell,
+    knownPaths: DEFAULT_KNOWN_SHELL_PATHS,
+  });
+
+  return spawn(shellExecutable, ["-lc", command], {
+    cwd,
+    env: process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+    detached: true,
+  });
+}

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