@aliou/pi-processes 0.9.4 → 0.10.0

package/extensions/processes/tools/index.ts

@@ -0,0 +1,265 @@
+import {
+  type AgentToolResult,
+  defineTool,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { type Component, Container, Text } from "@earendil-works/pi-tui";
+
+import type { ProcessManager } from "../../../src/manager";
+import type { NotificationRegistry } from "../notifications/registry";
+import { type ClearDetails, executeClear, formatClearDetails } from "./clear";
+import * as clearRender from "./clear/render";
+import { ToolLayout } from "./components";
+import { executeList, formatListDetails, type ListDetails } from "./list";
+import * as listRender from "./list/render";
+import { executeOutput, type OutputDetails } from "./output";
+import * as outputRender from "./output/render";
+import { ProcessesParams, type ProcessesParamsType } from "./schema";
+import { executeStart, formatStartDetails, type StartDetails } from "./start";
+import * as startRender from "./start/render";
+import { executeStop, formatStopDetails, type StopDetails } from "./stop";
+import * as stopRender from "./stop/render";
+import {
+  executeUpdate,
+  formatUpdateDetails,
+  type UpdateDetails,
+} from "./update";
+import * as updateRender from "./update/render";
+import { executeWrite, formatWriteDetails, type WriteDetails } from "./write";
+import * as writeRender from "./write/render";
+
+type ProcessDetails =
+  | StartDetails
+  | ListDetails
+  | StopDetails
+  | OutputDetails
+  | WriteDetails
+  | UpdateDetails
+  | ClearDetails;
+
+export function registerProcessTool(
+  pi: ExtensionAPI,
+  manager: ProcessManager,
+  notifications: NotificationRegistry,
+): void {
+  pi.registerTool(
+    defineTool({
+      name: "process",
+      label: "Process",
+      description:
+        "Start, list, stop, write to stdin, update, clear, and inspect output of long-running background processes.",
+      promptSnippet:
+        "Manage long-running background processes: start, list, stop, write to stdin, update watches, clear finished entries, and inspect recent output. After starting a process, do not wait - notifications bring you back on exit and on log matches.",
+      promptGuidelines: [
+        "process tool: use process start for long-running commands (dev servers, watchers, builds) instead of shell background patterns like &, nohup, or setsid; give each process a specific name and check process list first when a duplicate would be noisy.",
+        "process tool: after process start, do not sleep, poll, or hold your turn. End your turn or move on. The process notifies you on exit (success, failure, killed) and on notify.logMatches matches, which brings you back.",
+        "process tool: use notify.logMatches to get brought back on readiness or error signals instead of polling process output. If a watch is too noisy, use process update (watches.mode append/replace/remove/clear) to fix it without restarting.",
+        "process tool: for the full lifecycle (start, list, output, update, write, stop, clear), notify options, use cases, and noisy-watch handling, read the pi-processes skill.",
+      ],
+      parameters: ProcessesParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        if (params.action === "output") {
+          const result = executeOutput(params, manager);
+          return {
+            content: [{ type: "text", text: result.content }],
+            details: result.details,
+          };
+        }
+
+        const details = await execute(params, manager, ctx, notifications);
+        return {
+          content: [{ type: "text", text: formatDetails(details) }],
+          details,
+        };
+      },
+      renderCall: renderProcessCall,
+      renderResult: renderProcessResult,
+    }),
+  );
+}
+
+async function execute(
+  params: ProcessesParamsType,
+  manager: ProcessManager,
+  ctx: ExtensionContext,
+  notifications: NotificationRegistry,
+): Promise<ProcessDetails> {
+  switch (params.action) {
+    case "start":
+      return executeStart(params, manager, ctx, notifications);
+    case "list":
+      return executeList(manager, params, notifications);
+    case "stop":
+      return executeStop(params, manager, notifications);
+    case "write":
+      return executeWrite(params, manager);
+    case "update":
+      return executeUpdate(params, manager, notifications);
+    case "clear":
+      return executeClear(manager);
+    default:
+      throw new Error(`unsupported process action: ${String(params.action)}`);
+  }
+}
+
+function renderProcessCall(
+  args: ProcessesParamsType,
+  theme: Theme,
+  context?: { expanded?: boolean },
+): Component {
+  switch (args.action) {
+    case "start":
+      return new ToolLayout().setHeader(
+        startRender.buildHeader(args, theme, context),
+      );
+    case "list":
+      return new ToolLayout().setHeader(listRender.buildHeader(args, theme));
+    case "stop":
+      return new ToolLayout().setHeader(
+        stopRender.buildHeader(args, theme, context),
+      );
+    case "output":
+      return new ToolLayout().setHeader(
+        outputRender.buildHeader(args, theme, context),
+      );
+    case "write":
+      return new ToolLayout().setHeader(
+        writeRender.buildHeader(args, theme, context),
+      );
+    case "update":
+      return new ToolLayout().setHeader(
+        updateRender.buildHeader(args, theme, context),
+      );
+    case "clear":
+      return new ToolLayout().setHeader(clearRender.buildHeader(args, theme));
+    default:
+      return fallbackContainer(theme);
+  }
+}
+
+function renderProcessResult(
+  result: AgentToolResult<ProcessDetails>,
+  options: { expanded?: boolean; isPartial?: boolean },
+  theme: Theme,
+  context?: { isError?: boolean },
+): Component {
+  if (options.isPartial) {
+    return fallbackContainer(theme, "process running...");
+  }
+
+  if (context?.isError) {
+    return fallbackContainer(theme, "process failed");
+  }
+
+  const details = result.details as ProcessDetails | undefined;
+
+  if (!details) {
+    return fallbackContainer(theme, "process completed");
+  }
+
+  const contentText = getContentText(result);
+
+  return new ToolLayout()
+    .withSectionSpacing(options.expanded)
+    .setBody(buildBody(details, contentText, options, theme))
+    .setFooter(buildFooter(details, contentText, options, theme));
+}
+
+function getContentText(
+  result: AgentToolResult<ProcessDetails>,
+): string | undefined {
+  const first = result.content[0];
+  if (first?.type === "text" && typeof first.text === "string") {
+    return first.text;
+  }
+  return undefined;
+}
+
+function buildBody(
+  details: ProcessDetails,
+  contentText: string | undefined,
+  options: { expanded?: boolean },
+  theme: Theme,
+): Container {
+  switch (details.action) {
+    case "start":
+      return options.expanded
+        ? startRender.buildExpanded(details, theme)
+        : startRender.buildCollapsed(details, theme);
+    case "list":
+      return options.expanded
+        ? listRender.buildExpanded(details, theme)
+        : listRender.buildCollapsed(details, theme);
+    case "output":
+      return options.expanded
+        ? outputRender.buildExpanded(contentText ?? "", details, theme)
+        : outputRender.buildCollapsed(contentText ?? "", details, theme);
+    case "update":
+      return options.expanded
+        ? updateRender.buildExpanded(details, theme)
+        : updateRender.buildCollapsed(details, theme);
+    case "write":
+      return options.expanded
+        ? writeRender.buildExpanded(details, theme)
+        : writeRender.buildCollapsed(details, theme);
+    case "stop":
+      return options.expanded
+        ? stopRender.buildExpanded(details, theme)
+        : stopRender.buildCollapsed(details, theme);
+    case "clear":
+      return options.expanded
+        ? clearRender.buildExpanded(details, theme)
+        : clearRender.buildCollapsed(details, theme);
+  }
+}
+
+function buildFooter(
+  details: ProcessDetails,
+  _contentText: string | undefined,
+  options: { expanded?: boolean },
+  theme: Theme,
+): Container | null {
+  switch (details.action) {
+    case "start":
+      return startRender.buildFooter(details, options, theme);
+    case "list":
+      return listRender.buildFooter(details, options, theme);
+    case "stop":
+      return stopRender.buildFooter(details, options, theme);
+    case "output":
+      return outputRender.buildFooter(details, options, theme);
+    case "update":
+      return updateRender.buildFooter(details, options, theme);
+    case "write":
+      return writeRender.buildFooter(details, options, theme);
+    case "clear":
+      return clearRender.buildFooter(details, options, theme);
+  }
+}
+
+function formatDetails(details: ProcessDetails): string {
+  switch (details.action) {
+    case "start":
+      return formatStartDetails(details);
+    case "list":
+      return formatListDetails(details);
+    case "stop":
+      return formatStopDetails(details);
+    case "update":
+      return formatUpdateDetails(details);
+    case "write":
+      return formatWriteDetails(details);
+    case "clear":
+      return formatClearDetails(details);
+    case "output":
+      throw new Error("output action uses pre-formatted content");
+  }
+}
+
+function fallbackContainer(theme: Theme, message = "process"): Container {
+  const container = new Container();
+  container.addChild(new Text(theme.fg("muted", message), 0, 0));
+  return container;
+}

package/extensions/processes/tools/list/index.ts

@@ -0,0 +1,157 @@
+import type { ProcessManager } from "../../../../src/manager";
+import { LIVE_STATUSES, type ProcessInfo } from "../../../../src/types";
+import type {
+  LogMatcherConfig,
+  NotificationRegistry,
+} from "../../notifications/registry";
+import type {
+  ProcessesParamsType,
+  ProcessListSort,
+  ProcessListStatusFilter,
+} from "../schema";
+import { formatProcessRuntime } from "../utils";
+import { formatPatternsForModel } from "../watch-format";
+
+/**
+ * A process plus its duration computed when the list was produced.
+ *
+ * For stopped processes this is the actual run duration (endTime - startTime).
+ * For running processes it is measured against the list call's reference time.
+ */
+export interface ListProcess extends ProcessInfo {
+  duration: string;
+  watches: LogMatcherConfig[];
+}
+
+export interface ListDetails {
+  action: "list";
+  processes: ListProcess[];
+  filters: {
+    limit: number | null;
+    sortBy: ProcessListSort;
+    statuses: ProcessListStatusFilter[];
+  };
+  counts: ProcessListCounts;
+}
+
+export interface ProcessListCounts {
+  running: number;
+  exited: number;
+  failed: number;
+  killed: number;
+  total: number;
+}
+
+export function executeList(
+  manager: ProcessManager,
+  params: ProcessesParamsType,
+  notifications: NotificationRegistry,
+): ListDetails {
+  const filters = resolveListFilters(params);
+  const allProcesses = manager.list();
+  const filtered = allProcesses
+    .filter((process) => matchesStatusFilter(process, filters.statuses))
+    .sort((a, b) => compareProcesses(a, b, filters.sortBy));
+
+  const limited =
+    filters.limit === null ? filtered : filtered.slice(0, filters.limit);
+
+  // Capture the reference time after listing so every process in `limited`
+  // has startTime <= now (avoids negative durations for just-spawned ones).
+  const now = Date.now();
+  const processes: ListProcess[] = limited.map((process) => ({
+    ...process,
+    duration: formatProcessRuntime(process, now),
+    watches: LIVE_STATUSES.has(process.status)
+      ? (notifications.getWatchState(process.id)?.logMatches ?? [])
+      : [],
+  }));
+
+  return {
+    action: "list",
+    processes,
+    filters,
+    counts: countProcesses(processes),
+  };
+}
+
+export function formatListDetails(details: ListDetails): string {
+  if (details.processes.length === 0) {
+    return "No matching background processes.";
+  }
+
+  return details.processes
+    .map(
+      (process) =>
+        `${process.id}\t${process.status}\t${process.name}\t${process.command}\t${process.stdoutFile}\t${process.stderrFile}\tpatterns=${formatPatternsForModel(process.watches)}`,
+    )
+    .join("\n");
+}
+
+function resolveListFilters(
+  params: ProcessesParamsType,
+): ListDetails["filters"] {
+  return {
+    limit: params.limit && params.limit > 0 ? Math.floor(params.limit) : null,
+    sortBy: params.sortBy ?? "startTime_desc",
+    statuses:
+      params.statuses && params.statuses.length > 0 ? params.statuses : ["all"],
+  };
+}
+
+function matchesStatusFilter(
+  process: ProcessInfo,
+  filters: ProcessListStatusFilter[],
+): boolean {
+  if (filters.includes("all")) return true;
+
+  return filters.some((filter) => {
+    if (filter === "finished") {
+      return process.status === "exited" && process.success === true;
+    }
+
+    if (filter === "failed") {
+      return (
+        process.status === "terminate_timeout" ||
+        (process.status === "exited" && process.success === false)
+      );
+    }
+
+    return process.status === filter;
+  });
+}
+
+function compareProcesses(
+  a: ProcessInfo,
+  b: ProcessInfo,
+  sortBy: ProcessListSort,
+): number {
+  switch (sortBy) {
+    case "startTime_asc":
+      return a.startTime - b.startTime;
+    case "name_asc":
+      return a.name.localeCompare(b.name);
+    case "name_desc":
+      return b.name.localeCompare(a.name);
+    case "status_asc":
+      return a.status.localeCompare(b.status);
+    case "startTime_desc":
+      return b.startTime - a.startTime;
+  }
+}
+
+function countProcesses(processes: ProcessInfo[]): ProcessListCounts {
+  return {
+    running: processes.filter((process) => process.status === "running").length,
+    exited: processes.filter(
+      (process) => process.status === "exited" && process.success === true,
+    ).length,
+    failed: processes.filter(
+      (process) =>
+        process.status === "terminate_timeout" ||
+        (process.status === "exited" && process.success === false),
+    ).length,
+    killed: processes.filter((process) => process.status === "killed").length,
+    total: processes.length,
+  };
+}

package/extensions/processes/tools/list/render.ts

@@ -0,0 +1,211 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Text, visibleWidth } from "@earendil-works/pi-tui";
+import { formatTimestamp, shortenPath } from "../../../../src/utils";
+import { LinesComponent } from "../../../shared/ui";
+import { truncateToWidth } from "../../utils/truncate";
+import { formatPatternForDisplay, ProcessActionTitle } from "../components";
+import type {
+  ProcessesParamsType,
+  ProcessListSort,
+  ProcessListStatusFilter,
+} from "../schema";
+import { formatColoredProcessStatus, formatCount } from "../utils";
+import type { ListDetails, ListProcess, ProcessListCounts } from ".";
+
+type CountStatusItem = {
+  filter: ProcessListStatusFilter;
+  countKey: keyof Pick<
+    ProcessListCounts,
+    "running" | "exited" | "failed" | "killed"
+  >;
+  label: string;
+  tone: "success" | "warning" | "error" | "muted";
+};
+
+const COUNT_STATUS_ITEMS: CountStatusItem[] = [
+  {
+    filter: "running",
+    countKey: "running",
+    label: "running",
+    tone: "success",
+  },
+  {
+    filter: "finished",
+    countKey: "exited",
+    label: "exited",
+    tone: "muted",
+  },
+  {
+    filter: "failed",
+    countKey: "failed",
+    label: "failed",
+    tone: "error",
+  },
+  {
+    filter: "killed",
+    countKey: "killed",
+    label: "killed",
+    tone: "warning",
+  },
+];
+
+export function buildHeader(
+  args: ProcessesParamsType,
+  theme: Theme,
+): Container {
+  const header = new Container();
+  header.addChild(
+    new ProcessActionTitle("list", theme, formatListHeaderSuffix(args, theme)),
+  );
+  return header;
+}
+
+export function buildExpanded(details: ListDetails, theme: Theme): Container {
+  const container = new Container();
+  container.addChild(
+    new LinesComponent((width) =>
+      formatExpandedProcessLines(details.processes, theme, width),
+    ),
+  );
+  return container;
+}
+
+export function buildCollapsed(details: ListDetails, theme: Theme): Container {
+  const container = new Container();
+
+  for (const process of details.processes.slice(0, 2)) {
+    const parts = [
+      process.name,
+      theme.fg("accent", process.id),
+      `pid ${process.pid}`,
+      formatColoredProcessStatus(process, theme),
+      theme.fg(
+        "muted",
+        `${process.watches.length} ${process.watches.length === 1 ? "watch" : "watches"}`,
+      ),
+    ];
+    container.addChild(new Text(parts.join("  "), 0, 0));
+  }
+
+  return container;
+}
+
+export function buildFooter(
+  details: ListDetails,
+  _options: { expanded?: boolean },
+  theme: Theme,
+): Container {
+  const footer = new Container();
+  footer.addChild(new Text(formatCounts(details, theme), 0, 0));
+  return footer;
+}
+
+function formatListHeaderSuffix(
+  args: ProcessesParamsType,
+  theme: Theme,
+): string {
+  const statuses = normalizeStatuses(args.statuses);
+  const parts = [
+    `${theme.fg("muted", "sorted")} ${theme.fg("accent", formatSort(args.sortBy ?? "startTime_desc"))}`,
+  ];
+
+  if (args.limit) {
+    parts.unshift(
+      `${theme.fg("muted", "limit")} ${theme.fg("accent", String(args.limit))}`,
+    );
+  }
+
+  if (!statuses.includes("all")) {
+    parts.push(
+      `${theme.fg("muted", "statuses")} ${theme.fg("accent", statuses.join(", "))}`,
+    );
+  }
+
+  return parts.join(theme.fg("dim", " / "));
+}
+
+function normalizeStatuses(
+  statuses: ProcessListStatusFilter[] | undefined,
+): ProcessListStatusFilter[] {
+  return statuses && statuses.length > 0 ? statuses : ["all"];
+}
+
+function formatSort(sort: ProcessListSort): string {
+  switch (sort) {
+    case "startTime_desc":
+      return "newest first";
+    case "startTime_asc":
+      return "oldest first";
+    case "name_asc":
+      return "name A-Z";
+    case "name_desc":
+      return "name Z-A";
+    case "status_asc":
+      return "status A-Z";
+  }
+}
+
+function formatCounts(details: ListDetails, theme: Theme): string {
+  if (details.processes.length === 0) {
+    return "no process running";
+  }
+
+  const statuses = details.filters.statuses;
+  const showAll = statuses.includes("all");
+
+  return COUNT_STATUS_ITEMS.filter(
+    (item) => showAll || statuses.includes(item.filter),
+  )
+    .map((item) =>
+      theme.fg(
+        item.tone,
+        `${formatCount(details.counts[item.countKey], "process")} ${item.label}`,
+      ),
+    )
+    .join(theme.fg("dim", " / "));
+}
+
+export function formatExpandedProcessLines(
+  processes: ListProcess[],
+  theme: Theme,
+  width: number,
+): string[] {
+  if (processes.length === 0) {
+    return ["No matching background processes."];
+  }
+
+  const lines: string[] = [];
+
+  for (const process of processes) {
+    if (lines.length > 0) lines.push("");
+
+    const summary = [
+      theme.bold(theme.fg("text", formatPatternForDisplay(process.name))),
+      `${theme.fg("muted", "pid:")} ${process.pid}`,
+      formatColoredProcessStatus(process, theme),
+      theme.fg("muted", process.duration),
+      theme.fg("muted", `(${formatTimestamp(process.startTime)})`),
+      theme.fg("accent", process.id),
+    ].join(" ");
+    lines.push(fitStyledLine(summary, width));
+
+    const command = `${theme.fg("muted", "  $")} ${theme.fg("text", formatPatternForDisplay(process.command))}`;
+    lines.push(fitStyledLine(command, width));
+    const cwd = `${theme.fg("muted", "    cwd")} ${theme.fg("text", formatPatternForDisplay(shortenPath(process.cwd)))}`;
+    lines.push(fitStyledLine(cwd, width));
+
+    for (const matcher of process.watches) {
+      const stream = matcher.stream ?? "both";
+      const watch = `${theme.fg("muted", "  ↳")} ${theme.fg("muted", `[${stream}]`)} ${theme.fg("accent", formatPatternForDisplay(matcher.pattern))}`;
+      lines.push(fitStyledLine(watch, width));
+    }
+  }
+
+  return lines;
+}
+
+function fitStyledLine(line: string, width: number): string {
+  if (width <= 0) return "";
+  if (visibleWidth(line) <= width) return line;
+  return `${truncateToWidth(line, width)}\u001b[0m`;
+}