pi-workflow-engine 0.10.3 → 0.12.0

package/.pi/extensions/pi-workflow-engine/src/process-runner.ts

@@ -1,11 +1,13 @@
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import { performance } from "node:perf_hooks";
+import { unknownErrorMessage } from "./unknown-error.ts";
 
 export interface BoundedProcessOptions {
   readonly file: string;
   readonly args: readonly string[];
   readonly cwd: string;
   readonly env?: NodeJS.ProcessEnv;
+  readonly stdin?: string | Uint8Array;
   readonly signal?: AbortSignal;
   readonly timeoutMs: number;
   readonly maxBufferBytes?: number;
@@ -16,81 +18,243 @@ export interface BoundedProcessOptions {
   readonly exitError: (stderr: string, code: number | null, signal: NodeJS.Signals | null) => string;
 }
 
-export interface BoundedProcessResult {
-  readonly ok: boolean;
+interface BoundedProcessResultBase {
   readonly stdout: string;
   readonly stderr: string;
   readonly durationMs: number;
   readonly bytes: number;
-  readonly error?: string;
 }
 
-export async function runBoundedProcess(options: BoundedProcessOptions): Promise<BoundedProcessResult> {
+export interface UnconfirmedProcessTermination {
+  readonly status: "unconfirmed";
+  readonly reason: string;
+}
+
+export type BoundedProcessFailure =
+  | { readonly kind: "spawn" | "abort" | "timeout" | "max-buffer"; readonly message: string }
+  | {
+      readonly kind: "exit";
+      readonly message: string;
+      readonly code: number | null;
+      readonly signal: NodeJS.Signals | null;
+    };
+
+export type BoundedProcessResult =
+  | (BoundedProcessResultBase & { readonly ok: true; readonly error?: undefined; readonly failure?: undefined })
+  | (BoundedProcessResultBase & {
+      readonly ok: false;
+      /** Backward-compatible display message. Branch on `failure.kind` for control flow. */
+      readonly error: string;
+      readonly failure: BoundedProcessFailure;
+      /** Present only when the runner's final bound elapsed without observing child closure. */
+      readonly termination?: UnconfirmedProcessTermination;
+    });
+
+export type WindowsTaskkillResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: string };
+
+export interface ProcessRunnerDependencies {
+  readonly platform: NodeJS.Platform;
+  readonly runWindowsTaskkill: (pid: number, complete: (result: WindowsTaskkillResult) => void) => void;
+  readonly killChild: (child: ChildProcess, signal: NodeJS.Signals) => boolean;
+}
+
+const NODE_PROCESS_RUNNER_DEPENDENCIES: ProcessRunnerDependencies = {
+  platform: process.platform,
+  runWindowsTaskkill(pid, complete) {
+    let completed = false;
+    const finish = (result: WindowsTaskkillResult) => {
+      if (completed) return;
+      completed = true;
+      complete(result);
+    };
+    try {
+      const killer = spawn("taskkill.exe", ["/pid", String(pid), "/t", "/f"], {
+        detached: false,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      killer.once("error", (error) => finish({ ok: false, reason: `taskkill failed to start: ${unknownErrorMessage(error)}` }));
+      killer.once("close", (code, signal) => {
+        if (code === 0) {
+          finish({ ok: true });
+          return;
+        }
+        finish({
+          ok: false,
+          reason: `taskkill exited with ${code === null ? `signal ${signal ?? "unknown"}` : `code ${code}`}`,
+        });
+      });
+      killer.unref();
+    } catch (error) {
+      finish({ ok: false, reason: `taskkill could not be started: ${unknownErrorMessage(error)}` });
+    }
+  },
+  killChild: (child, signal) => child.kill(signal),
+};
+
+export async function runBoundedProcess(
+  options: BoundedProcessOptions,
+  dependencies: ProcessRunnerDependencies = NODE_PROCESS_RUNNER_DEPENDENCIES,
+): Promise<BoundedProcessResult> {
   const start = performance.now();
   let stdout = "";
   let stderr = "";
   let bytes = 0;
-  let error: string | undefined;
+  let pendingFailure: BoundedProcessFailure | undefined;
   const child = spawn(options.file, [...options.args], {
     cwd: options.cwd,
     env: options.env ?? process.env,
-    stdio: ["ignore", "pipe", "pipe"],
+    detached: dependencies.platform !== "win32",
+    stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
   });
 
   return await new Promise<BoundedProcessResult>((resolve) => {
     let settled = false;
     let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+    let hardSettleTimer: ReturnType<typeof setTimeout> | undefined;
+    let directChildKillAttempted = false;
+    let windowsTerminationReason = "process close was not observed after taskkill and direct-child fallback";
     const killGraceMs = Math.max(1, options.killGraceMs ?? 100);
-    const finish = (ok: boolean, finishError?: string) => {
+    const cleanup = () => {
+      clearTimeout(timeout);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      if (hardSettleTimer) clearTimeout(hardSettleTimer);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+    const finish = (failure?: BoundedProcessFailure, termination?: UnconfirmedProcessTermination) => {
       if (settled) return;
       settled = true;
       cleanup();
-      resolve({ ok, stdout, stderr, durationMs: performance.now() - start, bytes, error: finishError });
+      const base = { stdout, stderr, durationMs: performance.now() - start, bytes };
+      if (!failure) {
+        resolve({ ...base, ok: true });
+        return;
+      }
+      resolve({ ...base, ok: false, error: failure.message, failure, ...(termination ? { termination } : {}) });
     };
-    const kill = (message: string) => {
-      error = error ?? message;
-      child.kill("SIGTERM");
-      forceKillTimer ??= setTimeout(() => {
-        child.kill("SIGKILL");
-        finish(false, error);
-      }, killGraceMs);
+    const killDirectChild = (signal: NodeJS.Signals, reason: string) => {
+      if (directChildKillAttempted) return;
+      directChildKillAttempted = true;
+      windowsTerminationReason = reason;
+      try {
+        if (!dependencies.killChild(child, signal)) {
+          windowsTerminationReason = `${reason}; direct-child termination was not accepted`;
+        }
+      } catch (error) {
+        windowsTerminationReason = `${reason}; direct-child termination failed: ${unknownErrorMessage(error)}`;
+      }
     };
-    const onAbort = () => kill(options.abortError);
-    const timeout = setTimeout(() => kill(options.timeoutError), options.timeoutMs);
-    const cleanup = () => {
-      clearTimeout(timeout);
-      if (forceKillTimer) clearTimeout(forceKillTimer);
-      options.signal?.removeEventListener("abort", onAbort);
+    const signalPosixProcess = (signal: NodeJS.Signals) => {
+      let groupSignalled = false;
+      if (child.pid !== undefined) {
+        try {
+          process.kill(-child.pid, signal);
+          groupSignalled = true;
+        } catch {
+          // The process may have exited before its descendants released stdio.
+          // Fall back to the direct child below.
+        }
+      }
+      if (!groupSignalled) {
+        try {
+          dependencies.killChild(child, signal);
+        } catch {
+          // The hard-settlement timer remains authoritative when signalling fails.
+        }
+      }
     };
+    const destroyStdio = () => {
+      child.stdin?.destroy();
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+    };
+    const terminate = (failure: BoundedProcessFailure) => {
+      pendingFailure ??= failure;
+      if (forceKillTimer) return;
+      if (dependencies.platform === "win32") {
+        if (child.pid === undefined) {
+          killDirectChild("SIGKILL", "taskkill was unavailable because the child process had no pid");
+        } else {
+          try {
+            dependencies.runWindowsTaskkill(child.pid, (result) => {
+              if (settled || result.ok) return;
+              killDirectChild("SIGKILL", result.reason);
+            });
+          } catch (error) {
+            killDirectChild("SIGKILL", `taskkill invocation failed: ${unknownErrorMessage(error)}`);
+          }
+        }
+      } else {
+        signalPosixProcess("SIGTERM");
+      }
+      forceKillTimer = setTimeout(() => {
+        if (dependencies.platform === "win32") {
+          if (directChildKillAttempted) {
+            windowsTerminationReason = `${windowsTerminationReason}; child did not close within the termination grace period`;
+          } else {
+            killDirectChild("SIGKILL", "taskkill did not close the child within the termination grace period");
+          }
+        } else {
+          signalPosixProcess("SIGKILL");
+        }
+        destroyStdio();
+        if (!settled) {
+          hardSettleTimer = setTimeout(() => {
+            if (!pendingFailure) return;
+            finish(
+              pendingFailure,
+              { status: "unconfirmed", reason: dependencies.platform === "win32"
+                ? windowsTerminationReason
+                : "process close was not observed after forced process-group termination" },
+            );
+          }, killGraceMs);
+        }
+      }, killGraceMs);
+    };
+    const onAbort = () => terminate({ kind: "abort", message: options.abortError });
+    const timeout = setTimeout(() => terminate({ kind: "timeout", message: options.timeoutError }), options.timeoutMs);
 
-    if (options.signal?.aborted) {
-      kill(options.abortError);
-    } else {
-      options.signal?.addEventListener("abort", onAbort, { once: true });
-    }
-
-    child.stdout?.on("data", (chunk: Buffer) => {
+    const captureChunk = (chunk: Buffer, append: (text: string) => void) => {
+      if (pendingFailure) return;
       bytes += chunk.length;
       if (options.maxBufferBytes !== undefined && bytes > options.maxBufferBytes) {
-        kill(options.maxBufferError ?? `process output exceeded ${options.maxBufferBytes} bytes`);
+        terminate({
+          kind: "max-buffer",
+          message: options.maxBufferError ?? `process output exceeded ${options.maxBufferBytes} bytes`,
+        });
         return;
       }
-      stdout += chunk.toString("utf8");
-    });
-    child.stderr?.on("data", (chunk: Buffer) => {
-      stderr += chunk.toString("utf8");
+      append(chunk.toString("utf8"));
+    };
+    child.stdout?.on("data", (chunk: Buffer) => captureChunk(chunk, (text) => (stdout += text)));
+    child.stderr?.on("data", (chunk: Buffer) => captureChunk(chunk, (text) => (stderr += text)));
+    child.on("error", (spawnError) => {
+      if (!pendingFailure) finish({ kind: "spawn", message: spawnError.message });
     });
-    child.on("error", (spawnError) => finish(false, spawnError.message));
     child.on("close", (code, signal) => {
-      if (error) {
-        finish(false, error);
+      if (pendingFailure) {
+        finish(pendingFailure);
         return;
       }
       if (code === 0) {
-        finish(true);
+        finish();
         return;
       }
-      finish(false, options.exitError(stderr, code, signal));
+      const message = options.exitError(stderr, code, signal);
+      finish({ kind: "exit", message, code, signal });
     });
+    if (options.signal?.aborted) {
+      onAbort();
+    } else {
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+    }
+    if (options.stdin !== undefined) {
+      // The child may reject input and exit before consuming it. Its process exit
+      // remains the authoritative result; avoid surfacing a secondary EPIPE.
+      child.stdin?.on("error", () => undefined);
+      child.stdin?.end(options.stdin);
+    }
   });
 }

package/.pi/extensions/pi-workflow-engine/src/progress-types.ts

@@ -0,0 +1,50 @@
+import type { WorkflowUsageSnapshot } from "./usage.ts";
+
+export type AgentRowStatus = "queued" | "running" | "done" | "failed";
+export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
+
+export interface AgentRowSnapshot {
+  readonly id: number;
+  readonly label: string;
+  readonly status: AgentRowStatus;
+  readonly startedAt?: number;
+  readonly doneAt?: number;
+  readonly toolUses: number;
+  readonly lastTool?: string;
+  readonly error?: string;
+}
+
+export interface PhaseSnapshot {
+  readonly title: string;
+  readonly agents: readonly AgentRowSnapshot[];
+}
+
+export interface WorkflowCounterSnapshot {
+  readonly key: string;
+  readonly label: string;
+  readonly value: number;
+}
+
+export interface WorkflowLaneItemSnapshot {
+  readonly lane: string;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly status: WorkflowLaneItemStatus;
+  readonly details?: string;
+  readonly createdAt: number;
+}
+
+export interface WorkflowProgressSnapshot {
+  readonly runId: string;
+  readonly title: string;
+  readonly startedAt: number;
+  readonly doneAt?: number;
+  readonly currentPhase: string;
+  readonly phases: readonly PhaseSnapshot[];
+  readonly counters: readonly WorkflowCounterSnapshot[];
+  readonly summary: readonly [string, string | number][];
+  readonly lanes: readonly [string, readonly WorkflowLaneItemSnapshot[]][];
+  readonly laneOverflow: readonly [string, number][];
+  readonly logs: readonly string[];
+  readonly usage?: WorkflowUsageSnapshot;
+}

package/.pi/extensions/pi-workflow-engine/src/progress.ts

@@ -1,54 +1,20 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { TUI } from "@earendil-works/pi-tui";
-import type { WorkflowLaneItemStatus, WorkflowProgressEvent } from "./types.ts";
+import type { WorkflowProgressEvent } from "./types.ts";
+import type { AgentRowStatus, WorkflowLaneItemStatus, WorkflowProgressSnapshot } from "./progress-types.ts";
+import { formatWorkflowUsageLine, type WorkflowUsageSnapshot } from "./usage.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 import { statusTextFromCounts, type WorkflowStatusCounts } from "./ui/workflow-format.ts";
-import { createWorkflowWidget, type WorkflowWidget } from "./ui/workflow-widget.ts";
-
-export type AgentRowStatus = "queued" | "running" | "done" | "failed";
-
-export interface AgentRowSnapshot {
-  readonly id: number;
-  readonly label: string;
-  readonly status: AgentRowStatus;
-  readonly startedAt?: number;
-  readonly doneAt?: number;
-  readonly toolUses: number;
-  readonly lastTool?: string;
-  readonly error?: string;
-}
-
-export interface PhaseSnapshot {
-  readonly title: string;
-  readonly agents: readonly AgentRowSnapshot[];
-}
-
-export interface WorkflowCounterSnapshot {
-  readonly key: string;
-  readonly label: string;
-  readonly value: number;
-}
-
-export interface WorkflowLaneItemSnapshot {
-  readonly lane: string;
-  readonly title: string;
-  readonly subtitle?: string;
-  readonly status: WorkflowLaneItemStatus;
-  readonly details?: string;
-  readonly createdAt: number;
-}
-
-export interface WorkflowProgressSnapshot {
-  readonly title: string;
-  readonly startedAt: number;
-  readonly doneAt?: number;
-  readonly currentPhase: string;
-  readonly phases: readonly PhaseSnapshot[];
-  readonly counters: readonly WorkflowCounterSnapshot[];
-  readonly summary: readonly [string, string | number][];
-  readonly lanes: readonly [string, readonly WorkflowLaneItemSnapshot[]][];
-  readonly laneOverflow: readonly [string, number][];
-  readonly logs: readonly string[];
-}
+import { renderWorkflowWidgetLines } from "./ui/workflow-widget.ts";
+
+export type {
+  AgentRowSnapshot,
+  AgentRowStatus,
+  PhaseSnapshot,
+  WorkflowCounterSnapshot,
+  WorkflowLaneItemSnapshot,
+  WorkflowLaneItemStatus,
+  WorkflowProgressSnapshot,
+} from "./progress-types.ts";
 
 interface AgentRow {
   id: number;
@@ -82,6 +48,7 @@ interface WorkflowLaneItem {
 }
 
 const LOG_LIMIT = 24;
+const WIDGET_REFRESH_INTERVAL_MS = 1_000;
 export const DEFAULT_LANE_ITEM_LIMIT = 200;
 
 /**
@@ -102,17 +69,18 @@ export class ProgressTracker {
   private doneAt: number | undefined;
   private currentPhase = "Workflow";
   private nextAgentId = 1;
-  private widget: WorkflowWidget | undefined;
-  private widgetRegistered = false;
-  private tui: Pick<TUI, "requestRender"> | undefined;
-  private widgetInterval: ReturnType<typeof setInterval> | undefined;
   private lastStatusText: string | undefined;
-  private renderQueued = false;
+  private usageSnapshot: WorkflowUsageSnapshot | undefined;
+  private widgetRefreshInterval: ReturnType<typeof setInterval> | undefined;
+  private readonly surfaceKey: string;
 
   constructor(
     private readonly ctx: ExtensionContext,
     private readonly title: string,
+    private readonly runId: string,
+    private readonly onSnapshot?: (snapshot: WorkflowProgressSnapshot) => void,
   ) {
+    this.surfaceKey = `workflow:${runId}`;
     this.ensurePhase(this.currentPhase);
   }
 
@@ -129,14 +97,14 @@ export class ProgressTracker {
     this.currentPhase = title;
     this.ensurePhase(title);
     if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${title}\n`);
-    this.render();
+    this.publish();
   }
 
   log(message: string): void {
     this.logs.push(message);
     while (this.logs.length > LOG_LIMIT) this.logs.shift();
     if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${message}\n`);
-    this.render();
+    this.publish();
   }
 
   event(event: WorkflowProgressEvent): void {
@@ -171,7 +139,7 @@ export class ProgressTracker {
         this.summary.set(event.key, event.value);
         break;
     }
-    this.render();
+    this.publish();
   }
 
   agentQueued(phase: string | undefined, label: string): number {
@@ -180,7 +148,7 @@ export class ProgressTracker {
     this.ensurePhase(phase ?? this.currentPhase).agents.push(row);
     this.rowsById.set(id, row);
     this.agentCounts.queued++;
-    this.render();
+    this.publish();
     return id;
   }
 
@@ -202,7 +170,7 @@ export class ProgressTracker {
       this.rowsById.set(nextRow.id, nextRow);
       this.agentCounts.running++;
     }
-    this.render();
+    this.publish();
   }
 
   agentTool(label: string, tool: string, id?: number): void {
@@ -211,7 +179,7 @@ export class ProgressTracker {
       row.lastTool = tool;
       row.toolUses += 1;
     }
-    this.render();
+    this.publish();
   }
 
   agentDone(label: string, id?: number): void {
@@ -220,7 +188,7 @@ export class ProgressTracker {
       this.transitionAgentStatus(row, "done");
       row.doneAt = Date.now();
     }
-    this.render();
+    this.publish();
   }
 
   agentFailed(label: string, error: unknown, id?: number): void {
@@ -228,13 +196,19 @@ export class ProgressTracker {
     if (row) {
       this.transitionAgentStatus(row, "failed");
       row.doneAt = Date.now();
-      row.error = errorMessage(error);
+      row.error = unknownErrorMessage(error);
     }
-    this.render();
+    this.publish();
+  }
+
+  updateUsage(snapshot: WorkflowUsageSnapshot): void {
+    this.usageSnapshot = snapshot;
+    this.publish();
   }
 
   snapshot(): WorkflowProgressSnapshot {
     return {
+      runId: this.runId,
       title: this.title,
       startedAt: this.startedAt,
       doneAt: this.doneAt,
@@ -248,6 +222,7 @@ export class ProgressTracker {
       lanes: [...this.lanes.entries()].map(([lane, items]) => [lane, items.map((item) => ({ ...item }))]),
       laneOverflow: [...this.laneOverflow.entries()],
       logs: [...this.logs],
+      usage: this.usageSnapshot,
     };
   }
 
@@ -299,25 +274,35 @@ export class ProgressTracker {
     return this.rowsById.get(id);
   }
 
-  private render(): void {
+  private publish(): void {
+    this.publishSnapshot();
     if (!this.ctx.hasUI) return;
-    this.ensureWidget();
-    this.widget?.invalidate();
-    this.requestRenderSoon();
+    this.publishWidget();
+    this.startWidgetRefresh();
     this.publishStatus();
   }
 
-  private requestRenderSoon(): void {
-    if (this.renderQueued) return;
-    this.renderQueued = true;
-    queueMicrotask(() => {
-      this.renderQueued = false;
-      this.tui?.requestRender();
-    });
+  private publishWidget(): void {
+    this.ctx.ui.setWidget(
+      this.surfaceKey,
+      renderWorkflowWidgetLines(this.snapshot(), this.ctx.ui.theme),
+      { placement: "aboveEditor" },
+    );
+  }
+
+  private startWidgetRefresh(): void {
+    if (this.widgetRefreshInterval !== undefined) return;
+    this.widgetRefreshInterval = setInterval(() => this.publishWidget(), WIDGET_REFRESH_INTERVAL_MS);
+  }
+
+  private stopWidgetRefresh(): void {
+    if (this.widgetRefreshInterval === undefined) return;
+    clearInterval(this.widgetRefreshInterval);
+    this.widgetRefreshInterval = undefined;
   }
 
   private publishStatus(): void {
-    const next = statusTextFromCounts(
+    const status = statusTextFromCounts(
       {
         title: this.title,
         doneAt: this.doneAt,
@@ -327,55 +312,26 @@ export class ProgressTracker {
       this.statusCountsSnapshot(),
       this.ctx.ui.theme,
     );
+    const usage = formatWorkflowUsageLine(this.usageSnapshot);
+    const next = usage ? `${status} · ${usage}` : status;
     if (next === this.lastStatusText) return;
-    this.ctx.ui.setStatus("workflow", next);
+    this.ctx.ui.setStatus(this.surfaceKey, next);
     this.lastStatusText = next;
   }
 
-  private ensureWidget(): void {
-    if (this.widgetRegistered) return;
-    this.widget = createWorkflowWidget(() => this.snapshot());
-    this.ctx.ui.setWidget(
-      "workflow",
-      (tui, theme) => {
-        this.tui = tui;
-        return {
-          render: (width?: number) => this.widget?.render(width ?? tui.terminal.columns, theme) ?? [],
-          invalidate: () => this.widget?.invalidate(),
-        };
-      },
-      { placement: "aboveEditor" },
-    );
-    this.widgetRegistered = true;
-    this.startWidgetTimer();
-  }
-
-  private startWidgetTimer(): void {
-    if (this.widgetInterval !== undefined) return;
-    this.widgetInterval = setInterval(() => {
-      this.widget?.nextFrame();
-      this.tui?.requestRender();
-    }, 100);
-  }
-
-  private stopWidgetTimer(): void {
-    if (this.widgetInterval === undefined) return;
-    clearInterval(this.widgetInterval);
-    this.widgetInterval = undefined;
-  }
-
-  /** Clear live workflow surfaces; optionally leave a one-line final status. */
-  done(status?: string): void {
+  /** Clear this run's live workflow surfaces. Final feedback is delivered by the result surface. */
+  done(): void {
     this.doneAt = Date.now();
-    this.stopWidgetTimer();
+    this.stopWidgetRefresh();
+    this.publishSnapshot();
     if (!this.ctx.hasUI) return;
-    this.ctx.ui.setWidget("workflow", undefined);
-    this.ctx.ui.setStatus("workflow", status);
-    this.lastStatusText = status;
-    this.renderQueued = false;
-    this.widgetRegistered = false;
-    this.widget = undefined;
-    this.tui = undefined;
+    this.ctx.ui.setWidget(this.surfaceKey, undefined);
+    this.ctx.ui.setStatus(this.surfaceKey, undefined);
+    this.lastStatusText = undefined;
+  }
+
+  private publishSnapshot(): void {
+    this.onSnapshot?.(this.snapshot());
   }
 }
 
@@ -384,7 +340,3 @@ function laneItemLimitFromEnv(): number {
   if (!Number.isFinite(parsed) || parsed < 1) return DEFAULT_LANE_ITEM_LIMIT;
   return Math.trunc(parsed);
 }
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}