@aliou/pi-processes 0.10.9 → 0.11.0

package/extensions/processes/client.ts

@@ -8,22 +8,44 @@
  */
 
 import type { EventBus } from "@earendil-works/pi-coding-agent";
+import type { KillResult, ProcessInfo } from "../../src/types";
 import {
   CHANNELS,
   type CommandClearPayload,
   type CommandKillPayload,
   type CommandPinPayload,
   type CommandPinResult,
+  type CommandStartPayload,
+  type CommandStartResult,
   type ProcessProtocolConfig,
   type RequestCombinedOutputPayload,
   type RequestConfigPayload,
   type RequestGetPayload,
   type RequestListPayload,
-} from "../../src/protocol";
-import type { KillResult, ProcessInfo } from "../../src/types";
+} from "../shared/protocol";
 
 export type ProcessLogLine = { type: "stdout" | "stderr"; text: string };
 
+/**
+ * Start a managed process via the core extension's protocol channel. Resolves
+ * when the core handler replies. The started process is fully visible to the
+ * agent via the `process` tool (list, output, stop, etc.).
+ */
+export function requestStart(
+  events: EventBus,
+  options: { name: string; command: string; cwd?: string },
+): Promise<CommandStartResult> {
+  return new Promise((resolve) => {
+    const payload: CommandStartPayload = {
+      name: options.name,
+      command: options.command,
+      cwd: options.cwd,
+      reply: (result) => resolve(result),
+    };
+    events.emit(CHANNELS.COMMAND_START, payload);
+  });
+}
+
 export function requestProcessList(events: EventBus): ProcessInfo[] {
   let processes: ProcessInfo[] = [];
   const payload: RequestListPayload = {

package/extensions/processes/commands/overview.ts

@@ -4,9 +4,9 @@ import type {
   ExtensionCommandContext,
   Theme,
 } from "@earendil-works/pi-coding-agent";
-import type { ProcessProtocolConfig } from "../../../src/protocol";
 import type { ProcessInfo } from "../../../src/types";
 import { sanitizeForDisplay } from "../../shared/display-text";
+import type { ProcessProtocolConfig } from "../../shared/protocol";
 import { requestConfig, requestProcess, requestProcessList } from "../client";
 import { OverviewComponent } from "../components/overview-component";
 

package/extensions/processes/components/overview-component.ts

@@ -4,11 +4,10 @@ import {
   type Component,
   Input,
   Key,
-  matchesKey,
+  parseKey,
   type TUI,
   visibleWidth,
 } from "@earendil-works/pi-tui";
-import { CHANNELS, type ProcessProtocolConfig } from "../../../src/protocol";
 import { LIVE_STATUSES, type ProcessInfo } from "../../../src/types";
 import { formatRuntime } from "../../../src/utils/format";
 import {
@@ -17,7 +16,20 @@ import {
 } from "../../shared/display-text";
 import { buildDroppedOutputLine, trimToBudget } from "../../shared/line-buffer";
 import { renderLogLine } from "../../shared/log-line";
-import { isOutputChangedPayload } from "../../shared/output-payload";
+import {
+  CHANNELS,
+  type ProcessesOutputChangedPayload,
+  type ProcessProtocolConfig,
+} from "../../shared/protocol";
+import {
+  SHORTCUTS_KEY,
+  type ShortcutHint,
+  ShortcutHintsComponent,
+} from "../../shared/shortcut-hints";
+import {
+  type ShortcutGroup,
+  showShortcutsOverlay,
+} from "../../shared/shortcuts-overlay";
 import { truncateToWidth } from "../../shared/truncate";
 import { LineComponent, LinesComponent, statusColor } from "../../shared/ui";
 import {
@@ -89,6 +101,8 @@ export class OverviewComponent implements Component {
   private runningProcessCount = 0;
   private readonly disposers: Array<() => void> = [];
   private disposed = false;
+  /** Disposer for the "?" shortcuts overlay, when open. */
+  private shortcutsHelp: (() => void) | null = null;
 
   constructor(private readonly opts: OverviewOptions) {
     this.configureFilterInput();
@@ -120,6 +134,34 @@ export class OverviewComponent implements Component {
     return panel.render(width);
   }
 
+  /**
+   * Key dispatch for normal mode, keyed by parsed key id. Close keys are
+   * handled in `handleInput` before the table is consulted.
+   */
+  private readonly keyActions: Record<string, () => void> = {
+    [Key.down]: () => this.moveSelection(1),
+    [Key.up]: () => this.moveSelection(-1),
+    [Key.enter]: () => void this.pinSelected(),
+    j: () => this.moveSelection(1),
+    k: () => this.moveSelection(-1),
+    J: () => this.scrollPreview(1),
+    K: () => this.scrollPreview(-1),
+    g: () => {
+      this.previewOffset = 0;
+      this.requestRender();
+    },
+    G: () => {
+      this.previewOffset = Math.max(0, this.previewLines.length - 1);
+      this.requestRender();
+    },
+    x: () => this.killSelected(),
+    c: () => this.clearFinished(),
+    s: () => this.cycleSort(),
+    f: () => this.cycleFilter(),
+    "/": () => this.startQuickFilter(),
+    [SHORTCUTS_KEY]: () => this.openShortcutsHelp(),
+  };
+
   handleInput(data: string): void {
     if (this.mode === "filter-typing") {
       this.filterInput.handleInput?.(data);
@@ -127,30 +169,13 @@ export class OverviewComponent implements Component {
       return;
     }
 
-    if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+    const key = parseKey(data);
+    if (key === "escape" || key === "ctrl+c" || key === "q" || key === "Q") {
       this.close();
       return;
     }
-    if (data === "q" || data === "Q") {
-      this.close();
-      return;
-    }
-    if (matchesKey(data, Key.down) || data === "j") this.moveSelection(1);
-    else if (matchesKey(data, Key.up) || data === "k") this.moveSelection(-1);
-    else if (data === "J") this.scrollPreview(1);
-    else if (data === "K") this.scrollPreview(-1);
-    else if (data === "g") {
-      this.previewOffset = 0;
-      this.requestRender();
-    } else if (data === "G") {
-      this.previewOffset = Math.max(0, this.previewLines.length - 1);
-      this.requestRender();
-    } else if (data === "x") this.killSelected();
-    else if (data === "c") this.clearFinished();
-    else if (data === "s") this.cycleSort();
-    else if (data === "f") this.cycleFilter();
-    else if (data === "/") this.startQuickFilter();
-    else if (matchesKey(data, Key.enter)) void this.pinSelected();
+
+    this.keyActions[key ?? ""]?.();
   }
 
   invalidate(): void {}
@@ -158,6 +183,8 @@ export class OverviewComponent implements Component {
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;
+    this.shortcutsHelp?.();
+    this.shortcutsHelp = null;
     for (const dispose of this.disposers.splice(0)) dispose();
   }
 
@@ -195,8 +222,8 @@ export class OverviewComponent implements Component {
     this.requestRender();
   }
 
-  private handleOutputChanged(payload: unknown): void {
-    if (!isOutputChangedPayload(payload)) return;
+  private handleOutputChanged(rawPayload: unknown): void {
+    const payload = rawPayload as ProcessesOutputChangedPayload;
     const selected = this.selectedProcess();
     if (!selected || selected.id !== payload.id) return;
     const appended = [
@@ -447,6 +474,19 @@ export class OverviewComponent implements Component {
     this.opts.onClose();
   }
 
+  /**
+   * Open the "?" shortcuts overlay on top of the overview. While open it
+   * captures input; closing it restores focus here. Disposed with the
+   * overview so a background close cannot leave it behind.
+   */
+  private openShortcutsHelp(): void {
+    if (this.shortcutsHelp) return;
+    this.shortcutsHelp = showShortcutsOverlay(this.opts.tui, {
+      theme: this.opts.theme,
+      groups: this.shortcutGroups(),
+    });
+  }
+
   private requestRender(): void {
     this.opts.tui.requestRender();
   }
@@ -658,35 +698,65 @@ export class OverviewComponent implements Component {
   }
 
   private buildFooter(): Component {
-    return new LineComponent((width) => this.renderFooterLine(width));
-  }
-
-  private renderFooterLine(width: number): string {
-    const t = this.opts.theme;
-    const dim = (value: string) => t.fg("dim", value);
-
     if (this.mode === "filter-typing") {
-      const rendered = this.filterInput.render(60)[0] ?? "";
-      return truncateToWidth(
-        `${dim("/")}${rendered}  ${dim("enter")} apply  ${dim("esc")} cancel`,
-        width,
-        "",
-        true,
-      );
+      return new LineComponent((width) => {
+        const dim = (value: string) => this.opts.theme.fg("dim", value);
+        const rendered = this.filterInput.render(60)[0] ?? "";
+        return truncateToWidth(
+          `${dim("/")}${rendered}  ${dim("enter")} apply  ${dim("esc")} cancel`,
+          width,
+          "",
+          true,
+        );
+      });
     }
+    return new ShortcutHintsComponent(
+      () => this.overviewHints(),
+      this.opts.theme,
+    );
+  }
+
+  /** Footer hint list for the overview. */
+  private overviewHints(): ShortcutHint[] {
+    return [
+      { key: "j/k", label: "move" },
+      { key: "J/K", label: "scroll" },
+      { key: "enter", label: this.renderPinHint() },
+      { key: "x", label: "kill" },
+      { key: "c", label: "clear" },
+      { key: "s", label: "sort" },
+      { key: "f", label: "filter" },
+      { key: "/", label: "find" },
+      { key: "g/G", label: "top/bot" },
+      { key: "q", label: "close" },
+    ];
+  }
 
-    const keys = [
-      `${dim("j/k")} move`,
-      `${dim("J/K")} scroll`,
-      `${dim("enter")} ${this.renderPinHint()}`,
-      `${dim("x")} kill`,
-      `${dim("c")} clear`,
-      `${dim("s")} sort`,
-      `${dim("f")} filter`,
-      `${dim("/")} find`,
-      `${dim("q")} close`,
+  /** Groups for the "?" shortcuts overlay. */
+  private shortcutGroups(): ShortcutGroup[] {
+    return [
+      {
+        title: "list",
+        rows: [
+          { keys: "j / k", description: "move selection" },
+          { keys: "g / G", description: "preview top / bottom" },
+          { keys: "enter", description: this.renderPinHint() },
+          { keys: "x", description: "kill" },
+          { keys: "c", description: "clear finished" },
+          { keys: "s", description: "sort" },
+          { keys: "f", description: "filter" },
+          { keys: "/", description: "find by name" },
+        ],
+      },
+      {
+        title: "preview",
+        rows: [{ keys: "J / K", description: "scroll output" }],
+      },
+      {
+        title: "general",
+        rows: [{ keys: "q", description: "close" }],
+      },
     ];
-    return truncateToWidth(keys.join("  "), width, "", true);
   }
 }
 

package/extensions/processes/config/migrations/001-v0-9-4-to-v0-10-0-config.ts

@@ -73,10 +73,6 @@ export interface ConfigV0100 {
  * - widget.showStatusWidget is preserved (still controls the status widget).
  */
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function setIfDefined<T extends object, K extends keyof T>(
   target: T,
   key: K,
@@ -120,10 +116,11 @@ export function needsConfigV094ToV0100Migration(
     return false;
   }
 
-  const root = config as Record<string, unknown>;
-  const widget = isRecord(root.widget) ? root.widget : undefined;
-
-  return widget?.dockDefaultState === "hidden";
+  // Widen to string | undefined: the incoming config predates the migration,
+  // so its dockDefaultState can be "hidden" even though the static type says
+  // it cannot.
+  const dockDefaultState: string | undefined = config.widget?.dockDefaultState;
+  return dockDefaultState === "hidden";
 }
 
 export function migrateConfigV094ToV0100(config: ConfigV094): ConfigV0100 {

package/extensions/processes/config/types.ts

@@ -5,7 +5,7 @@
  * Runtime config uses the shared protocol shape returned by REQUEST_CONFIG.
  */
 
-import type { ProcessProtocolConfig } from "../../../src/protocol";
+import type { ProcessProtocolConfig } from "../../shared/protocol";
 
 export interface ExecutionConfig {
   /** Absolute shell executable used to run process commands. */

package/extensions/processes/handlers/commands.ts

@@ -1,13 +1,13 @@
 import type { EventBus } from "@earendil-works/pi-coding-agent";
 
 import type { ProcessManager } from "../../../src/manager";
+import type { KillResult } from "../../../src/types";
 import {
   CHANNELS,
   type CommandClearPayload,
   type CommandKillPayload,
-} from "../../../src/protocol";
-import type { KillResult } from "../../../src/types";
-import { isRecord } from "../../../src/utils/is-record";
+  type CommandStartPayload,
+} from "../../shared/protocol";
 import type { NotificationRegistry } from "../notifications/registry";
 import { killIntentionally } from "./kill-process";
 
@@ -17,9 +17,26 @@ export function registerCommandHandlers(
   notifications: NotificationRegistry,
 ): () => void {
   const disposers = [
+    events.on(CHANNELS.COMMAND_START, (payload) => {
+      const command = payload as CommandStartPayload;
+
+      try {
+        const info = manager.start(
+          command.name,
+          command.command,
+          command.cwd ?? process.cwd(),
+        );
+        notifications.register(info.id, {});
+        safeReply(command.reply, { ok: true, process: info });
+      } catch (err) {
+        safeReply(command.reply, {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }),
     events.on(CHANNELS.COMMAND_KILL, (payload) => {
       const command = payload as CommandKillPayload;
-      if (!isCommandKillPayload(command)) return;
 
       void killIntentionally(manager, notifications, command.id, {
         signal: command.signal,
@@ -31,7 +48,6 @@ export function registerCommandHandlers(
     }),
     events.on(CHANNELS.COMMAND_CLEAR, (payload) => {
       const command = payload as CommandClearPayload;
-      if (!isCommandClearPayload(command)) return;
 
       safeReply(command.reply, manager.clearFinished());
     }),
@@ -42,42 +58,6 @@ export function registerCommandHandlers(
   };
 }
 
-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);

package/extensions/processes/handlers/notifications.ts

@@ -3,8 +3,7 @@ import type { EventBus, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   CHANNELS,
   type ProcessProtocolNotificationPayload,
-} from "../../../src/protocol";
-import { isRecord } from "../../../src/utils/is-record";
+} from "../../shared/protocol";
 import {
   attentionToSendOptions,
   sendProcessNotificationMessage,
@@ -83,8 +82,8 @@ export function registerNotificationDelivery(
 
   const disposeListener = events.on(
     CHANNELS.NOTIFICATION,
-    (payload: unknown) => {
-      if (!isNotificationPayload(payload)) return;
+    (rawPayload: unknown) => {
+      const payload = rawPayload as ProcessProtocolNotificationPayload;
 
       if (payload.kind === "log_match") {
         const now = performance.now();
@@ -113,36 +112,3 @@ export function registerNotificationDelivery(
     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

@@ -9,8 +9,7 @@ import {
   type RequestListPayload,
   type RequestLogFilesPayload,
   type RequestOutputPayload,
-} from "../../../src/protocol";
-import { isRecord } from "../../../src/utils/is-record";
+} from "../../shared/protocol";
 import type { ProcessProtocolConfig } from "../config";
 
 export function registerRequestHandlers(
@@ -21,43 +20,36 @@ export function registerRequestHandlers(
   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());
     }),
@@ -67,48 +59,3 @@ export function registerRequestHandlers(
     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

@@ -1,13 +1,12 @@
 import type { EventBus } from "@earendil-works/pi-coding-agent";
 
 import type { ProcessManager } from "../../../src/manager";
+import { buildDroppedOutputLine } from "../../shared/line-buffer";
 import {
   CHANNELS,
   type LogsSubscribePayload,
   type LogsUnsubscribePayload,
-} from "../../../src/protocol";
-import { isRecord } from "../../../src/utils/is-record";
-import { buildDroppedOutputLine } from "../../shared/line-buffer";
+} from "../../shared/protocol";
 
 interface LogSubscriber {
   subscriberId: string;
@@ -22,7 +21,6 @@ export function registerLogSubscriptions(
 
   const disposeSubscribe = events.on(CHANNELS.LOGS_SUBSCRIBE, (payload) => {
     const request = payload as LogsSubscribePayload;
-    if (!isLogsSubscribePayload(request)) return;
 
     const processInfo = manager.get(request.processId);
 
@@ -51,7 +49,6 @@ export function registerLogSubscriptions(
 
   const disposeUnsubscribe = events.on(CHANNELS.LOGS_UNSUBSCRIBE, (payload) => {
     const request = payload as LogsUnsubscribePayload;
-    if (!isLogsUnsubscribePayload(request)) return;
 
     subscribers.delete(request.subscriberId);
   });
@@ -112,33 +109,3 @@ function removeStaleSubscribers(
     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))
-  );
-}

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

@@ -1,7 +1,7 @@
 import type { EventBus } from "@earendil-works/pi-coding-agent";
 
 import type { ProcessManager } from "../../../src/manager";
-import { CHANNELS } from "../../../src/protocol";
+import { CHANNELS } from "../../shared/protocol";
 
 export function registerEventBridge(
   events: EventBus,

package/extensions/processes/index.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { getManager } from "../../src/get-manager";
+import { ProcessManager } from "../../src/manager";
 import { isWindowsPlatform } from "../../src/utils/platform";
 import { registerClearCommand } from "./commands/clear";
 import { registerKillCommand } from "./commands/kill";
@@ -40,7 +40,7 @@ export default async function processesExtension(
   await loadProcessConfig();
   registerMigrationMessageNotifications(pi);
 
-  const manager = getManager({
+  const manager = new ProcessManager({
     getConfiguredShellPath: () => configLoader.getConfig().execution.shellPath,
   });
   const notifications = createNotificationRegistry();