@aliou/pi-processes 0.9.5 → 0.10.0

package/src/config.ts

@@ -1,107 +0,0 @@
-/**
- * Configuration for the processes extension.
- *
- * Global: ~/.pi/agent/extensions/process.json
- * Memory: ephemeral overrides via /ps:settings
- */
-
-import { ConfigLoader } from "@aliou/pi-utils-settings";
-import type { ProcessesKeybindings } from "./utils/keybindings";
-import { DEFAULT_KEYBINDINGS } from "./utils/keybindings";
-
-export interface ProcessesConfig {
-  processList?: {
-    /** Max visible processes in the /ps 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;
-  };
-  execution?: {
-    /** Absolute shell path override. Leave unset to auto-resolve. */
-    shellPath?: string;
-  };
-  widget?: {
-    /** Show the status widget below the editor. */
-    showStatusWidget?: boolean;
-    /** Default dock state when follow mode is enabled. */
-    dockDefaultState?: "hidden" | "collapsed";
-    /** Height of the dock in lines when open. */
-    dockHeight?: number;
-  };
-  follow?: {
-    /** Enable follow mode by default when starting processes. */
-    enabledByDefault?: boolean;
-    /** Auto-hide dock when all processes finish. */
-    autoHideOnFinish?: boolean;
-  };
-  keybindings?: Partial<ProcessesKeybindings>;
-  interception?: {
-    /** Block background bash commands (&, nohup, disown, setsid) and guide the model to use the process tool. */
-    blockBackgroundCommands?: boolean;
-  };
-}
-
-export interface ResolvedProcessesConfig {
-  processList: {
-    maxVisibleProcesses: number;
-    maxPreviewLines: number;
-  };
-  output: {
-    defaultTailLines: number;
-    maxOutputLines: number;
-  };
-  execution: {
-    shellPath?: string;
-  };
-  widget: {
-    showStatusWidget: boolean;
-    dockDefaultState: "hidden" | "collapsed";
-    dockHeight: number;
-  };
-  follow: {
-    enabledByDefault: boolean;
-    autoHideOnFinish: boolean;
-  };
-  keybindings: ProcessesKeybindings;
-  interception: {
-    blockBackgroundCommands: boolean;
-  };
-}
-
-const DEFAULT_CONFIG: ResolvedProcessesConfig = {
-  processList: {
-    maxVisibleProcesses: 8,
-    maxPreviewLines: 12,
-  },
-  output: {
-    defaultTailLines: 100,
-    maxOutputLines: 200,
-  },
-  execution: {},
-  widget: {
-    showStatusWidget: false,
-    dockDefaultState: "collapsed",
-    dockHeight: 12,
-  },
-  follow: {
-    enabledByDefault: true,
-    autoHideOnFinish: true,
-  },
-  keybindings: DEFAULT_KEYBINDINGS,
-  interception: {
-    blockBackgroundCommands: false,
-  },
-};
-
-export const configLoader = new ConfigLoader<
-  ProcessesConfig,
-  ResolvedProcessesConfig
->("process", DEFAULT_CONFIG, {
-  scopes: ["global", "memory"],
-});

package/src/constants/index.ts

@@ -1,16 +0,0 @@
-export type {
-  ExecuteResult,
-  KillResult,
-  LogWatch,
-  LogWatchMatchEvent,
-  LogWatchStream,
-  ManagerEvent,
-  ProcessAction,
-  ProcessesDetails,
-  ProcessInfo,
-  ProcessStatus,
-  StartOptions,
-  WriteResult,
-} from "./types";
-
-export { LIVE_STATUSES, MESSAGE_TYPE_PROCESS_UPDATE } from "./types";

package/src/constants/types.ts

@@ -1,119 +0,0 @@
-// Custom message type for process update notifications
-export const MESSAGE_TYPE_PROCESS_UPDATE = "ad-process:update";
-
-export type ProcessAction =
-  | "start"
-  | "list"
-  | "output"
-  | "logs"
-  | "kill"
-  | "clear"
-  | "write"
-  | "debug_preview";
-
-export type ProcessStatus =
-  | "running"
-  | "terminating"
-  | "terminate_timeout"
-  | "exited"
-  | "killed";
-
-export const LIVE_STATUSES: ReadonlySet<ProcessStatus> = new Set([
-  "running",
-  "terminating",
-  "terminate_timeout",
-]);
-
-export type LogWatchStream = "stdout" | "stderr" | "both";
-
-export interface LogWatch {
-  pattern: string;
-  stream?: LogWatchStream;
-  repeat?: boolean;
-}
-
-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 interface LogWatchMatchEvent {
-  processId: string;
-  processName: string;
-  processCommand: string;
-  source: "stdout" | "stderr";
-  line: string;
-  watch: {
-    index: number;
-    pattern: string;
-    stream: LogWatchStream;
-    repeat: boolean;
-  };
-}
-
-export type ManagerEvent =
-  | { type: "process_started"; info: ProcessInfo }
-  | { type: "process_ended"; info: ProcessInfo }
-  | { type: "process_output_changed"; id: string }
-  | { type: "process_watch_matched"; match: LogWatchMatchEvent }
-  | { type: "processes_changed" };
-
-export type KillResult =
-  | { ok: true; info: ProcessInfo }
-  | { ok: false; info: ProcessInfo; reason: "not_found" | "timeout" | "error" };
-
-export type WriteResult =
-  | { ok: true }
-  | {
-      ok: false;
-      reason: "not_found" | "process_exited" | "stdin_closed" | "write_error";
-    };
-
-export interface StartOptions {
-  alertOnSuccess?: boolean;
-  alertOnFailure?: boolean;
-  alertOnKill?: boolean;
-  logWatches?: LogWatch[];
-}
-
-import type { TruncationDetails } from "../tools/actions/output-truncate";
-
-export interface ProcessesDetails {
-  action: ProcessAction;
-  success: boolean;
-  message: string;
-  process?: ProcessInfo;
-  processes?: ProcessInfo[];
-  /**
-   * Legacy-only raw output arrays retained so historical session results can
-   * still render. New executions must never populate this field; the bounded
-   * preview lives in tool-result `content` and a truncation summary lives in
-   * `truncation`.
-   */
-  output?: { stdout: string[]; stderr: string[]; status: string };
-  logFiles?: { stdoutFile: string; stderrFile: string };
-  /**
-   * Metadata only (no raw output) describing how `content` was bounded.
-   * Present when the body exceeded the byte or line limits.
-   */
-  truncation?: TruncationDetails;
-  cleared?: number;
-}
-
-export interface ExecuteResult {
-  content: Array<{ type: "text"; text: string }>;
-  details: ProcessesDetails;
-}

package/src/hooks/background-blocker.ts

@@ -1,66 +0,0 @@
-/**
- * Blocks background bash commands (e.g. `cmd &`, `nohup cmd`) and guides
- * the model to use the process tool instead.
- *
- * Opt-in via config: `interception.blockBackgroundCommands`.
- */
-
-import { 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*$/;
-
-export function setupBackgroundBlocker(pi: ExtensionAPI): void {
-  pi.on("tool_call", async (event, ctx) => {
-    if (event.toolName !== "bash") return;
-
-    const command = String(event.input.command ?? "");
-
-    let hasBackground = false;
-    try {
-      const { ast } = parse(command);
-
-      // Check statement-level background flag (cmd &)
-      for (const stmt of ast.body) {
-        if (stmt.background) {
-          hasBackground = true;
-          break;
-        }
-      }
-
-      // Check for nohup/disown/setsid as command names
-      if (!hasBackground) {
-        walkCommands(ast, (cmd) => {
-          const name = cmd.words?.[0] ? wordToString(cmd.words[0]) : undefined;
-          if (name && BACKGROUND_CMD_NAMES.has(name)) {
-            hasBackground = true;
-            return true;
-          }
-          return false;
-        });
-      }
-    } catch {
-      // Fallback to regex on parse failure
-      hasBackground = BACKGROUND_PATTERN.test(command);
-    }
-
-    if (hasBackground) {
-      ctx.ui?.notify(
-        "Blocked background command. Use the process tool instead.",
-        "warning",
-      );
-
-      return {
-        block: true,
-        reason:
-          "Background commands (&, nohup, disown, setsid) are not supported in bash. " +
-          'Use the "process" tool with action "start" to run commands in the background. ' +
-          'Example: process({ action: "start", name: "my-server", command: "npm run dev" })',
-      };
-    }
-
-    return;
-  });
-}

package/src/hooks/cleanup.ts

@@ -1,10 +0,0 @@
-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.stopWatcher();
-    manager.shutdownKillAll();
-    manager.cleanup();
-  });
-}

package/src/hooks/index.ts

@@ -1,32 +0,0 @@
-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 { setupProcessWatchHook } from "./process-watch";
-import { type DockActions, setupProcessWidget } from "./widget";
-
-export type { DockActions };
-
-export function setupProcessesHooks(
-  pi: ExtensionAPI,
-  manager: ProcessManager,
-  config: ResolvedProcessesConfig,
-): { update: () => void; dockActions: DockActions } {
-  setupCleanupHook(pi, manager);
-  setupProcessEndHook(pi, manager);
-  setupProcessWatchHook(pi, manager);
-
-  if (config.interception.blockBackgroundCommands) {
-    setupBackgroundBlocker(pi);
-  }
-
-  // Set up widget AFTER process-end so it chains onto the existing callback
-  const widget = setupProcessWidget(pi, manager, config);
-
-  setupMessageRenderer(pi);
-
-  return widget;
-}

package/src/hooks/message-renderer.ts

@@ -1,115 +0,0 @@
-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 ProcessLifecycleDetails {
-  kind?: "lifecycle";
-  processId: string;
-  processName: string;
-  command: string;
-  status: "exited" | "killed";
-  exitCode: number | null;
-  success: boolean;
-  runtime: string;
-}
-
-interface ProcessWatchMatchDetails {
-  kind: "watch_matched";
-  processId: string;
-  processName: string;
-  command: string;
-  source: "stdout" | "stderr";
-  line: string;
-  watch: {
-    index: number;
-    pattern: string;
-    stream: "stdout" | "stderr" | "both";
-    repeat: boolean;
-  };
-}
-
-interface ProcessUpdateMessage {
-  customType: string;
-  content: string | Array<{ type: string; text?: string }>;
-  details?: ProcessLifecycleDetails | ProcessWatchMatchDetails;
-}
-
-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<
-    ProcessLifecycleDetails | ProcessWatchMatchDetails
-  >(
-    MESSAGE_TYPE_PROCESS_UPDATE,
-    (
-      message: ProcessUpdateMessage,
-      _options: MessageRenderOptions,
-      theme: Theme,
-    ) => {
-      const details = message.details;
-
-      if (!details) {
-        return new Text(getContentText(message.content), 0, 0);
-      }
-
-      if (details.kind === "watch_matched") {
-        const streamColor = details.source === "stderr" ? "warning" : "accent";
-        const text =
-          theme.fg("success", "* ") +
-          theme.fg("accent", `"${details.processName}"`) +
-          theme.fg("muted", ` (${details.processId}) `) +
-          theme.fg("success", "watch matched ") +
-          theme.fg("muted", `/${details.watch.pattern}/ `) +
-          theme.fg(streamColor, `[${details.source}]`) +
-          theme.fg("muted", ` ${details.line}`);
-
-        return new Text(text, 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

@@ -1,69 +0,0 @@
-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 } from "../utils";
-import { safeSendMessage } from "./utils";
-
-interface ProcessUpdateDetails {
-  kind: "lifecycle";
-  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;
-
-    const info: ProcessInfo = event.info;
-
-    // Determine if the agent should get a turn to react to this process ending.
-    // When true, the agent receives the message in its context and can respond
-    // (e.g. check results, fix code, restart the process).
-    const triggerAgentTurn =
-      (info.status === "killed" && info.alertOnKill) ||
-      (info.status === "exited" && info.success && info.alertOnSuccess) ||
-      (info.status === "exited" && !info.success && info.alertOnFailure);
-
-    const runtime = formatRuntime(info.startTime, info.endTime);
-
-    // Build message
-    let message: string;
-
-    if (info.status === "killed") {
-      message = `Process '${info.name}' was terminated (${runtime})`;
-    } else if (info.success) {
-      message = `Process '${info.name}' completed successfully (${runtime})`;
-    } else {
-      message = `Process '${info.name}' crashed with exit code ${info.exitCode ?? "?"} (${runtime})`;
-    }
-
-    // Send the message to the conversation - displayed via custom renderer in UI
-    // Only trigger an agent turn when the notification preferences say so.
-    const details: ProcessUpdateDetails = {
-      kind: "lifecycle",
-      processId: info.id,
-      processName: info.name,
-      command: info.command,
-      status: info.status as "exited" | "killed",
-      exitCode: info.exitCode,
-      success: info.success ?? false,
-      runtime,
-    };
-
-    safeSendMessage(
-      pi,
-      {
-        customType: MESSAGE_TYPE_PROCESS_UPDATE,
-        content: message,
-        display: true,
-        details,
-      },
-      { triggerTurn: triggerAgentTurn },
-    );
-  });
-}

package/src/hooks/process-watch.ts

@@ -1,85 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { MESSAGE_TYPE_PROCESS_UPDATE } from "../constants";
-import type { ProcessManager } from "../manager";
-import { safeSendMessage } from "./utils";
-
-interface ProcessWatchUpdateDetails {
-  kind: "watch_matched";
-  processId: string;
-  processName: string;
-  command: string;
-  source: "stdout" | "stderr";
-  line: string;
-  watch: {
-    index: number;
-    pattern: string;
-    stream: "stdout" | "stderr" | "both";
-    repeat: boolean;
-  };
-}
-
-const REPEAT_WATCH_TURN_COOLDOWN_MS = 5000;
-
-export function setupProcessWatchHook(
-  pi: ExtensionAPI,
-  manager: ProcessManager,
-) {
-  const lastRepeatTurnAt = new Map<string, number>();
-
-  manager.onEvent((event) => {
-    if (event.type === "process_ended") {
-      // Cleanup cooldown state for this process.
-      const prefix = `${event.info.id}:`;
-      for (const key of lastRepeatTurnAt.keys()) {
-        if (key.startsWith(prefix)) {
-          lastRepeatTurnAt.delete(key);
-        }
-      }
-      return;
-    }
-
-    if (event.type !== "process_watch_matched") return;
-
-    const match = event.match;
-    const message =
-      `Watch matched for '${match.processName}' (${match.processId}) ` +
-      `[${match.source}] /${match.watch.pattern}/`;
-
-    const details: ProcessWatchUpdateDetails = {
-      kind: "watch_matched",
-      processId: match.processId,
-      processName: match.processName,
-      command: match.processCommand,
-      source: match.source,
-      line: match.line,
-      watch: {
-        index: match.watch.index,
-        pattern: match.watch.pattern,
-        stream: match.watch.stream,
-        repeat: match.watch.repeat,
-      },
-    };
-
-    let triggerTurn = true;
-    if (match.watch.repeat) {
-      const watchKey = `${match.processId}:${match.watch.index}`;
-      const now = Date.now();
-      const last = lastRepeatTurnAt.get(watchKey) ?? 0;
-      triggerTurn = now - last >= REPEAT_WATCH_TURN_COOLDOWN_MS;
-      if (triggerTurn) {
-        lastRepeatTurnAt.set(watchKey, now);
-      }
-    }
-
-    safeSendMessage(
-      pi,
-      {
-        customType: MESSAGE_TYPE_PROCESS_UPDATE,
-        content: message,
-        display: true,
-        details,
-      },
-      { triggerTurn },
-    );
-  });
-}

package/src/hooks/utils.ts

@@ -1,23 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-/**
- * Send a message via pi, swallowing stale-context errors.
- *
- * After /new, /resume, or /fork, the pi proxy is invalidated and all
- * method calls throw. This wrapper catches that specific error so the
- * extension doesn't crash — the event is simply lost for the old session.
- */
-export function safeSendMessage(
-  pi: ExtensionAPI,
-  message: Parameters<ExtensionAPI["sendMessage"]>[0],
-  options?: Parameters<ExtensionAPI["sendMessage"]>[1],
-): void {
-  try {
-    pi.sendMessage(message, options);
-  } catch (err: unknown) {
-    if (err instanceof Error && err.message.includes("stale")) {
-      return;
-    }
-    throw err;
-  }
-}

package/src/hooks/widget/index.ts

@@ -1,2 +0,0 @@
-export { setupProcessWidget } from "./setup";
-export type { DockActions } from "./types";