@aliou/pi-processes 0.9.4 → 0.10.0

package/extensions/processes/config/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Extension config types.
+ *
+ * User-facing schema is ProcessConfig (all fields optional).
+ * Runtime config uses the shared protocol shape returned by REQUEST_CONFIG.
+ */
+
+import type { ProcessProtocolConfig } from "../../../src/protocol";
+
+export interface ExecutionConfig {
+  /** Absolute shell executable used to run process commands. */
+  shellPath?: string;
+}
+
+export interface InterceptionConfig {
+  /** Block shell background patterns and redirect the agent to the process tool. */
+  blockBackgroundCommands?: boolean;
+}
+
+export interface ProcessListConfig {
+  /** Maximum log rows displayed in the overview preview and logs overlay. */
+  maxPreviewLines?: number;
+  /** Maximum process rows displayed in the overview before scrolling. */
+  maxVisibleProcesses?: number;
+}
+
+export interface OutputConfig {
+  /** Default number of recent lines returned by the process output action. */
+  defaultTailLines?: number;
+  /** Maximum lines retained by process log interfaces. */
+  maxOutputLines?: number;
+  /** Maximum bytes retained by each process log interface. */
+  maxOutputBytes?: number;
+}
+
+export interface FollowConfig {
+  /** Open process log interfaces in follow mode by default. */
+  enabledByDefault?: boolean;
+  /** Hide process log interfaces when all managed processes finish. */
+  autoHideOnFinish?: boolean;
+}
+
+export interface WidgetConfig {
+  /** Show a one-line process summary below the editor. */
+  showStatusWidget?: boolean;
+  /** Initial visibility of the process dock. */
+  dockDefaultState?: "closed" | "collapsed" | "expanded";
+  /** Number of log rows displayed in the expanded process dock. */
+  dockHeight?: number;
+}
+
+/** User-facing pi-processes settings stored on disk. */
+export interface ProcessConfig {
+  /** JSON Schema URL used by editors for validation and autocomplete. */
+  $schema?: string;
+  /** Config migration marker written after v0.10.0 settings migration. */
+  version?: string;
+  /** Process execution settings. */
+  execution?: ExecutionConfig;
+  /** Shell-command interception settings. */
+  interception?: InterceptionConfig;
+  /** Process overview and log viewport settings. */
+  processList?: ProcessListConfig;
+  /** Process output retention settings. */
+  output?: OutputConfig;
+  /** Live log follow behavior. */
+  follow?: FollowConfig;
+  /** Dock and status widget settings. */
+  widget?: WidgetConfig;
+}
+
+export type { ProcessProtocolConfig };

package/extensions/processes/constants.ts

@@ -0,0 +1 @@
+export const MESSAGE_TYPE_PROCESS_NOTIFICATION = "ad-process:notification";

package/extensions/processes/handlers/commands.ts

@@ -0,0 +1,113 @@
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+
+import type { ProcessManager } from "../../../src/manager";
+import {
+  CHANNELS,
+  type CommandClearPayload,
+  type CommandKillPayload,
+} from "../../../src/protocol";
+import type { KillResult } from "../../../src/types";
+import { isRecord } from "../../../src/utils/is-record";
+import type { NotificationRegistry } from "../notifications/registry";
+import { killIntentionally } from "./kill-process";
+
+export function registerCommandHandlers(
+  events: EventBus,
+  manager: ProcessManager,
+  notifications: NotificationRegistry,
+): () => void {
+  const disposers = [
+    events.on(CHANNELS.COMMAND_KILL, (payload) => {
+      const command = payload as CommandKillPayload;
+      if (!isCommandKillPayload(command)) return;
+
+      void killIntentionally(manager, notifications, command.id, {
+        signal: command.signal,
+        timeoutMs: command.timeoutMs,
+      }).then(
+        (result) => safeReply(command.reply, result),
+        () => safeReply(command.reply, createKillErrorResult(command.id)),
+      );
+    }),
+    events.on(CHANNELS.COMMAND_CLEAR, (payload) => {
+      const command = payload as CommandClearPayload;
+      if (!isCommandClearPayload(command)) return;
+
+      safeReply(command.reply, manager.clearFinished());
+    }),
+  ];
+
+  return () => {
+    for (const dispose of disposers) dispose();
+  };
+}
+
+function isCommandKillPayload(
+  payload: CommandKillPayload,
+): payload is CommandKillPayload {
+  return (
+    isRecord(payload) &&
+    typeof payload.id === "string" &&
+    isOptionalSignal(payload.signal) &&
+    isOptionalNumber(payload.timeoutMs) &&
+    isReply(payload)
+  );
+}
+
+function isCommandClearPayload(
+  payload: CommandClearPayload,
+): payload is CommandClearPayload {
+  return isRecord(payload) && isReply(payload);
+}
+
+function isReply(
+  payload: unknown,
+): payload is { reply: (...args: never[]) => void } {
+  return isRecord(payload) && typeof payload.reply === "function";
+}
+
+function isOptionalSignal(
+  signal: unknown,
+): signal is NodeJS.Signals | undefined {
+  return signal === undefined || typeof signal === "string";
+}
+
+function isOptionalNumber(value: unknown): value is number | undefined {
+  return (
+    value === undefined || (typeof value === "number" && Number.isFinite(value))
+  );
+}
+
+function safeReply<T>(reply: (result: T) => void, result: T): void {
+  try {
+    reply(result);
+  } catch {
+    // Reply callbacks are owned by the requester. Never let a bad requester
+    // break shared command listeners or create unhandled promise rejections.
+    return;
+  }
+}
+
+function createKillErrorResult(id: string): KillResult {
+  return {
+    ok: false,
+    reason: "error",
+    info: {
+      id,
+      name: "(unknown)",
+      pid: -1,
+      command: "",
+      cwd: "",
+      startTime: 0,
+      endTime: null,
+      status: "exited",
+      exitCode: null,
+      success: false,
+      stdoutFile: "",
+      stderrFile: "",
+      endReason: null,
+      signal: null,
+      errorMessage: "Failed to kill process",
+    },
+  };
+}

package/extensions/processes/handlers/kill-process.ts

@@ -0,0 +1,31 @@
+import type { ProcessManager } from "../../../src/manager";
+import type { KillResult } from "../../../src/types";
+import { LIVE_STATUSES } from "../../../src/types";
+import type { NotificationRegistry } from "../notifications/registry";
+
+export async function killIntentionally(
+  manager: ProcessManager,
+  notifications: NotificationRegistry,
+  id: string,
+  opts?: { signal?: NodeJS.Signals; timeoutMs?: number },
+): Promise<KillResult> {
+  notifications.markIntentionalStop(id);
+
+  let result: KillResult;
+  try {
+    result = await manager.kill(id, opts);
+  } catch {
+    notifications.consumeIntentionalStop(id);
+    throw new Error(`process stop failed for ${id}`);
+  }
+
+  if (!result.ok) {
+    if (result.reason === "not_found" || result.reason === "error") {
+      notifications.consumeIntentionalStop(id);
+    }
+  } else if (!LIVE_STATUSES.has(result.info.status)) {
+    notifications.consumeIntentionalStop(id);
+  }
+
+  return result;
+}

package/extensions/processes/handlers/notifications.ts

@@ -0,0 +1,147 @@
+import type { EventBus, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import {
+  CHANNELS,
+  type ProcessProtocolNotificationPayload,
+} from "../../../src/protocol";
+import { isRecord } from "../../../src/utils/is-record";
+import {
+  attentionToSendOptions,
+  sendProcessNotificationMessage,
+} from "../notification-sender";
+
+const NOTIFICATION_WINDOW_MS = 60_000;
+const MAX_LOG_MATCH_NOTIFICATIONS_PER_WINDOW = 20;
+
+/**
+ * Delivers notification events emitted on {@link CHANNELS.NOTIFICATION} to Pi as
+ * persisted custom messages. This is the core side of the notification fanout:
+ * the NotificationService emits language-neutral payloads, and this listener
+ * converts each payload into a displayed `ad-process:notification` message with
+ * the attention-derived send options. UI extensions observe the same channel
+ * for display concerns (e.g. log-match highlighting) without importing this
+ * module.
+ *
+ * Returns a disposer that removes the listener; it must be called on
+ * `session_shutdown` before the manager is killed.
+ */
+export function registerNotificationDelivery(
+  events: EventBus,
+  pi: ExtensionAPI,
+): () => void {
+  let windowStart: number | null = null;
+  let sentInWindow = 0;
+  let suppressed = 0;
+  let summaryTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const clearSummaryTimer = () => {
+    if (!summaryTimer) return;
+    clearTimeout(summaryTimer);
+    summaryTimer = null;
+  };
+
+  const resetWindow = (): number => {
+    clearSummaryTimer();
+    const count = suppressed;
+    windowStart = null;
+    sentInWindow = 0;
+    suppressed = 0;
+    return count;
+  };
+
+  const sendSuppressedSummary = (count: number) => {
+    if (count === 0) return;
+    const details: ProcessProtocolNotificationPayload = {
+      kind: "log_match_suppressed",
+      processId: "*",
+      processName: "log watches",
+      command: "",
+      timestamp: Date.now(),
+      summary: `Suppressed ${count} log-match notifications because output was too fast.`,
+      attention: "context",
+    };
+    sendProcessNotificationMessage(pi, details, {
+      triggerTurn: false,
+      deliverAs: "steer",
+    });
+  };
+
+  const flushSuppressedSummary = () => {
+    const count = resetWindow();
+    sendSuppressedSummary(count);
+  };
+
+  const startWindow = (now: number) => {
+    windowStart = now;
+    sentInWindow = 0;
+    suppressed = 0;
+    clearSummaryTimer();
+    summaryTimer = setTimeout(flushSuppressedSummary, NOTIFICATION_WINDOW_MS);
+    summaryTimer.unref?.();
+  };
+
+  const disposeListener = events.on(
+    CHANNELS.NOTIFICATION,
+    (payload: unknown) => {
+      if (!isNotificationPayload(payload)) return;
+
+      if (payload.kind === "log_match") {
+        const now = performance.now();
+        if (
+          windowStart === null ||
+          now - windowStart >= NOTIFICATION_WINDOW_MS
+        ) {
+          const previousSuppressed = windowStart === null ? 0 : resetWindow();
+          startWindow(now);
+          sendSuppressedSummary(previousSuppressed);
+        }
+        if (sentInWindow >= MAX_LOG_MATCH_NOTIFICATIONS_PER_WINDOW) {
+          suppressed++;
+          return;
+        }
+        sentInWindow++;
+      }
+
+      const options = attentionToSendOptions(payload.attention);
+      sendProcessNotificationMessage(pi, payload, options);
+    },
+  );
+
+  return () => {
+    disposeListener();
+    resetWindow();
+  };
+}
+
+function isNotificationPayload(
+  payload: unknown,
+): payload is ProcessProtocolNotificationPayload {
+  if (!isRecord(payload)) return false;
+  if (!isNotificationKind(payload.kind)) return false;
+  if (typeof payload.processId !== "string") return false;
+  if (typeof payload.processName !== "string") return false;
+  if (typeof payload.command !== "string") return false;
+  if (typeof payload.timestamp !== "number") return false;
+  if (typeof payload.summary !== "string") return false;
+  if (
+    payload.attention !== "turn" &&
+    payload.attention !== "context" &&
+    payload.attention !== "ignore"
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function isNotificationKind(
+  value: unknown,
+): value is ProcessProtocolNotificationPayload["kind"] {
+  return (
+    value === "success" ||
+    value === "failure" ||
+    value === "crash" ||
+    value === "killed" ||
+    value === "log_match" ||
+    value === "log_match_suppressed"
+  );
+}

package/extensions/processes/handlers/requests.ts

@@ -0,0 +1,114 @@
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+import type { ProcessManager } from "../../../src/manager";
+import {
+  CHANNELS,
+  type RequestCombinedOutputPayload,
+  type RequestConfigPayload,
+  type RequestFileSizePayload,
+  type RequestGetPayload,
+  type RequestListPayload,
+  type RequestLogFilesPayload,
+  type RequestOutputPayload,
+} from "../../../src/protocol";
+import { isRecord } from "../../../src/utils/is-record";
+import type { ProcessProtocolConfig } from "../config";
+
+export function registerRequestHandlers(
+  events: EventBus,
+  manager: ProcessManager,
+  getConfig: () => ProcessProtocolConfig,
+): () => void {
+  const disposers = [
+    events.on(CHANNELS.REQUEST_LIST, (payload) => {
+      const request = payload as RequestListPayload;
+      if (!isRequestListPayload(request)) return;
+
+      request.reply(manager.list());
+    }),
+    events.on(CHANNELS.REQUEST_GET, (payload) => {
+      const request = payload as RequestGetPayload;
+      if (!isIdRequest(request)) return;
+
+      request.reply(manager.get(request.id));
+    }),
+    events.on(CHANNELS.REQUEST_OUTPUT, (payload) => {
+      const request = payload as RequestOutputPayload;
+      if (!isIdRequest(request)) return;
+
+      request.reply(manager.getOutput(request.id, request.tailLines));
+    }),
+    events.on(CHANNELS.REQUEST_COMBINED_OUTPUT, (payload) => {
+      const request = payload as RequestCombinedOutputPayload;
+      if (!isIdRequest(request)) return;
+
+      request.reply(manager.getCombinedOutput(request.id, request.tailLines));
+    }),
+    events.on(CHANNELS.REQUEST_LOG_FILES, (payload) => {
+      const request = payload as RequestLogFilesPayload;
+      if (!isIdRequest(request)) return;
+
+      request.reply(manager.getLogFiles(request.id));
+    }),
+    events.on(CHANNELS.REQUEST_FILE_SIZE, (payload) => {
+      const request = payload as RequestFileSizePayload;
+      if (!isIdRequest(request)) return;
+
+      request.reply(manager.getFileSize(request.id));
+    }),
+    events.on(CHANNELS.REQUEST_CONFIG, (payload) => {
+      const request = payload as RequestConfigPayload;
+      if (!isRequestConfigPayload(request)) return;
+
+      request.reply(getConfig());
+    }),
+  ];
+
+  return () => {
+    for (const dispose of disposers) dispose();
+  };
+}
+
+function isRequestListPayload(
+  payload: RequestListPayload,
+): payload is RequestListPayload {
+  return isRecord(payload) && isReply(payload);
+}
+
+function isRequestConfigPayload(
+  payload: RequestConfigPayload,
+): payload is RequestConfigPayload {
+  return isRecord(payload) && isReply(payload);
+}
+
+function isIdRequest(
+  payload:
+    | RequestGetPayload
+    | RequestOutputPayload
+    | RequestCombinedOutputPayload
+    | RequestLogFilesPayload
+    | RequestFileSizePayload,
+): payload is
+  | RequestGetPayload
+  | RequestOutputPayload
+  | RequestCombinedOutputPayload
+  | RequestLogFilesPayload
+  | RequestFileSizePayload {
+  return (
+    isRecord(payload) &&
+    typeof payload.id === "string" &&
+    isOptionalNumber(payload.tailLines) &&
+    isReply(payload)
+  );
+}
+
+function isReply(
+  payload: unknown,
+): payload is { reply: (...args: never[]) => void } {
+  return isRecord(payload) && typeof payload.reply === "function";
+}
+
+function isOptionalNumber(value: unknown): value is number | undefined {
+  return (
+    value === undefined || (typeof value === "number" && Number.isFinite(value))
+  );
+}

package/extensions/processes/handlers/subscriptions.ts

@@ -0,0 +1,144 @@
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+
+import type { ProcessManager } from "../../../src/manager";
+import {
+  CHANNELS,
+  type LogsSubscribePayload,
+  type LogsUnsubscribePayload,
+} from "../../../src/protocol";
+import { isRecord } from "../../../src/utils/is-record";
+import { buildDroppedOutputLine } from "../../shared/line-buffer";
+
+interface LogSubscriber {
+  subscriberId: string;
+  processId: string;
+}
+
+export function registerLogSubscriptions(
+  events: EventBus,
+  manager: ProcessManager,
+): () => void {
+  const subscribers = new Map<string, LogSubscriber>();
+
+  const disposeSubscribe = events.on(CHANNELS.LOGS_SUBSCRIBE, (payload) => {
+    const request = payload as LogsSubscribePayload;
+    if (!isLogsSubscribePayload(request)) return;
+
+    const processInfo = manager.get(request.processId);
+
+    if (!processInfo) {
+      request.reply({ ok: false, error: "Process not found" });
+      return;
+    }
+
+    const initialLines = manager.getCombinedOutput(
+      request.processId,
+      request.tailLines ?? 100,
+    );
+
+    if (!initialLines) {
+      request.reply({ ok: false, error: "Process logs not found" });
+      return;
+    }
+
+    subscribers.set(request.subscriberId, {
+      subscriberId: request.subscriberId,
+      processId: request.processId,
+    });
+
+    request.reply({ ok: true, initialLines });
+  });
+
+  const disposeUnsubscribe = events.on(CHANNELS.LOGS_UNSUBSCRIBE, (payload) => {
+    const request = payload as LogsUnsubscribePayload;
+    if (!isLogsUnsubscribePayload(request)) return;
+
+    subscribers.delete(request.subscriberId);
+  });
+
+  const disposeManager = manager.onEvent((event) => {
+    if (event.type === "process_ended") {
+      removeSubscribersForProcess(subscribers, event.info.id);
+      return;
+    }
+
+    if (event.type === "processes_changed") {
+      removeStaleSubscribers(subscribers, manager);
+      return;
+    }
+
+    if (event.type !== "process_output_changed") return;
+    const lines = [
+      ...(event.droppedLines
+        ? [buildDroppedOutputLine(event.droppedLines)]
+        : []),
+      ...(event.appendedText ?? []),
+    ];
+    if (lines.length === 0) return;
+
+    for (const subscriber of subscribers.values()) {
+      if (subscriber.processId !== event.id) continue;
+
+      events.emit(CHANNELS.LOGS_CHUNK, {
+        subscriberId: subscriber.subscriberId,
+        processId: subscriber.processId,
+        lines,
+      });
+    }
+  });
+
+  return () => {
+    disposeSubscribe();
+    disposeUnsubscribe();
+    disposeManager();
+    subscribers.clear();
+  };
+}
+
+function removeSubscribersForProcess(
+  subscribers: Map<string, LogSubscriber>,
+  processId: string,
+): void {
+  for (const [subscriberId, subscriber] of subscribers.entries()) {
+    if (subscriber.processId === processId) subscribers.delete(subscriberId);
+  }
+}
+
+function removeStaleSubscribers(
+  subscribers: Map<string, LogSubscriber>,
+  manager: ProcessManager,
+): void {
+  for (const [subscriberId, subscriber] of subscribers.entries()) {
+    if (!manager.get(subscriber.processId)) subscribers.delete(subscriberId);
+  }
+}
+
+function isLogsSubscribePayload(
+  payload: LogsSubscribePayload,
+): payload is LogsSubscribePayload {
+  return (
+    isRecord(payload) &&
+    typeof payload.subscriberId === "string" &&
+    typeof payload.processId === "string" &&
+    isOptionalNumber(payload.tailLines) &&
+    isReply(payload)
+  );
+}
+
+function isLogsUnsubscribePayload(
+  payload: LogsUnsubscribePayload,
+): payload is LogsUnsubscribePayload {
+  return isRecord(payload) && typeof payload.subscriberId === "string";
+}
+
+function isReply(
+  payload: unknown,
+): payload is { reply: (...args: never[]) => void } {
+  return isRecord(payload) && typeof payload.reply === "function";
+}
+
+function isOptionalNumber(value: unknown): value is number | undefined {
+  return (
+    value === undefined || (typeof value === "number" && Number.isFinite(value))
+  );
+}