@osolmaz/pi-workflows 0.14.0 → 0.15.0

package/src/extension/message-card.ts

@@ -0,0 +1,61 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Box, Text, TruncatedText } from "@earendil-works/pi-tui";
+import { sanitizeText } from "../workflows/text.js";
+
+export type MessageCardView = {
+  title: string;
+  status?: string;
+  expandedText?: string;
+};
+
+export type MessageCardColor = "accent" | "dim" | "error" | "success" | "warning";
+
+export function renderMessageCard(view: MessageCardView, theme: Theme): Box {
+  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(new TruncatedText(view.title));
+  if (view.status !== undefined) {
+    box.addChild(new TruncatedText(view.status));
+  }
+  if (view.expandedText !== undefined) {
+    box.addChild(new Text(`\n${view.expandedText}`));
+  }
+  return box;
+}
+
+export function customMessageContentText(content: unknown): string {
+  if (typeof content === "string") return cleanMultiline(content);
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => {
+      if (part === null || typeof part !== "object" || !("text" in part)) return "";
+      const text = (part as { text?: unknown }).text;
+      return typeof text === "string" ? cleanMultiline(text) : "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function cleanOptionalSingleLine(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? cleanSingleLine(value) : undefined;
+}
+
+export function cleanSingleLine(value: string): string {
+  return sanitizeText(value);
+}
+
+export function paintMessageCard(
+  theme: Pick<Theme, "fg"> | undefined,
+  color: MessageCardColor,
+  text: string,
+): string {
+  return theme?.fg(color, text) ?? text;
+}
+
+function cleanMultiline(value: string): string {
+  return value
+    .replaceAll("\r\n", "\n")
+    .replaceAll("\r", "\n")
+    .split("\n")
+    .map((line) => sanitizeText(line))
+    .join("\n");
+}

package/src/extension/step-message.ts

@@ -1,17 +1,25 @@
 import { createHash } from "node:crypto";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
-import { Box, Text, TruncatedText } from "@earendil-works/pi-tui";
-import { sanitizeText } from "../workflows/text.js";
 import type {
   AgentStepContract,
   AgentStepPresentation,
   AgentStepSubmission,
 } from "../workflows/types.js";
-import { visibleAssistantText, type PromptDeliveryKind } from "./executor.js";
+import {
+  cleanOptionalSingleLine,
+  cleanSingleLine,
+  customMessageContentText,
+  paintMessageCard,
+  renderMessageCard,
+  type MessageCardView,
+} from "./message-card.js";
 
 export const WORKFLOW_AGENT_STEP_MESSAGE_TYPE = "pi-workflows-agent-step";
 export const WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA = "pi-workflows.agent-step-message.v1";
 
+type PromptDeliveryKind = "step" | "reminder" | "resume";
+
 export type WorkflowAgentStepMessageDetails = {
   schema: typeof WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA;
   kind: PromptDeliveryKind;
@@ -25,27 +33,13 @@ type WorkflowAgentStepMessage = {
   details?: unknown;
 };
 
-type WorkflowAgentStepView = {
-  title: string;
-  status?: string;
-  expandedText?: string;
-};
+type WorkflowAgentStepView = MessageCardView;
 
 export function registerWorkflowAgentStepMessageRenderer(pi: ExtensionAPI): void {
   pi.registerMessageRenderer<WorkflowAgentStepMessageDetails>(
     WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
-    (message, { expanded }, theme) => {
-      const view = buildWorkflowAgentStepView(message, expanded, theme);
-      const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
-      box.addChild(new TruncatedText(view.title));
-      if (view.status !== undefined) {
-        box.addChild(new TruncatedText(view.status));
-      }
-      if (view.expandedText !== undefined) {
-        box.addChild(new Text(`\n${view.expandedText}`));
-      }
-      return box;
-    },
+    (message, { expanded }, theme) =>
+      renderMessageCard(buildWorkflowAgentStepView(message, expanded, theme), theme),
   );
 }
 
@@ -65,12 +59,14 @@ export function buildWorkflowAgentStepView(
   const label = runTitle ?? workflowName;
   const suffix = kind === "step" ? "" : ` · ${kind}`;
   const glyph = kind === "step" ? "▶" : "↻";
-  const title = paint(theme, "accent", `${glyph} ${label} › ${nodeId}${suffix}`);
+  const title = paintMessageCard(theme, "accent", `${glyph} ${label} › ${nodeId}${suffix}`);
 
   if (!expanded) {
     return {
       title,
-      ...(statusDetail !== undefined ? { status: paint(theme, "dim", statusDetail) } : {}),
+      ...(statusDetail !== undefined
+        ? { status: paintMessageCard(theme, "dim", statusDetail) }
+        : {}),
     };
   }
 
@@ -88,11 +84,11 @@ export function buildWorkflowAgentStepView(
     `Completion: ${assistant ? "assistant response" : "workflow submission"}`,
     `Expected output: ${cleanSingleLine(expectedOutput)}`,
   ];
-  const prompt = contentText(message.content);
+  const prompt = customMessageContentText(message.content);
   return {
     title,
-    ...(statusDetail !== undefined ? { status: paint(theme, "dim", statusDetail) } : {}),
-    expandedText: `${metadata.map((line) => paint(theme, "dim", line)).join("\n")}\n\n${prompt}`,
+    ...(statusDetail !== undefined ? { status: paintMessageCard(theme, "dim", statusDetail) } : {}),
+    expandedText: `${metadata.map((line) => paintMessageCard(theme, "dim", line)).join("\n")}\n\n${prompt}`,
   };
 }
 
@@ -168,6 +164,43 @@ function sessionEntry(value: unknown): Record<string, unknown> | undefined {
     : undefined;
 }
 
+function assistantMessageLike(
+  message: unknown,
+): Pick<AssistantMessage, "role" | "content" | "stopReason" | "errorMessage"> | undefined {
+  if (message === null || typeof message !== "object") return undefined;
+  const candidate = message as Partial<AssistantMessage>;
+  if (candidate.role !== "assistant" || !Array.isArray(candidate.content)) return undefined;
+  if (typeof candidate.stopReason !== "string") return undefined;
+  return candidate as Pick<AssistantMessage, "role" | "content" | "stopReason" | "errorMessage">;
+}
+
+/** Extract the exact visible text blocks from one finalized assistant message. */
+export function visibleAssistantText(message: unknown, maxChars?: number): string {
+  const assistant = assistantMessageLike(message);
+  if (assistant === undefined) {
+    throw new Error("Assistant step settled without a final assistant message");
+  }
+  if (assistant.stopReason !== "stop" && assistant.stopReason !== "length") {
+    throw new Error(
+      assistant.errorMessage?.trim() ||
+        `Assistant step stopped with ${JSON.stringify(assistant.stopReason)} before a final response`,
+    );
+  }
+  const text = assistant.content
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("\n");
+  if (text.trim().length === 0) {
+    throw new Error("Assistant step returned no visible text");
+  }
+  if (maxChars !== undefined && text.length > maxChars) {
+    throw new Error(
+      `Assistant response has ${text.length} characters, above the configured limit of ${maxChars}`,
+    );
+  }
+  return text;
+}
+
 function isAssistantWithVisibleText(message: unknown): boolean {
   if (message === null || typeof message !== "object") return false;
   const candidate = message as { role?: unknown; content?: unknown; stopReason?: unknown };
@@ -208,41 +241,3 @@ function parseDetails(value: unknown): WorkflowAgentStepMessageDetails | undefin
   }
   return candidate as WorkflowAgentStepMessageDetails;
 }
-
-function contentText(content: unknown): string {
-  if (typeof content === "string") return cleanMultiline(content);
-  if (!Array.isArray(content)) return "";
-  return content
-    .map((part) => {
-      if (part === null || typeof part !== "object" || !("text" in part)) return "";
-      const text = (part as { text?: unknown }).text;
-      return typeof text === "string" ? cleanMultiline(text) : "";
-    })
-    .filter(Boolean)
-    .join("\n");
-}
-
-function cleanOptionalSingleLine(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? cleanSingleLine(value) : undefined;
-}
-
-function cleanSingleLine(value: string): string {
-  return sanitizeText(value);
-}
-
-function cleanMultiline(value: string): string {
-  return value
-    .replaceAll("\r\n", "\n")
-    .replaceAll("\r", "\n")
-    .split("\n")
-    .map((line) => sanitizeText(line))
-    .join("\n");
-}
-
-function paint(
-  theme: Pick<Theme, "fg"> | undefined,
-  color: "accent" | "dim",
-  text: string,
-): string {
-  return theme?.fg(color, text) ?? text;
-}

package/src/host/child-worker-supervisor.ts

@@ -0,0 +1,183 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { once } from "node:events";
+import { errorMessage } from "../workflows/errors.js";
+import { HostProcessRegistry, type ProcessIdentity } from "./processes.js";
+import { NdjsonFrameDecoder } from "./protocol.js";
+import type { WorkerOutcome } from "./state.js";
+
+const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;
+const DEFAULT_KILL_GRACE_MS = 2_000;
+const MAX_DIAGNOSTIC_BYTES = 64 * 1024;
+
+export type SupervisedWorkerResult = {
+  outcome: WorkerOutcome;
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  diagnostic?: string;
+};
+
+type ChildWorkerSupervisorOptions<Message, Response> = {
+  label: string;
+  registry: HostProcessRegistry;
+  onMessage: (message: Message) => Promise<Response>;
+  parseMessage: (frame: Buffer) => Message;
+  encodeResponse: (response: Response) => Buffer;
+  isReady: (message: Message) => boolean;
+  isTerminal: (message: Message) => boolean;
+  startupTimeoutMs?: number;
+  onSpawn?: (identity: ProcessIdentity) => void;
+  onDiagnostic?: (message: string) => void;
+};
+
+type ChildWorkerStartOptions = {
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+};
+
+/** Shared supervision, framing, diagnostics, and process-group shutdown for host workers. */
+export class ChildWorkerSupervisor<Message, Response> {
+  private child: ChildProcessWithoutNullStreams | null = null;
+  private identity: ProcessIdentity | null = null;
+  private readonly decoder = new NdjsonFrameDecoder();
+  private diagnostic = Buffer.alloc(0);
+  private terminalMessage = false;
+  private stopping: WorkerOutcome | null = null;
+  private processing = Promise.resolve();
+  private readyResolve: (() => void) | undefined;
+  private readyReject: ((error: Error) => void) | undefined;
+  private exitResolve: ((result: SupervisedWorkerResult) => void) | undefined;
+  private readonly readyPromise = new Promise<void>((resolve, reject) => {
+    this.readyResolve = resolve;
+    this.readyReject = reject;
+  });
+  private readonly exitPromise = new Promise<SupervisedWorkerResult>((resolve) => {
+    this.exitResolve = resolve;
+  });
+
+  constructor(private readonly options: ChildWorkerSupervisorOptions<Message, Response>) {}
+
+  async start(options: ChildWorkerStartOptions): Promise<void> {
+    if (this.child !== null) throw new Error(`${this.options.label} already started`);
+    const child = spawn(process.execPath, options.args, {
+      cwd: options.cwd,
+      env: options.env,
+      detached: process.platform !== "win32",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    this.child = child;
+    if (child.pid === undefined) throw new Error(`${this.options.label} did not receive a PID`);
+    this.identity = this.options.registry.register(child.pid);
+    this.options.onSpawn?.(this.identity);
+    child.stdout.on("data", (chunk: Buffer) => this.onStdout(chunk));
+    child.stderr.on("data", (chunk: Buffer) => this.onStderr(chunk));
+    child.on("error", (error) => this.readyReject?.(error));
+    child.on("exit", (code, signal) => this.onExit(code, signal));
+
+    const timeout = setTimeout(() => {
+      this.readyReject?.(new Error(`${this.options.label} startup timed out`));
+      void this.stop("timedOut");
+    }, this.options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS);
+    timeout.unref?.();
+    try {
+      await this.readyPromise;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async wait(): Promise<SupervisedWorkerResult> {
+    return await this.exitPromise;
+  }
+
+  async stop(outcome: WorkerOutcome = "cancelled"): Promise<void> {
+    if (this.child === null) {
+      this.exitResolve?.({ outcome, exitCode: null, signal: null });
+      return;
+    }
+    if (this.child.exitCode !== null || this.child.signalCode !== null) return;
+    this.stopping = outcome;
+    signalProcess(this.child.pid, "SIGTERM");
+    const exited = await Promise.race([
+      this.exitPromise.then(() => true),
+      new Promise<false>((resolve) => {
+        const timer = setTimeout(() => resolve(false), DEFAULT_KILL_GRACE_MS);
+        timer.unref?.();
+      }),
+    ]);
+    if (!exited) signalProcess(this.child.pid, "SIGKILL");
+  }
+
+  private onStdout(chunk: Buffer): void {
+    let frames: Buffer[];
+    try {
+      frames = this.decoder.push(chunk);
+    } catch (error) {
+      this.appendDiagnostic(errorMessage(error));
+      void this.stop("crashed");
+      return;
+    }
+    for (const frame of frames) {
+      this.processing = this.processing
+        .then(async () => {
+          const message = this.options.parseMessage(frame);
+          if (this.options.isTerminal(message)) this.terminalMessage = true;
+          const response = await this.options.onMessage(message);
+          if (this.child?.stdin.destroyed !== false) return;
+          if (!this.child.stdin.write(this.options.encodeResponse(response))) {
+            await once(this.child.stdin, "drain");
+          }
+          if (this.options.isReady(message)) this.readyResolve?.();
+        })
+        .catch((error: unknown) => {
+          this.appendDiagnostic(errorMessage(error));
+          void this.stop("crashed");
+        });
+    }
+  }
+
+  private onStderr(chunk: Buffer): void {
+    this.options.onDiagnostic?.(chunk.toString("utf8").trimEnd());
+    if (this.diagnostic.byteLength >= MAX_DIAGNOSTIC_BYTES) return;
+    this.diagnostic = Buffer.concat([
+      this.diagnostic,
+      chunk.subarray(0, MAX_DIAGNOSTIC_BYTES - this.diagnostic.byteLength),
+    ]);
+  }
+
+  private appendDiagnostic(message: string): void {
+    this.onStderr(Buffer.from(`${message}\n`, "utf8"));
+  }
+
+  private onExit(code: number | null, signal: NodeJS.Signals | null): void {
+    if (this.identity !== null) this.options.registry.unregister(this.identity.pid);
+    const outcome =
+      this.stopping ?? (code === 0 && this.terminalMessage ? "exited" : ("crashed" as const));
+    const diagnostic = this.diagnostic.toString("utf8").trim();
+    const result: SupervisedWorkerResult = {
+      outcome,
+      exitCode: code,
+      signal,
+      ...(diagnostic.length === 0 ? {} : { diagnostic }),
+    };
+    if (outcome !== "exited") {
+      this.readyReject?.(
+        new Error(diagnostic || `${this.options.label} exited with code ${String(code)}`),
+      );
+    }
+    this.exitResolve?.(result);
+  }
+}
+
+function signalProcess(pid: number | undefined, signal: NodeJS.Signals): void {
+  if (pid === undefined) return;
+  try {
+    process.kill(process.platform === "win32" ? pid : -pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+      // The process has already exited.
+    }
+  }
+}