@mjakl/pi-processes 0.8.0

package/src/hooks/background-blocker.ts

@@ -0,0 +1,295 @@
+/**
+ * Blocks background bash commands (e.g. `cmd &`, `nohup cmd`) and obvious
+ * long-running foreground commands (e.g. `pnpm dev`, `tail -f`) and guides
+ * the model to use the process tool instead.
+ *
+ * Controlled via config: `interception.blockBackgroundCommands`.
+ */
+
+import { basename } from "node:path";
+import { type Program, parse } from "@aliou/sh";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { walkCommands, wordToString } from "../utils/shell-utils";
+
+const BACKGROUND_CMD_NAMES = new Set(["nohup", "disown", "setsid"]);
+const BACKGROUND_PATTERN = /&\s*$/;
+const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn", "bun"]);
+const LONG_RUNNING_SCRIPT_NAMES = new Set([
+  "dev",
+  "start",
+  "serve",
+  "preview",
+  "watch",
+]);
+const DIRECT_LONG_RUNNING_COMMANDS = new Set([
+  "vite",
+  "nodemon",
+  "webpack-dev-server",
+  "uvicorn",
+  "foreman",
+  "honcho",
+]);
+const SHELL_LAUNCHERS = new Set(["bash", "sh", "zsh", "fish"]);
+const FOLLOW_FLAGS = new Set(["-f", "--follow"]);
+const WATCH_FLAGS = new Set([
+  "--watch",
+  "--watchall",
+  "--watch-all",
+  "--watchfiles",
+  "--reload",
+]);
+const DETACH_FLAGS = new Set(["-d", "--detach"]);
+const SUSPICIOUS_SCRIPT_NAME =
+  /(^|[-_.])(dev|serve|server|start|watch|tail|logs?|port[-_]?forward|preview)([-_.]|$)/i;
+
+export interface ManagedCommandDecision {
+  kind: "background" | "long_running";
+  suggestedName: string;
+}
+
+export function analyzeManagedCommand(
+  command: string,
+): ManagedCommandDecision | undefined {
+  try {
+    const { ast } = parse(command);
+
+    for (const stmt of ast.body) {
+      if (stmt.background) {
+        return {
+          kind: "background",
+          suggestedName:
+            findFirstCommandName(command, ast) ?? "background-process",
+        };
+      }
+    }
+
+    let decision: ManagedCommandDecision | undefined;
+    walkCommands(ast, (cmd) => {
+      const words = cmd.words?.map(wordToString).filter(Boolean) ?? [];
+      if (words.length === 0) return false;
+
+      decision = classifySimpleCommand(words);
+      return decision !== undefined;
+    });
+
+    return decision;
+  } catch {
+    return analyzeManagedCommandFallback(command);
+  }
+}
+
+export function setupBackgroundBlocker(pi: ExtensionAPI): void {
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName !== "bash") return;
+
+    const command = String(event.input.command ?? "");
+    const decision = analyzeManagedCommand(command);
+
+    if (!decision) return;
+
+    const isBackground = decision.kind === "background";
+    ctx.ui?.notify(
+      isBackground
+        ? "Blocked background command. Use process instead."
+        : "Blocked long-running command. Use process instead.",
+      "warning",
+    );
+
+    const example = `process({ action: "start", name: "${decision.suggestedName}", command: ${JSON.stringify(command)} })`;
+
+    return {
+      block: true,
+      reason: isBackground
+        ? `This bash command tries to run in the background. Use the process tool instead. Example: ${example}`
+        : `This bash command looks long-running and would block the conversation. Use the process tool instead. Example: ${example}`,
+    };
+  });
+}
+
+function classifySimpleCommand(
+  words: string[],
+): ManagedCommandDecision | undefined {
+  const [rawName, ...rawArgs] = words;
+  const name = basename(rawName).toLowerCase();
+  const args = rawArgs.map((arg) => arg.toLowerCase());
+
+  if (BACKGROUND_CMD_NAMES.has(name)) {
+    return {
+      kind: "background",
+      suggestedName: suggestProcessName(words),
+    };
+  }
+
+  if (isLongRunningCommand(rawName, rawArgs, name, args)) {
+    return {
+      kind: "long_running",
+      suggestedName: suggestProcessName(words),
+    };
+  }
+
+  return undefined;
+}
+
+function isLongRunningCommand(
+  rawName: string,
+  rawArgs: string[],
+  name: string,
+  args: string[],
+): boolean {
+  if (PACKAGE_MANAGERS.has(name)) {
+    const scriptName = getPackageManagerScript(args);
+    if (
+      (scriptName !== undefined && LONG_RUNNING_SCRIPT_NAMES.has(scriptName)) ||
+      hasAnyArg(args, WATCH_FLAGS)
+    ) {
+      return true;
+    }
+
+    if ((args[0] === "exec" || args[0] === "dlx") && rawArgs[1]) {
+      const execName = basename(rawArgs[1]).toLowerCase();
+      const execArgs = rawArgs.slice(2);
+      return isLongRunningCommand(
+        rawArgs[1],
+        execArgs,
+        execName,
+        execArgs.map((arg) => arg.toLowerCase()),
+      );
+    }
+
+    return false;
+  }
+
+  if (DIRECT_LONG_RUNNING_COMMANDS.has(name)) return true;
+
+  if (name === "next") return args[0] === "dev" || args[0] === "start";
+  if (name === "astro") return args[0] === "dev" || args[0] === "preview";
+  if (name === "webpack") return args.includes("serve");
+  if (name === "cargo") return args[0] === "watch";
+  if (name === "tail" || name === "journalctl") {
+    return hasAnyArg(args, FOLLOW_FLAGS);
+  }
+  if (name === "kubectl") {
+    return (
+      args[0] === "port-forward" ||
+      (args[0] === "logs" && hasAnyArg(args, FOLLOW_FLAGS))
+    );
+  }
+  if (name === "docker-compose") {
+    return args.includes("up") && !hasAnyArg(args, DETACH_FLAGS);
+  }
+  if (name === "docker") {
+    return (
+      args[0] === "compose" &&
+      args.includes("up") &&
+      !hasAnyArg(args, DETACH_FLAGS)
+    );
+  }
+  if (name === "ssh") return hasSshNoCommandFlag(rawArgs);
+  if (name === "python" || name === "python3") {
+    return args[0] === "-m" && args[1] === "http.server";
+  }
+  if (name === "vitest" || name === "jest") {
+    return hasAnyArg(args, WATCH_FLAGS);
+  }
+  if (name === "rails") return args[0] === "server" || args[0] === "s";
+
+  return (
+    looksLikeSuspiciousScript(rawName) ||
+    (SHELL_LAUNCHERS.has(name) && looksLikeSuspiciousScript(args[0]))
+  );
+}
+
+function getPackageManagerScript(args: string[]): string | undefined {
+  if (args.length === 0) return undefined;
+  if (args[0] === "run" || args[0] === "exec" || args[0] === "dlx") {
+    return args[1];
+  }
+  return args[0];
+}
+
+function hasSshNoCommandFlag(args: string[]): boolean {
+  return args.some((arg) => /^-[^-]*N/.test(arg));
+}
+
+function hasAnyArg(args: string[], values: Set<string>): boolean {
+  return args.some((arg) => values.has(arg));
+}
+
+function suggestProcessName(words: string[]): string {
+  const [rawName, ...rawArgs] = words;
+  const name = basename(rawName).toLowerCase();
+  const args = rawArgs.map((arg) => arg.toLowerCase());
+
+  if (PACKAGE_MANAGERS.has(name)) {
+    const scriptName = getPackageManagerScript(args);
+    if (scriptName) return sanitizeProcessName(scriptName);
+  }
+
+  if (name === "docker" || name === "docker-compose") return "compose";
+  if (name === "kubectl" && args[0] === "port-forward") return "port-forward";
+  if (name === "tail" || name === "journalctl") return "logs";
+  if (SHELL_LAUNCHERS.has(name) && rawArgs[0]) {
+    const scriptName = sanitizeProcessName(rawArgs[0]);
+    if (scriptName !== "process") return scriptName;
+  }
+
+  return sanitizeProcessName(rawName);
+}
+
+function sanitizeProcessName(value: string): string {
+  const withoutExt = basename(value).replace(/\.(sh|bash|zsh|fish)$/i, "");
+  const cleaned = withoutExt
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return cleaned || "process";
+}
+
+function looksLikeSuspiciousScript(value: string | undefined): boolean {
+  if (!value) return false;
+  return SUSPICIOUS_SCRIPT_NAME.test(basename(value));
+}
+
+function analyzeManagedCommandFallback(
+  command: string,
+): ManagedCommandDecision | undefined {
+  if (BACKGROUND_PATTERN.test(command)) {
+    return {
+      kind: "background",
+      suggestedName: "background-process",
+    };
+  }
+
+  const lower = command.toLowerCase();
+  if (
+    /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|preview|watch)\b/.test(
+      lower,
+    ) ||
+    /\bdocker(?:-compose|\s+compose)\s+up\b/.test(lower) ||
+    /\bkubectl\s+port-forward\b/.test(lower) ||
+    /\b(?:tail|journalctl)\b.*(?:\s-f\b|\s-F\b|--follow\b)/.test(lower)
+  ) {
+    return {
+      kind: "long_running",
+      suggestedName: "process",
+    };
+  }
+
+  return undefined;
+}
+
+function findFirstCommandName(
+  command: string,
+  ast: Program,
+): string | undefined {
+  let suggested: string | undefined;
+
+  walkCommands(ast, (cmd) => {
+    const words = cmd.words?.map(wordToString).filter(Boolean) ?? [];
+    if (words.length === 0) return false;
+    suggested = suggestProcessName(words);
+    return true;
+  });
+
+  return suggested ?? sanitizeProcessName(command);
+}

package/src/hooks/cleanup.ts

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

package/src/hooks/index.ts

@@ -0,0 +1,24 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ResolvedProcessesConfig } from "../config";
+import type { ProcessManager } from "../manager";
+import { setupBackgroundBlocker } from "./background-blocker";
+import { setupCleanupHook } from "./cleanup";
+import { setupMessageRenderer } from "./message-renderer";
+import { setupProcessEndHook } from "./process-end";
+import { setupStatusWidget } from "./status-widget";
+
+export function setupProcessesHooks(
+  pi: ExtensionAPI,
+  manager: ProcessManager,
+  config: ResolvedProcessesConfig,
+): void {
+  setupCleanupHook(pi, manager);
+  setupProcessEndHook(pi, manager);
+  setupStatusWidget(pi, manager);
+
+  if (config.interception.blockBackgroundCommands) {
+    setupBackgroundBlocker(pi);
+  }
+
+  setupMessageRenderer(pi);
+}

package/src/hooks/message-renderer.ts

@@ -0,0 +1,83 @@
+import type {
+  ExtensionAPI,
+  MessageRenderOptions,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/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);
+    },
+  );
+}

package/src/hooks/process-end.ts

@@ -0,0 +1,86 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { MESSAGE_TYPE_PROCESS_UPDATE, type ProcessInfo } from "../constants";
+import type { ProcessManager } from "../manager";
+import { formatRuntime, stripAnsi, truncateCmd } from "../utils";
+
+interface ProcessUpdateDetails {
+  processId: string;
+  processName: string;
+  command: string;
+  status: "exited" | "killed";
+  exitCode: number | null;
+  success: boolean;
+  runtime: string;
+}
+
+export function setupProcessEndHook(pi: ExtensionAPI, manager: ProcessManager) {
+  manager.onEvent((event) => {
+    if (event.type !== "process_ended") return;
+
+    // Tool-initiated kills already return a tool result. Do not enqueue a
+    // custom message while the agent is streaming; even triggerTurn=false would
+    // otherwise be delivered as steering by Pi.
+    if (!event.triggerAgentTurn) return;
+
+    const info: ProcessInfo = event.info;
+    const runtime = formatRuntime(info.startTime, info.endTime);
+
+    // Build message
+    let summary: string;
+
+    if (info.status === "killed") {
+      summary = `Process "${info.name}" (${info.id}) was terminated after ${runtime}.`;
+    } else if (info.success) {
+      summary = `Process "${info.name}" (${info.id}) completed successfully after ${runtime}.`;
+    } else {
+      summary = `Process "${info.name}" (${info.id}) crashed with exit code ${info.exitCode ?? "?"} after ${runtime}.`;
+    }
+
+    const message = buildAgentMessage(summary, info, manager);
+
+    // Send the message to the conversation - displayed via custom renderer in UI.
+    const details: ProcessUpdateDetails = {
+      processId: info.id,
+      processName: info.name,
+      command: info.command,
+      status: info.status as "exited" | "killed",
+      exitCode: info.exitCode,
+      success: info.success ?? false,
+      runtime,
+    };
+
+    pi.sendMessage(
+      {
+        customType: MESSAGE_TYPE_PROCESS_UPDATE,
+        content: message,
+        display: true,
+        details,
+      },
+      { triggerTurn: true, deliverAs: "steer" },
+    );
+  });
+}
+
+function buildAgentMessage(
+  summary: string,
+  info: ProcessInfo,
+  manager: ProcessManager,
+): string {
+  const lines = [summary, `Command: ${truncateCmd(info.command, 160)}`];
+
+  const recentOutput = manager.getCombinedOutput(info.id, 20) ?? [];
+  if (recentOutput.length > 0) {
+    lines.push("", "Recent output:");
+    for (const line of recentOutput) {
+      const prefix = line.type === "stderr" ? "stderr" : "stdout";
+      lines.push(`${prefix}: ${truncateCmd(stripAnsi(line.text), 500)}`);
+    }
+  }
+
+  lines.push(
+    "",
+    "This is the automatic process-end notification. Do not call process list/output/logs just to check whether it finished; use process output once only if you need more logs for debugging.",
+  );
+
+  return lines.join("\n");
+}

package/src/hooks/status-widget.ts

@@ -0,0 +1,65 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { ProcessInfo } from "../constants";
+import type { ProcessManager } from "../manager";
+
+const STATUS_WIDGET_ID = "processes-status";
+
+function renderStatusWidget(
+  processes: ProcessInfo[],
+  theme: ExtensionContext["ui"]["theme"],
+): string[] {
+  if (processes.length === 0) return [];
+
+  const activeCount = processes.filter(
+    (process) =>
+      process.status === "running" ||
+      process.status === "terminating" ||
+      process.status === "terminate_timeout",
+  ).length;
+  const finishedCount = processes.length - activeCount;
+
+  const line =
+    theme.fg("dim", "processes: ") +
+    theme.fg("accent", String(activeCount)) +
+    theme.fg("dim", " active") +
+    theme.fg("dim", " | ") +
+    theme.fg("dim", String(finishedCount)) +
+    theme.fg("dim", " finished");
+
+  return [line];
+}
+
+export function setupStatusWidget(
+  pi: ExtensionAPI,
+  manager: ProcessManager,
+): void {
+  let latestContext: ExtensionContext | null = null;
+
+  const updateWidget = (): void => {
+    if (!latestContext?.hasUI) return;
+
+    const processes = manager.list();
+    if (processes.length === 0) {
+      latestContext.ui.setWidget(STATUS_WIDGET_ID, undefined);
+      return;
+    }
+
+    latestContext.ui.setWidget(
+      STATUS_WIDGET_ID,
+      renderStatusWidget(processes, latestContext.ui.theme),
+      { placement: "belowEditor" },
+    );
+  };
+
+  manager.onEvent(() => {
+    updateWidget();
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    latestContext = ctx;
+    updateWidget();
+  });
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { setupProcessesCommands } from "./commands";
+import { configLoader } from "./config";
+import { setupProcessesHooks } from "./hooks";
+import { ProcessManager } from "./manager";
+import { setupProcessesTools } from "./tools";
+
+export default async function (pi: ExtensionAPI) {
+  if (process.platform === "win32") {
+    pi.on("session_start", async (_event, ctx) => {
+      if (!ctx.hasUI) return;
+      ctx.ui.notify("processes extension not available on Windows", "warning");
+    });
+    return;
+  }
+
+  await configLoader.load();
+  const manager = new ProcessManager({
+    getConfiguredShellPath: () => configLoader.getConfig().execution.shellPath,
+  });
+
+  setupProcessesHooks(pi, manager, configLoader.getConfig());
+  setupProcessesCommands(pi, manager);
+  setupProcessesTools(pi, manager);
+}