@aliou/pi-processes 0.9.4 → 0.10.0

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

@@ -0,0 +1,229 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+
+import { ProcessActionHeader } from "../components";
+import type { ProcessesParamsType } from "../schema";
+import { buildField } from "../utils";
+import type { OutputDetails } from ".";
+
+export function buildHeader(
+  args: ProcessesParamsType,
+  theme: Theme,
+  options?: { expanded?: boolean },
+): Container {
+  const suffix = args.id ? theme.fg("accent", `(${args.id})`) : undefined;
+  return new ProcessActionHeader(args, theme, {
+    action: "output",
+    expanded: options?.expanded,
+    suffix,
+  });
+}
+
+export function buildExpanded(
+  contentText: string,
+  details: OutputDetails,
+  theme: Theme,
+): Container {
+  const container = new Container();
+  container.addChild(buildOutputMeta(details, theme));
+
+  const bodyLines = extractOutputBody(contentText, details);
+
+  if (bodyLines.length > 0) {
+    container.addChild(new Spacer(1));
+    for (const line of bodyLines) {
+      container.addChild(new Text(line, 0, 0));
+    }
+  } else {
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(theme.fg("muted", emptyMessage(details)), 0, 0),
+    );
+  }
+
+  if (details.truncation) {
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(theme.fg("muted", buildTruncationSummary(details)), 0, 0),
+    );
+  }
+
+  return container;
+}
+
+export function buildCollapsed(
+  contentText: string,
+  details: OutputDetails,
+  theme: Theme,
+): Container {
+  const container = new Container();
+
+  container.addChild(
+    new Text(
+      [
+        details.processName,
+        theme.fg("accent", details.id),
+        theme.fg(getStatusTone(details), details.processStatus),
+      ]
+        .filter(Boolean)
+        .join("  "),
+      0,
+      0,
+    ),
+  );
+
+  const bodyLines = extractOutputBody(contentText, details);
+  const preview = bodyLines.slice(-2).join("\n");
+
+  if (preview) {
+    container.addChild(new Text(theme.fg("muted", preview), 0, 0));
+  } else {
+    container.addChild(
+      new Text(theme.fg("muted", emptyMessage(details)), 0, 0),
+    );
+  }
+
+  return container;
+}
+
+export function buildFooter(
+  details: OutputDetails,
+  options: { expanded?: boolean },
+  theme: Theme,
+): Container | null {
+  if (!options.expanded) return null;
+
+  const container = new Container();
+  container.addChild(new Text(theme.fg("muted", "logs:"), 0, 0));
+  container.addChild(
+    new Text(`  ${theme.fg("accent", details.stdoutFile)}`, 0, 0),
+  );
+  container.addChild(
+    new Text(`  ${theme.fg("accent", details.stderrFile)}`, 0, 0),
+  );
+  return container;
+}
+
+function buildOutputMeta(details: OutputDetails, theme: Theme): Container {
+  const container = new Container();
+  container.addChild(buildField("name", details.processName, theme));
+  container.addChild(buildField("id", details.id, theme));
+  container.addChild(
+    buildField(
+      "status",
+      theme.fg(getStatusTone(details), details.processStatus),
+      theme,
+    ),
+  );
+  container.addChild(buildField("stream", details.stream, theme));
+
+  if (details.pattern) {
+    const modeTag = details.mode === "regex" ? " (regex)" : "";
+    container.addChild(
+      buildField("filter", `${details.pattern}${modeTag}`, theme),
+    );
+  }
+
+  return container;
+}
+
+function emptyMessage(details: OutputDetails): string {
+  return details.pattern ? "No matching lines found" : "No output yet";
+}
+
+function buildTruncationSummary(details: OutputDetails): string {
+  const truncation = details.truncation;
+  if (!truncation) return "";
+
+  const partialNote = truncation.lastLinePartial ? " · partial final line" : "";
+  return `Preview truncated · ${truncation.outputLines}/${truncation.totalLines} lines${partialNote}`;
+}
+
+function getStatusTone(
+  details: OutputDetails,
+): "success" | "warning" | "error" | "muted" {
+  if (details.processStatus === "running") return "success";
+  if (details.processStatus === "killed") return "warning";
+  return "muted";
+}
+
+/**
+ * Extract process output from the tool-result content text.
+ *
+ * The content text is structured as:
+ *   - a one- or two-line header with process metadata and filter;
+ *   - the bounded output body;
+ *   - optional running guidance and truncation notice;
+ *   - a final `[Complete currently-retained logs: ...]` footer.
+ *
+ * The renderer uses details for metadata, guidance, truncation state, and log
+ * paths. Only process output is returned here. Legacy content that has lost
+ * its header through tail truncation is also accepted.
+ */
+function extractOutputBody(
+  contentText: string,
+  details: OutputDetails,
+): string[] {
+  const lines = contentText.split("\n");
+
+  const expectedHeader = `"${details.processName}" (${details.id}) [${details.processStatus}]`;
+  let bodyStart = lines[0] === expectedHeader ? 1 : 0;
+  if (lines[bodyStart]?.startsWith("filter: ")) {
+    bodyStart++;
+  }
+
+  // Use the final exact marker so process output containing the same text does
+  // not terminate the rendered preview.
+  const footerStart = findLastLineIndex(
+    lines,
+    (line) => line === "[Complete currently-retained logs:",
+  );
+  let bodyEnd = footerStart >= 0 ? footerStart : lines.length;
+
+  if (details.truncation) {
+    const truncationNotice = findLastLineIndex(
+      lines,
+      (line, index) =>
+        index < bodyEnd && line.startsWith("[Preview truncated by "),
+    );
+    if (truncationNotice >= bodyStart) {
+      bodyEnd = truncationNotice;
+    }
+  }
+
+  if (details.processStatus === "running") {
+    const guidance = findLastLineIndex(
+      lines,
+      (line, index) =>
+        index < bodyEnd &&
+        line === "Process is still running. Use watches instead of polling.",
+    );
+    if (guidance >= bodyStart) {
+      bodyEnd = guidance;
+    }
+  }
+
+  const body = lines.slice(bodyStart, bodyEnd);
+
+  // Trim leading/trailing blank lines while preserving internal blank lines.
+  let start = 0;
+  while (start < body.length && body[start] === "") {
+    start++;
+  }
+  let end = body.length;
+  while (end > start && body[end - 1] === "") {
+    end--;
+  }
+
+  return body.slice(start, end);
+}
+
+function findLastLineIndex(
+  lines: string[],
+  predicate: (line: string, index: number) => boolean,
+): number {
+  for (let index = lines.length - 1; index >= 0; index--) {
+    if (predicate(lines[index] ?? "", index)) return index;
+  }
+  return -1;
+}

package/extensions/processes/tools/schema.ts

@@ -0,0 +1,263 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+import { MAX_NOTIFY_LOG_MATCHERS, MAX_NOTIFY_PATTERN_LENGTH } from "./notify";
+
+// --- Output action constants ---
+
+export const DEFAULT_OUTPUT_TAIL_LINES = 100;
+export const MAX_OUTPUT_TAIL_LINES = 2000;
+export const MAX_OUTPUT_SCAN_LINES = 5000;
+export const MAX_OUTPUT_BYTES = 50 * 1024;
+export const MAX_OUTPUT_PATTERN_LENGTH = MAX_NOTIFY_PATTERN_LENGTH;
+
+export const PROCESS_OUTPUT_STREAMS = ["stdout", "stderr", "both"] as const;
+
+export const PROCESS_OUTPUT_MATCH_MODES = ["literal", "regex"] as const;
+
+export const PROCESS_WATCH_UPDATE_MODES = [
+  "append",
+  "replace",
+  "remove",
+  "clear",
+] as const;
+
+export const PROCESS_LIST_STATUS_FILTERS = [
+  "all",
+  "running",
+  "finished",
+  "failed",
+  "terminating",
+  "terminate_timeout",
+  "killed",
+] as const;
+
+export const PROCESS_LIST_SORTS = [
+  "startTime_desc",
+  "startTime_asc",
+  "name_asc",
+  "name_desc",
+  "status_asc",
+] as const;
+
+export const PROCESS_NOTIFY_ATTENTIONS = ["turn", "context", "ignore"] as const;
+export const PROCESS_NOTIFY_LOG_MATCH_MODES = ["literal", "regex"] as const;
+export const PROCESS_NOTIFY_LOG_MATCH_STREAMS = [
+  "stdout",
+  "stderr",
+  "both",
+] as const;
+
+const NotifyLogMatchParams = Type.Object({
+  pattern: Type.String({
+    maxLength: MAX_NOTIFY_PATTERN_LENGTH,
+    description:
+      "Log pattern to match. Limited to 500 characters. Literal by default; regex only when mode is regex.",
+  }),
+  mode: Type.Optional(
+    StringEnum(PROCESS_NOTIFY_LOG_MATCH_MODES, {
+      description: "Pattern matching mode. Defaults to literal.",
+    }),
+  ),
+  stream: Type.Optional(
+    StringEnum(PROCESS_NOTIFY_LOG_MATCH_STREAMS, {
+      description: "Output stream to inspect. Defaults to both.",
+    }),
+  ),
+  repeat: Type.Optional(
+    Type.Boolean({
+      description:
+        "Whether this matcher can notify more than once. Defaults to false.",
+    }),
+  ),
+  on: Type.Optional(
+    StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
+      description: "Agent attention for this log match. Defaults to turn.",
+    }),
+  ),
+});
+
+const WatchUpdateItemParams = Type.Object({
+  index: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      description:
+        "Matcher index to remove. Only for remove mode. If pattern is also provided, index takes precedence.",
+    }),
+  ),
+  pattern: Type.Optional(
+    Type.String({
+      maxLength: MAX_NOTIFY_PATTERN_LENGTH,
+      description:
+        "Log pattern. Required for append and replace modes. Optional for remove mode (use index or pattern).",
+    }),
+  ),
+  mode: Type.Optional(
+    StringEnum(PROCESS_NOTIFY_LOG_MATCH_MODES, {
+      description: "Pattern matching mode. Defaults to literal.",
+    }),
+  ),
+  stream: Type.Optional(
+    StringEnum(PROCESS_NOTIFY_LOG_MATCH_STREAMS, {
+      description: "Output stream to inspect. Defaults to both.",
+    }),
+  ),
+  repeat: Type.Optional(
+    Type.Boolean({
+      description:
+        "Whether this matcher can notify more than once. Defaults to false.",
+    }),
+  ),
+  on: Type.Optional(
+    StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
+      description: "Agent attention for this log match. Defaults to turn.",
+    }),
+  ),
+});
+
+const NotifyParams = Type.Object({
+  onSuccess: Type.Optional(
+    StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
+      description:
+        "Agent attention when the process exits successfully. Defaults to context.",
+    }),
+  ),
+  onFailure: Type.Optional(
+    StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
+      description:
+        "Agent attention when the process fails or crashes. Defaults to turn.",
+    }),
+  ),
+  onKilled: Type.Optional(
+    StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
+      description:
+        "Agent attention when the process is killed. Defaults to context.",
+    }),
+  ),
+  logMatches: Type.Optional(
+    Type.Array(NotifyLogMatchParams, {
+      maxItems: MAX_NOTIFY_LOG_MATCHERS,
+      description:
+        "Log match notifications. Supports at most 20 matchers, with each pattern limited to 500 characters.",
+    }),
+  ),
+});
+
+export const ProcessesParams = Type.Object({
+  action: StringEnum(
+    ["start", "list", "stop", "output", "write", "update", "clear"] as const,
+    {
+      description: "Action to perform.",
+    },
+  ),
+  name: Type.Optional(
+    Type.String({ description: "Process name. Required for start." }),
+  ),
+  command: Type.Optional(
+    Type.String({ description: "Shell command to run. Required for start." }),
+  ),
+  cwd: Type.Optional(
+    Type.String({
+      description:
+        "Working directory for start. Defaults to the agent's current working directory. Only for start.",
+    }),
+  ),
+  notify: Type.Optional(NotifyParams),
+  id: Type.Optional(
+    Type.String({
+      description:
+        "Opaque process ID returned by start or list (for example, proc_ab12). Required for stop, output, write, and update. Process names are not accepted.",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({ description: "Maximum number of processes to list." }),
+  ),
+  sortBy: Type.Optional(
+    StringEnum(PROCESS_LIST_SORTS, {
+      description: "Sort order for process list results.",
+    }),
+  ),
+  statuses: Type.Optional(
+    Type.Array(StringEnum(PROCESS_LIST_STATUS_FILTERS), {
+      description:
+        "Process list status filters. Use all for no filtering; finished means exited successfully; failed means exited unsuccessfully or terminate_timeout.",
+    }),
+  ),
+  stream: Type.Optional(
+    StringEnum(PROCESS_OUTPUT_STREAMS, {
+      description:
+        "Output stream to return. Defaults to both. Only for output action.",
+    }),
+  ),
+  tailLines: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: MAX_OUTPUT_TAIL_LINES,
+      description:
+        "Maximum matching lines to return per selected stream. Defaults to 100. Only for output action.",
+    }),
+  ),
+  pattern: Type.Optional(
+    Type.String({
+      maxLength: MAX_OUTPUT_PATTERN_LENGTH,
+      description:
+        "Optional output filter. Literal by default; regex only when mode is regex. Only for output action.",
+    }),
+  ),
+  input: Type.Optional(
+    Type.String({
+      description:
+        "Text to write to the process stdin. Only for write action. Defaults to an empty string when closing stdin with end.",
+    }),
+  ),
+  end: Type.Optional(
+    Type.Boolean({
+      description:
+        "Close stdin after writing. Use to signal end-of-input (EOF). Only for write action.",
+    }),
+  ),
+  mode: Type.Optional(
+    StringEnum(PROCESS_OUTPUT_MATCH_MODES, {
+      description:
+        "Pattern matching mode for output filter. Defaults to literal. Only for output action.",
+    }),
+  ),
+  watches: Type.Optional(
+    Type.Object(
+      {
+        mode: StringEnum(PROCESS_WATCH_UPDATE_MODES, {
+          description: "How to update log watches.",
+        }),
+        items: Type.Optional(
+          Type.Array(WatchUpdateItemParams, {
+            maxItems: MAX_NOTIFY_LOG_MATCHERS,
+            description:
+              "Watch entries. For append/replace, provide full matcher definitions. For remove, provide index or pattern to identify matchers to remove. Ignored for clear.",
+          }),
+        ),
+      },
+      {
+        description:
+          "Update log watches on a running process. Only for update action.",
+      },
+    ),
+  ),
+});
+
+export type ProcessesParamsType = Static<typeof ProcessesParams>;
+
+export type ProcessAction = ProcessesParamsType["action"];
+export type ProcessListStatusFilter =
+  (typeof PROCESS_LIST_STATUS_FILTERS)[number];
+export type ProcessListSort = (typeof PROCESS_LIST_SORTS)[number];
+export type ProcessNotifyAttention = (typeof PROCESS_NOTIFY_ATTENTIONS)[number];
+export type ProcessNotifyLogMatchMode =
+  (typeof PROCESS_NOTIFY_LOG_MATCH_MODES)[number];
+export type ProcessNotifyLogMatchStream =
+  (typeof PROCESS_NOTIFY_LOG_MATCH_STREAMS)[number];
+
+export type ProcessOutputStream = (typeof PROCESS_OUTPUT_STREAMS)[number];
+export type ProcessOutputMatchMode =
+  (typeof PROCESS_OUTPUT_MATCH_MODES)[number];
+export type ProcessWatchUpdateMode =
+  (typeof PROCESS_WATCH_UPDATE_MODES)[number];

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

@@ -0,0 +1,64 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { ProcessManager } from "../../../../src/manager";
+import type { ProcessInfo } from "../../../../src/types";
+import type {
+  NotificationRegistry,
+  NotifyConfig,
+} from "../../notifications/registry";
+import { normalizeNotifyConfig } from "../notify";
+import type { ProcessesParamsType } from "../schema";
+import { formatMatcherForModel } from "../watch-format";
+
+export interface StartDetails {
+  action: "start";
+  process: ProcessInfo;
+  notify: NotifyConfig;
+}
+
+export function executeStart(
+  params: ProcessesParamsType,
+  manager: ProcessManager,
+  ctx: ExtensionContext,
+  notifications: NotificationRegistry,
+): StartDetails {
+  if (!params.name) {
+    throw new Error("process start requires name");
+  }
+
+  if (!params.command) {
+    throw new Error("process start requires command");
+  }
+
+  const notify = normalizeNotifyConfig(params.notify);
+
+  const cwd = params.cwd ?? ctx.cwd;
+  const process = manager.start(params.name, params.command, cwd);
+  notifications.register(process.id, notify);
+
+  return {
+    action: "start",
+    process,
+    notify,
+  };
+}
+
+export function formatStartDetails(details: StartDetails): string {
+  const process = details.process;
+  const parts = [
+    `Started process ${process.name} (${process.id}) with pid ${process.pid}.`,
+  ];
+
+  if (details.notify.logMatches && details.notify.logMatches.length > 0) {
+    parts.push(
+      `Watches:\n${details.notify.logMatches
+        .map((matcher) => formatMatcherForModel(matcher))
+        .join("\n")}`,
+    );
+    parts.push(
+      "Continue other work; watch notifications will trigger follow-up.",
+    );
+  }
+
+  return parts.join(" ");
+}

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

@@ -0,0 +1,67 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { buildMatcherLine, ProcessActionHeader } from "../components";
+import type { ProcessesParamsType } from "../schema";
+import {
+  buildCompactProcessLine,
+  buildField,
+  buildProcessDetails,
+} from "../utils";
+import type { StartDetails } from ".";
+
+export function buildHeader(
+  args: ProcessesParamsType,
+  theme: Theme,
+  options?: { expanded?: boolean },
+): Container {
+  return new ProcessActionHeader(args, theme, {
+    action: "start",
+    expanded: options?.expanded,
+    suffix: args.name ? theme.fg("accent", `\`${args.name}\``) : undefined,
+  });
+}
+
+export function buildExpanded(details: StartDetails, theme: Theme): Container {
+  const container = buildProcessDetails(details.process, theme, {
+    runtime: false,
+  });
+  const watches = details.notify.logMatches ?? [];
+
+  if (watches.length > 0) {
+    container.addChild(
+      new Text(
+        theme.bold(
+          theme.fg(
+            "text",
+            `watches ${theme.fg("muted", `(${watches.length})`)}`,
+          ),
+        ),
+        0,
+        0,
+      ),
+    );
+    for (const matcher of watches) {
+      container.addChild(buildMatcherLine(matcher, theme, "  "));
+    }
+  }
+
+  return container;
+}
+
+export function buildCollapsed(details: StartDetails, theme: Theme): Container {
+  const container = new Container();
+  container.addChild(buildCompactProcessLine(details.process, theme));
+  const watchCount = details.notify.logMatches?.length ?? 0;
+  if (watchCount > 0) {
+    container.addChild(buildField("watches", watchCount, theme));
+  }
+  return container;
+}
+
+export function buildFooter(
+  _details: StartDetails,
+  _options: { expanded?: boolean },
+  _theme: Theme,
+): Container | null {
+  return null;
+}

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

@@ -0,0 +1,35 @@
+import type { ProcessManager } from "../../../../src/manager";
+import type { KillResult } from "../../../../src/types";
+import { killIntentionally } from "../../handlers/kill-process";
+import type { NotificationRegistry } from "../../notifications/registry";
+import type { ProcessesParamsType } from "../schema";
+
+export interface StopDetails {
+  action: "stop";
+  result: KillResult;
+}
+
+export async function executeStop(
+  params: ProcessesParamsType,
+  manager: ProcessManager,
+  notifications: NotificationRegistry,
+): Promise<StopDetails> {
+  if (!params.id) {
+    throw new Error("process stop requires id");
+  }
+
+  const result = await killIntentionally(manager, notifications, params.id);
+
+  return {
+    action: "stop",
+    result,
+  };
+}
+
+export function formatStopDetails(details: StopDetails): string {
+  if (details.result.ok) {
+    return `Stopped process ${details.result.info.name} (${details.result.info.id}).`;
+  }
+
+  return `Failed to stop process ${details.result.info.id}: ${details.result.reason}.`;
+}

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

@@ -0,0 +1,43 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container } from "@earendil-works/pi-tui";
+import { ProcessActionHeader } from "../components";
+import type { ProcessesParamsType } from "../schema";
+import {
+  buildCompactProcessLine,
+  buildField,
+  buildProcessDetails,
+} from "../utils";
+import type { StopDetails } from ".";
+
+export function buildHeader(
+  args: ProcessesParamsType,
+  theme: Theme,
+  options?: { expanded?: boolean },
+): Container {
+  return new ProcessActionHeader(args, theme, {
+    action: "stop",
+    expanded: options?.expanded,
+    suffix: args.id ? theme.fg("accent", `(${args.id})`) : undefined,
+  });
+}
+
+export function buildExpanded(details: StopDetails, theme: Theme): Container {
+  return buildProcessDetails(details.result.info, theme);
+}
+
+export function buildCollapsed(details: StopDetails, theme: Theme): Container {
+  const container = new Container();
+  container.addChild(buildCompactProcessLine(details.result.info, theme));
+  if (!details.result.ok) {
+    container.addChild(buildField("reason", details.result.reason, theme));
+  }
+  return container;
+}
+
+export function buildFooter(
+  _details: StopDetails,
+  _options: { expanded?: boolean },
+  _theme: Theme,
+): Container | null {
+  return null;
+}