@aliou/pi-processes 0.9.4 → 0.10.0

package/extensions/processes/hooks/background-blocker.ts

@@ -0,0 +1,201 @@
+/**
+ * Background command blocker.
+ *
+ * Listens for bash tool calls and blocks commands that contain
+ * shell background patterns (trailing &, nohup, disown, setsid).
+ *
+ * Uses @aliou/sh to parse commands into an AST and walk all
+ * SimpleCommand nodes, checking for:
+ * - Statement.background (trailing &)
+ * - Command name matching nohup/disown/setsid
+ *
+ * Registered only when config.interception.blockBackgroundCommands is enabled.
+ * Returns a blocking reason that tells the agent to use the process tool instead.
+ */
+
+import type {
+  Command,
+  Program,
+  SimpleCommand,
+  Statement,
+  Word,
+} from "@aliou/sh";
+import { parse } from "@aliou/sh";
+import type {
+  BashToolCallEvent,
+  ExtensionAPI,
+  ToolCallEventResult,
+} from "@earendil-works/pi-coding-agent";
+
+import { t } from "../i18n";
+
+const BACKGROUND_KEYWORDS = new Set(["nohup", "disown", "setsid"]);
+
+/**
+ * Extract the literal command name from a Word node.
+ * Returns the value of the first Literal part, or undefined if
+ * the word starts with a non-literal (e.g., variable expansion).
+ */
+function getCommandName(word: Word): string | undefined {
+  const firstPart = word.parts?.[0];
+  if (firstPart?.type === "Literal") {
+    return firstPart.value;
+  }
+  return undefined;
+}
+
+/**
+ * Check if a SimpleCommand's name matches a background keyword.
+ */
+function isBackgroundSimpleCommand(cmd: SimpleCommand): boolean {
+  const firstName = cmd.words?.[0] ? getCommandName(cmd.words[0]) : undefined;
+  return firstName !== undefined && BACKGROUND_KEYWORDS.has(firstName);
+}
+
+/**
+ * Recursively walk a Command AST, returning true if any branch
+ * contains a background pattern (trailing & or background keyword).
+ */
+function walkCommand(command: Command, isBg: { value: boolean }): void {
+  switch (command.type) {
+    case "SimpleCommand":
+      if (isBackgroundSimpleCommand(command)) {
+        isBg.value = true;
+      }
+      break;
+
+    case "Pipeline":
+      for (const stmt of command.commands ?? []) {
+        walkStatement(stmt, isBg);
+        if (isBg.value) return;
+      }
+      break;
+
+    case "Logical":
+      walkStatement(command.left, isBg);
+      if (isBg.value) return;
+      walkStatement(command.right, isBg);
+      break;
+
+    case "Subshell":
+    case "Block":
+      for (const stmt of command.body ?? []) {
+        walkStatement(stmt, isBg);
+        if (isBg.value) return;
+      }
+      break;
+
+    case "IfClause":
+      for (const stmt of command.cond ?? []) {
+        walkStatement(stmt, isBg);
+        if (isBg.value) return;
+      }
+      for (const stmt of command.then ?? []) {
+        walkStatement(stmt, isBg);
+        if (isBg.value) return;
+      }
+      for (const stmt of command.else ?? []) {
+        walkStatement(stmt, isBg);
+        if (isBg.value) return;
+      }
+      break;
+
+    case "WhileClause":
+    case "ForClause":
+    case "SelectClause":
+    case "CStyleLoop":
+      for (const stmt of command.body ?? []) {
+        walkStatement(stmt, isBg);
+        if (isBg.value) return;
+      }
+      break;
+
+    case "FunctionDecl":
+      for (const stmt of command.body ?? []) {
+        walkStatement(stmt, isBg);
+        if (isBg.value) return;
+      }
+      break;
+
+    case "CaseClause":
+      for (const item of command.items ?? []) {
+        for (const stmt of item.body ?? []) {
+          walkStatement(stmt, isBg);
+          if (isBg.value) return;
+        }
+      }
+      break;
+
+    default:
+      // TimeClause, TestClause, ArithCmd, CoprocClause, DeclClause, LetClause:
+      // these don't carry SimpleCommands that are background indicators.
+      break;
+  }
+}
+
+function walkStatement(stmt: Statement, isBg: { value: boolean }): void {
+  if (stmt.background) {
+    isBg.value = true;
+    return;
+  }
+  if (stmt.command) {
+    walkCommand(stmt.command, isBg);
+  }
+}
+
+/**
+ * Check if a command string contains background execution patterns.
+ * Returns true if the command should be blocked.
+ *
+ * Uses @aliou/sh to parse the command into an AST. If the command
+ * cannot be parsed (syntax error), falls back to a simple regex
+ * heuristic for trailing &.
+ */
+export function isBackgroundCommand(command: string): boolean {
+  let program: Program;
+
+  try {
+    const result = parse(command);
+    program = result.ast;
+  } catch {
+    // Fallback: if the command can't be parsed (syntax error),
+    // use a simple regex heuristic for trailing &.
+    return /\s*&\s*$/.test(command);
+  }
+
+  const isBg = { value: false };
+
+  for (const stmt of program.body ?? []) {
+    walkStatement(stmt, isBg);
+    if (isBg.value) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Register the background command blocker on the tool_call event.
+ *
+ * The blocker only activates when the provided isEnabled callback returns true.
+ * pi.on() does not return a disposer, so cleanup is handled by session_shutdown.
+ */
+export function registerBackgroundBlocker(
+  pi: ExtensionAPI,
+  isEnabled: () => boolean,
+): void {
+  pi.on("tool_call", (event) => {
+    if (!isEnabled()) return;
+
+    if (event.toolName !== "bash") return;
+
+    const bashEvent = event as BashToolCallEvent;
+    const command = bashEvent.input.command;
+
+    if (isBackgroundCommand(command)) {
+      return {
+        block: true,
+        reason: t("process.blocker.background_command"),
+      } satisfies ToolCallEventResult;
+    }
+  });
+}

package/extensions/processes/hooks/cleanup.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { ProcessManager } from "../../../src/manager";
+import type { NotificationRegistry } from "../notifications/registry";
+
+interface NotificationService {
+  dispose(): void;
+}
+
+type Disposer = () => void;
+
+interface CleanupHookDeps {
+  manager: ProcessManager;
+  notifications: NotificationRegistry;
+  notificationService: NotificationService;
+  disposers?: Disposer[];
+  disposeOverlays?: () => void;
+}
+
+export function registerCleanupHook(
+  pi: ExtensionAPI,
+  deps: CleanupHookDeps,
+): void {
+  let shuttingDown = false;
+
+  pi.on("session_shutdown", async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    // Close any open overview panels first so they stop listening to events
+    // before the manager and protocol handlers are torn down.
+    deps.disposeOverlays?.();
+
+    for (const dispose of deps.disposers ?? []) {
+      dispose();
+    }
+
+    deps.notificationService.dispose();
+    deps.notifications.clear();
+    deps.manager.killAll();
+    deps.manager.cleanup();
+  });
+}

package/extensions/processes/hooks/event-bridge.ts

@@ -0,0 +1,32 @@
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+
+import type { ProcessManager } from "../../../src/manager";
+import { CHANNELS } from "../../../src/protocol";
+
+export function registerEventBridge(
+  events: EventBus,
+  manager: ProcessManager,
+): () => void {
+  return manager.onEvent((event) => {
+    switch (event.type) {
+      case "process_started":
+        events.emit(CHANNELS.STARTED, event.info);
+        events.emit(CHANNELS.CHANGED, { reason: "started" });
+        break;
+      case "process_ended":
+        events.emit(CHANNELS.ENDED, event.info);
+        events.emit(CHANNELS.CHANGED, { reason: "ended" });
+        break;
+      case "process_output_changed":
+        events.emit(CHANNELS.OUTPUT_CHANGED, {
+          id: event.id,
+          appendedText: event.appendedText,
+          droppedLines: event.droppedLines,
+        });
+        break;
+      case "processes_changed":
+        events.emit(CHANNELS.CHANGED, { reason: "cleared" });
+        break;
+    }
+  });
+}

package/extensions/processes/i18n/index.ts

@@ -0,0 +1,3 @@
+export type { MessageKey } from "./messages";
+export type { Translator } from "./translator";
+export { createTranslator, t } from "./translator";

package/extensions/processes/i18n/messages.ts

@@ -0,0 +1,27 @@
+export type MessageKey =
+  | "process.list.empty"
+  | "process.list.summary"
+  | "process.stop.not_found"
+  | "process.stop.timeout"
+  | "process.status.running"
+  | "process.status.terminating"
+  | "process.status.terminate_timeout"
+  | "process.status.exited"
+  | "process.status.killed"
+  | "process.status.failed"
+  | "process.blocker.background_command";
+
+export const ENGLISH: Record<MessageKey, string> = {
+  "process.list.empty": "No running processes",
+  "process.list.summary": "{count} process{count_plural}",
+  "process.stop.not_found": "Process not found: {id}",
+  "process.stop.timeout": "Process kill timed out: {id}",
+  "process.status.running": "running",
+  "process.status.terminating": "terminating",
+  "process.status.terminate_timeout": "terminate timeout",
+  "process.status.exited": "exited ({exitCode})",
+  "process.status.killed": "killed",
+  "process.status.failed": "failed ({errorMessage})",
+  "process.blocker.background_command":
+    "Shell background patterns (&, nohup, disown, setsid) are not allowed. Use the process tool to manage background commands.",
+};

package/extensions/processes/i18n/translator.ts

@@ -0,0 +1,49 @@
+import type { MessageKey } from "./messages";
+import { ENGLISH } from "./messages";
+
+export type { MessageKey } from "./messages";
+
+export type Translator = (
+  key: MessageKey,
+  params?: Record<string, unknown>,
+) => string;
+
+function pluralize(count: number): string {
+  return count === 1 ? "" : "es";
+}
+
+function formatTemplate(
+  template: string,
+  params: Record<string, unknown>,
+): string {
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    if (key === "count_plural") {
+      const count = Number(params.count) || 0;
+      return pluralize(count);
+    }
+    return String(params[key] ?? match);
+  });
+}
+
+/**
+ * Create a translator with optional overrides.
+ *
+ * Overrides map message keys to custom strings. Unoverridden keys
+ * fall back to English defaults.
+ */
+export function createTranslator(
+  overrides?: Partial<Record<MessageKey, string>>,
+): Translator {
+  const strings = { ...ENGLISH, ...overrides };
+
+  return (key, params) => {
+    const template = strings[key] ?? ENGLISH[key] ?? key;
+    if (!params) return template;
+    return formatTemplate(template, params);
+  };
+}
+
+/**
+ * Default translator with English fallbacks. No overrides.
+ */
+export const t: Translator = createTranslator();

package/extensions/processes/index.ts

@@ -0,0 +1,109 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getManager } from "../../src/get-manager";
+import { isWindowsPlatform } from "../../src/utils/platform";
+import { registerClearCommand } from "./commands/clear";
+import { registerKillCommand } from "./commands/kill";
+import { registerOverviewCommand } from "./commands/overview";
+import { configLoader, drainImportMessages, loadProcessConfig } from "./config";
+import { registerCommandHandlers } from "./handlers/commands";
+import { registerNotificationDelivery } from "./handlers/notifications";
+import { registerRequestHandlers } from "./handlers/requests";
+import { registerLogSubscriptions } from "./handlers/subscriptions";
+import { registerBackgroundBlocker } from "./hooks/background-blocker";
+import { registerCleanupHook } from "./hooks/cleanup";
+import { registerEventBridge } from "./hooks/event-bridge";
+import { registerProcessNotificationRenderer } from "./message-renderer";
+import {
+  createNotificationRegistry,
+  createNotificationService,
+} from "./notifications/service";
+import { registerProcessSettings } from "./settings";
+import { registerProcessTool } from "./tools";
+
+export default async function processesExtension(
+  pi: ExtensionAPI,
+): Promise<void> {
+  if (isWindowsPlatform()) {
+    // POSIX-only: the manager relies on detached process groups and
+    // negative-pid group kill (src/utils/process-group.ts), neither of
+    // which exists on Windows. Bail before touching the config or spawning.
+    pi.on("session_start", (_event, ctx) => {
+      if (!ctx.hasUI) return;
+      ctx.ui.notify(
+        "The pi-processes extension is not available on Windows.",
+        "warning",
+      );
+    });
+    return;
+  }
+
+  await loadProcessConfig();
+  registerMigrationMessageNotifications(pi);
+
+  const manager = getManager({
+    getConfiguredShellPath: () => configLoader.getConfig().execution.shellPath,
+  });
+  const notifications = createNotificationRegistry();
+  const notificationService = createNotificationService({
+    events: pi.events,
+    manager,
+    registry: notifications,
+    getProcess: (id) => manager.get(id),
+  });
+
+  const getConfig = () => configLoader.getConfig();
+
+  const openOverlays = new Set<{ dispose: () => void }>();
+  const registerOverlay = (overlay: { dispose: () => void }) => {
+    openOverlays.add(overlay);
+    return () => openOverlays.delete(overlay);
+  };
+
+  const disposers = [
+    registerEventBridge(pi.events, manager),
+    registerRequestHandlers(pi.events, manager, getConfig),
+    registerCommandHandlers(pi.events, manager, notifications),
+    registerLogSubscriptions(pi.events, manager),
+    registerNotificationDelivery(pi.events, pi),
+  ];
+
+  registerBackgroundBlocker(
+    pi,
+    () => getConfig().interception.blockBackgroundCommands,
+  );
+
+  registerProcessNotificationRenderer(pi);
+  registerProcessTool(pi, manager, notifications);
+  registerProcessSettings(pi);
+  registerOverviewCommand(pi, { events: pi.events, registerOverlay });
+  registerKillCommand(pi);
+  registerClearCommand(pi);
+
+  registerCleanupHook(pi, {
+    manager,
+    notifications,
+    notificationService,
+    disposers,
+    disposeOverlays: () => {
+      for (const overlay of [...openOverlays]) overlay.dispose();
+      openOverlays.clear();
+    },
+  });
+}
+
+function registerMigrationMessageNotifications(pi: ExtensionAPI): void {
+  pi.on("session_start", (_event, ctx) => {
+    const messages = [
+      ...drainImportMessages(),
+      ...configLoader.drainMessages(),
+    ];
+    if (messages.length === 0) return;
+
+    const formattedMessages = messages.map((m) => `- ${m}`);
+
+    const message = `[processes]\n${formattedMessages.join("\n")}`;
+    if (ctx.hasUI) {
+      ctx.ui.notify(message, "info");
+    }
+  });
+}

package/extensions/processes/message-renderer.ts

@@ -0,0 +1,117 @@
+import type {
+  ExtensionAPI,
+  MessageRenderOptions,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import { type Component, Container, Text } from "@earendil-works/pi-tui";
+
+import { MESSAGE_TYPE_PROCESS_NOTIFICATION } from "./constants";
+import type { ProcessNotificationDetails } from "./notifications/types";
+import { truncateToWidth } from "./utils/truncate";
+
+export function registerProcessNotificationRenderer(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer<ProcessNotificationDetails>(
+    MESSAGE_TYPE_PROCESS_NOTIFICATION,
+    renderProcessNotificationMessage,
+  );
+}
+
+export function renderProcessNotificationMessage(
+  message: { details?: ProcessNotificationDetails },
+  options: MessageRenderOptions,
+  theme: Theme,
+): Component | undefined {
+  const details = message.details;
+  if (!details) {
+    return undefined;
+  }
+
+  const container = new Container();
+  container.addChild(new Text(formatSummary(details, theme), 0, 0));
+
+  if (options.expanded) {
+    container.addChild(new Text(formatDetailLine(details, theme), 0, 1));
+  }
+
+  return container;
+}
+
+function formatSummary(
+  details: ProcessNotificationDetails,
+  theme: Theme,
+): string {
+  const prefix = theme.fg("accent", "[process]");
+  const name = theme.fg("muted", `"${details.processName}"`);
+
+  if (details.logMatch) {
+    const line = truncateToWidth(details.logMatch.line, 160, "…");
+    return `${prefix} ${name} matched ${details.logMatch.stream}: ${line}`;
+  }
+
+  if (details.kind === "killed" && details.signal) {
+    const number =
+      details.signal.number === null ? "" : ` (${details.signal.number})`;
+    return `${prefix} ${name} killed by ${details.signal.name}${number}`;
+  }
+
+  const severity = colorKind(details.kind, theme, summaryVerb(details));
+  return `${prefix} ${name} ${severity}`;
+}
+
+function formatDetailLine(
+  details: ProcessNotificationDetails,
+  theme: Theme,
+): string {
+  const parts = [
+    `id: ${details.processId}`,
+    `attention: ${details.attention}`,
+    details.status ? `status: ${details.status}` : null,
+    details.exitCode === undefined || details.exitCode === null
+      ? null
+      : `exit: ${details.exitCode}`,
+    details.endReason ? `reason: ${details.endReason}` : null,
+  ].filter(Boolean);
+
+  return theme.fg("muted", parts.join("  "));
+}
+
+function summaryVerb(details: ProcessNotificationDetails): string {
+  if (details.summary) {
+    return details.summary;
+  }
+
+  switch (details.kind) {
+    case "success":
+      return "succeeded";
+    case "failure":
+    case "crash":
+      return details.exitCode === null || details.exitCode === undefined
+        ? "failed"
+        : `failed exit(${details.exitCode})`;
+    case "killed":
+      return "killed";
+    case "log_match":
+      return "matched log output";
+    case "log_match_suppressed":
+      return "suppressed repeated log matches";
+  }
+}
+
+function colorKind(
+  kind: ProcessNotificationDetails["kind"],
+  theme: Theme,
+  text: string,
+): string {
+  switch (kind) {
+    case "success":
+      return theme.fg("success", text);
+    case "killed":
+      return theme.fg("warning", text);
+    case "failure":
+    case "crash":
+      return theme.fg("error", text);
+    case "log_match":
+    case "log_match_suppressed":
+      return theme.fg("accent", text);
+  }
+}

package/extensions/processes/notification-sender.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { MESSAGE_TYPE_PROCESS_NOTIFICATION } from "./constants";
+import { buildProcessNotificationContent } from "./notifications/render-content";
+import type {
+  Attention,
+  ProcessNotificationDetails,
+} from "./notifications/types";
+
+export interface ProcessNotificationSendOptions {
+  triggerTurn: boolean;
+  deliverAs: "steer" | "followUp" | "nextTurn";
+}
+
+/** Maps a notification attention level to Pi send-message options. */
+export function attentionToSendOptions(
+  attention: Attention,
+): ProcessNotificationSendOptions {
+  switch (attention) {
+    case "turn":
+      return { triggerTurn: true, deliverAs: "steer" };
+    case "context":
+      return { triggerTurn: false, deliverAs: "steer" };
+    case "ignore":
+      return { triggerTurn: false, deliverAs: "steer" };
+  }
+}
+
+export function sendProcessNotificationMessage(
+  pi: ExtensionAPI,
+  details: ProcessNotificationDetails,
+  options: ProcessNotificationSendOptions,
+): void {
+  pi.sendMessage<ProcessNotificationDetails>(
+    {
+      customType: MESSAGE_TYPE_PROCESS_NOTIFICATION,
+      content: buildProcessNotificationContent(details),
+      display: true,
+      details,
+    },
+    options,
+  );
+}

package/extensions/processes/notifications/classify.ts

@@ -0,0 +1,27 @@
+import type { ProcessInfo } from "../../../src/types";
+import type { ProcessNotificationKind } from "./types";
+
+/**
+ * Classify a process end into a notification kind.
+ *
+ * A kill that times out is never classified here: `terminate_timeout` never
+ * reaches `process_ended` (the kill path sets `endTime` and transitions without
+ * emitting, and the close handler bails on the `endTime` guard). The stop tool
+ * carries the timeout via `KillResult.reason: "timeout"` instead.
+ */
+export function classifyProcessEnd(info: ProcessInfo): ProcessNotificationKind {
+  if (info.status === "killed") return "killed";
+  if (info.success === true) return "success";
+
+  if (
+    info.endReason === "spawn_error" ||
+    info.endReason === "missing_pid" ||
+    info.endReason === "lost"
+  ) {
+    return "crash";
+  }
+
+  if (info.exitCode !== null && info.exitCode !== 0) return "crash";
+
+  return "failure";
+}