@osolmaz/pi-workflows 0.11.2 → 0.12.1

package/src/extension/session-events.ts

@@ -9,7 +9,7 @@ export type PublicAssistantMessageEvent =
   | { type: "toolcall_start"; contentIndex: number; partial: unknown }
   | { type: "toolcall_delta"; contentIndex: number; delta: string; partial: unknown }
   | { type: "toolcall_end"; contentIndex: number; toolCall: unknown; partial: unknown }
-  | { type: "done"; reason: "stop" | "length" | "toolUse"; message: unknown }
+  | { type: "done"; reason: "stop" | "length" | "toolUse" | "deferred"; message: unknown }
   | { type: "error"; reason: "aborted" | "error"; error: unknown };
 
 export type TurnStartEventLike = { turnIndex: number };
@@ -44,7 +44,7 @@ export type NormalizedAssistantEvent =
   | { type: "toolcall_start"; contentIndex: number }
   | { type: "toolcall_delta"; contentIndex: number; delta: string }
   | { type: "toolcall_end"; contentIndex: number; toolCall: unknown }
-  | { type: "done"; reason: "stop" | "length" | "toolUse" }
+  | { type: "done"; reason: "stop" | "length" | "toolUse" | "deferred" }
   | { type: "error"; reason: "aborted" | "error" };
 
 /** Remove cumulative snapshots while preserving every semantic stream event. */

package/src/extension/step-message.ts

@@ -12,6 +12,7 @@ export type WorkflowAgentStepMessageDetails = {
   kind: PromptDeliveryKind;
   contract: AgentStepContract;
   presentation?: AgentStepPresentation;
+  turnIntentId?: string;
 };
 
 type WorkflowAgentStepMessage = {

package/src/extension/widget.ts

@@ -162,9 +162,11 @@ function progressLines(
       : progressTracksFromRecords(updateHistory, now).map((track) => track.estimate);
   const projected = mergeProgressEstimates(latestProgressEstimates(state, now), measured ?? []);
   const estimates = mergeProgressEstimates(projected, monitorEstimates(state) ?? []);
-  const lines = prioritizeProgressEstimates(estimates).map((estimate) =>
-    formatProgressLine(estimate, now),
-  );
+  const lines = prioritizeWidgetProgress(prioritizeProgressEstimates(estimates)).map((estimate) => {
+    const indentation =
+      estimate.key.startsWith("agents/") && estimate.key.split("/").length > 2 ? "  " : "";
+    return `${indentation}${formatProgressLine(estimate, now)}`;
+  });
   const schedule = (state.updates ?? []).find(
     (record) => record.type === "monitor.schedule" && record.key === "next-check",
   );
@@ -180,6 +182,24 @@ function progressLines(
   return lines;
 }
 
+function prioritizeWidgetProgress(estimates: ProgressEstimate[]): ProgressEstimate[] {
+  const weight = (estimate: ProgressEstimate) => {
+    if (!estimate.key.startsWith("agents/")) return 0;
+    const child = estimate.key.split("/").length > 2;
+    if (!child) return -4;
+    if (estimate.data.status === "failed" || estimate.data.status === "blocked") return -3;
+    if (
+      estimate.data.status === "running" ||
+      estimate.data.status === "pending" ||
+      estimate.data.status === "waiting"
+    ) {
+      return -2;
+    }
+    return 2;
+  };
+  return [...estimates].sort((left, right) => weight(left) - weight(right));
+}
+
 function monitorEstimates(state: WorkflowRunState): ProgressEstimate[] | undefined {
   const output = state.outputs.estimate;
   if (output === null || typeof output !== "object" || Array.isArray(output)) return undefined;
@@ -309,8 +329,7 @@ function nodeRuntimeSegments(
             })
           : undefined;
       const requestAudience =
-        (request?.schema === "pi-workflows.human-decision-request.v1" ||
-          request?.schema === "pi-workflows.human-decision-request.v2") &&
+        request?.schema === "pi-workflows.human-decision-request.v1" &&
         typeof request.audience === "string"
           ? request.audience
           : human.audience;

package/src/herdr/setup.ts

@@ -115,20 +115,20 @@ function preflightPackage(packageRoot: string): PluginPackage {
   try {
     root = fs.realpathSync(requestedRoot);
   } catch (error) {
-    throw new Error(`Pi Workflows package root is missing: ${requestedRoot}`, { cause: error });
+    throw new Error(`pi-workflows package root is missing: ${requestedRoot}`, { cause: error });
   }
   if (!fs.statSync(root).isDirectory()) {
-    throw new Error(`Pi Workflows package root is not a directory: ${requestedRoot}`);
+    throw new Error(`pi-workflows package root is not a directory: ${requestedRoot}`);
   }
   const packagePath = checkedRegularFile(root, "package.json");
   const manifestPath = checkedRegularFile(root, MANIFEST_NAME);
   const packageJson = parseJsonObject(fs.readFileSync(packagePath, "utf8"), "package.json");
   if (packageJson["name"] !== PACKAGE_NAME) {
-    throw new Error(`Unexpected Pi Workflows package name in ${packagePath}.`);
+    throw new Error(`Unexpected pi-workflows package name in ${packagePath}.`);
   }
   const packageVersion = packageJson["version"];
   if (typeof packageVersion !== "string" || packageVersion.length === 0) {
-    throw new Error(`Pi Workflows package version is missing in ${packagePath}.`);
+    throw new Error(`pi-workflows package version is missing in ${packagePath}.`);
   }
 
   const manifest = fs.readFileSync(manifestPath, "utf8");

package/src/render/graph-render.ts

@@ -313,8 +313,7 @@ function renderCellText(
       ? (state.finalOutput as { schema?: unknown }).schema
       : undefined;
   const waitingRequest =
-    waitingSchema === "pi-workflows.human-decision-request.v1" ||
-    waitingSchema === "pi-workflows.human-decision-request.v2"
+    waitingSchema === "pi-workflows.human-decision-request.v1"
       ? (state.finalOutput as {
           audience?: unknown;
           presentationDigest?: unknown;

package/src/viewer/render.ts

@@ -147,13 +147,13 @@ function nodeStatusLine(bundle: LoadedRunBundle, nodeId: string, width: number,
     suffix = ansi.yellow(
       human === undefined
         ? " waiting"
-        : ` waiting for human · ${sanitizeText(requestAudience ?? "operator")}${request?.schema === "pi-workflows.human-decision-request.v2" ? ` · ${sanitizeText(request.presentation.summary)}` : ""} · ${Object.values(
+        : ` waiting for human · ${sanitizeText(requestAudience ?? "operator")}${request === null ? "" : ` · ${sanitizeText(request.presentation.summary)}`} · ${Object.values(
             human.choices,
           )
             .map((choice) => sanitizeText(choice.label))
             .join(
               " / ",
-            )}${request?.schema === "pi-workflows.human-decision-request.v2" ? ` · ${request.presentationDigest.slice(7, 19)}` : ""}`,
+            )}${request === null ? "" : ` · ${request.presentationDigest.slice(7, 19)}`}`,
     );
   } else if (result) {
     glyph = result.outcome === "ok" ? ansi.green("✓") : ansi.red("✗");
@@ -210,8 +210,7 @@ function inspectorLines(step: WorkflowStepRecord, width: number): string[] {
 function humanDecisionRequest(value: unknown): HumanDecisionRequest | null {
   if (value === null || typeof value !== "object") return null;
   const schema = (value as { schema?: unknown }).schema;
-  return schema === "pi-workflows.human-decision-request.v1" ||
-    schema === "pi-workflows.human-decision-request.v2"
+  return schema === "pi-workflows.human-decision-request.v1"
     ? (value as HumanDecisionRequest)
     : null;
 }
@@ -271,12 +270,14 @@ export function renderRunDetailLines(
     lines.push("");
     lines.push(ansi.bold("progress"));
     for (const track of progress) {
-      lines.push(fitWidth(formatProgressLine(track.estimate, now), size.width));
+      const depth = track.key.startsWith("agents/") ? track.key.split("/").length - 2 : 0;
+      const indentation = "  ".repeat(Math.max(0, depth));
+      lines.push(fitWidth(`${indentation}${formatProgressLine(track.estimate, now)}`, size.width));
       const latest = track.samples.at(-1);
       lines.push(
         fitWidth(
           ansi.dim(
-            `  ${track.estimate.sampleCount} samples · ${track.estimate.confidence ?? "no"} confidence · updated ${latest?.at ?? "unknown"}`,
+            `${indentation}  ${track.estimate.sampleCount} samples · ${track.estimate.confidence ?? "no"} confidence · updated ${latest?.at ?? "unknown"}`,
           ),
           size.width,
         ),

package/src/workflows/catalog.ts

@@ -1,5 +1,5 @@
 import { isWorkflowDefinition } from "./definition.js";
-import { WorkflowSourceChangedError } from "./errors.js";
+import { BuiltinWorkflowRevisionChangedError } from "./errors.js";
 import type { WorkflowDefinition, WorkflowSource } from "./types.js";
 
 const BUILTIN_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
@@ -102,7 +102,12 @@ export class BuiltinWorkflowCatalog {
       throw new Error(`Unknown built-in workflow: ${source.id}`);
     }
     if (entry.revision !== source.revision) {
-      throw new WorkflowSourceChangedError(runId);
+      throw new BuiltinWorkflowRevisionChangedError({
+        runId,
+        workflowId: entry.id,
+        previousRevision: source.revision,
+        currentRevision: entry.revision,
+      });
     }
     return entry.definition;
   }

package/src/workflows/command-batch.ts

@@ -0,0 +1,254 @@
+import path from "node:path";
+import { CancelledError, TimeoutError, errorMessage, isAbortLikeError } from "./errors.js";
+import { runShellAction, shellOutputTruncation, shellResultFromError } from "./shell.js";
+import type { MaybePromise, ShellActionResult } from "./types.js";
+
+export const COMMAND_BATCH_RESULT_SCHEMA = "pi-workflows.command-batch-result.v1";
+export const MAX_COMMAND_BATCH_ITEMS = 64;
+export const MAX_COMMAND_BATCH_CONCURRENCY = 8;
+export const MAX_COMMAND_BATCH_TIMEOUT_MS = 60 * 60_000;
+export const MAX_COMMAND_BATCH_OUTPUT_CHARS = 1_000_000;
+
+const MAX_ERROR_CHARS = 2_000;
+const ITEM_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+
+export type CommandBatchItem = {
+  id: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  timeoutMs: number;
+  maxOutputChars: number;
+};
+
+export type CommandBatchRequest = {
+  items: CommandBatchItem[];
+  maxConcurrency: number;
+};
+
+export type CommandBatchItemOutcome = "succeeded" | "failed" | "timedOut" | "cancelled";
+
+export type CommandBatchItemResult = ShellActionResult & {
+  id: string;
+  outcome: CommandBatchItemOutcome;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+  error?: string;
+};
+
+export type CommandBatchResult = {
+  schema: typeof COMMAND_BATCH_RESULT_SCHEMA;
+  items: CommandBatchItemResult[];
+  completed: number;
+  total: number;
+};
+
+export type RunCommandBatchOptions = {
+  signal?: AbortSignal;
+  onItemSettled?: (
+    result: CommandBatchItemResult,
+    completed: number,
+    total: number,
+  ) => MaybePromise<void>;
+};
+
+export function validateCommandBatchRequest(value: unknown): CommandBatchRequest {
+  const request = requireRecord(value, "command batch request");
+  for (const key of Object.keys(request)) {
+    if (key !== "items" && key !== "maxConcurrency") {
+      throw new Error(`command batch request.${key} is not supported`);
+    }
+  }
+  if (!Array.isArray(request.items)) {
+    throw new Error("command batch items must be an array");
+  }
+  if (request.items.length > MAX_COMMAND_BATCH_ITEMS) {
+    throw new Error(`command batch items must contain at most ${MAX_COMMAND_BATCH_ITEMS} entries`);
+  }
+  const ids = new Set<string>();
+  const items = request.items.map((item, index) => {
+    const normalized = validateItem(item, index);
+    if (ids.has(normalized.id)) {
+      throw new Error(`command batch item id is duplicated: ${normalized.id}`);
+    }
+    ids.add(normalized.id);
+    return normalized;
+  });
+  const maxConcurrency = positiveInteger(
+    request.maxConcurrency,
+    "command batch maxConcurrency",
+    MAX_COMMAND_BATCH_CONCURRENCY,
+  );
+  return { items, maxConcurrency };
+}
+
+export async function runCommandBatch(
+  input: CommandBatchRequest,
+  options: RunCommandBatchOptions = {},
+): Promise<CommandBatchResult> {
+  const request = validateCommandBatchRequest(input);
+  const total = request.items.length;
+  if (total === 0) {
+    return { schema: COMMAND_BATCH_RESULT_SCHEMA, items: [], completed: 0, total: 0 };
+  }
+
+  const results = Array.from<CommandBatchItemResult | undefined>({ length: total });
+  const signal = options.signal;
+  let nextIndex = 0;
+  let completed = 0;
+
+  const worker = async () => {
+    while (!signal?.aborted) {
+      const index = nextIndex;
+      if (index >= total) return;
+      nextIndex += 1;
+      if (signal?.aborted) return;
+
+      const item = request.items[index];
+      if (item === undefined) return;
+      const result = await runItem(item, signal);
+      results[index] = result;
+      completed += 1;
+      try {
+        await options.onItemSettled?.(result, completed, total);
+      } catch {
+        // Completion callbacks are observational and cannot change batch execution.
+      }
+    }
+  };
+
+  const workerCount = Math.min(request.maxConcurrency, total);
+  await Promise.all(Array.from({ length: workerCount }, worker));
+
+  for (let index = 0; index < total; index += 1) {
+    if (results[index] !== undefined) continue;
+    const item = request.items[index];
+    if (item !== undefined) results[index] = cancelledResult(item);
+  }
+
+  return {
+    schema: COMMAND_BATCH_RESULT_SCHEMA,
+    items: results as CommandBatchItemResult[],
+    completed,
+    total,
+  };
+}
+
+function validateItem(value: unknown, index: number): CommandBatchItem {
+  const item = requireRecord(value, `command batch items[${index}]`);
+  const allowed = new Set(["id", "command", "args", "cwd", "timeoutMs", "maxOutputChars"]);
+  for (const key of Object.keys(item)) {
+    if (!allowed.has(key)) throw new Error(`command batch items[${index}].${key} is not supported`);
+  }
+  const id = requireString(item.id, `command batch items[${index}].id`);
+  if (!ITEM_ID_PATTERN.test(id)) {
+    throw new Error(`command batch items[${index}].id is invalid`);
+  }
+  const command = requireString(item.command, `command batch items[${index}].command`);
+  if (!Array.isArray(item.args) || item.args.some((arg) => typeof arg !== "string")) {
+    throw new Error(`command batch items[${index}].args must be an array of strings`);
+  }
+  const cwd = requireString(item.cwd, `command batch items[${index}].cwd`);
+  if (!path.isAbsolute(cwd)) {
+    throw new Error(`command batch items[${index}].cwd must be absolute`);
+  }
+  const timeoutMs = positiveInteger(
+    item.timeoutMs,
+    `command batch items[${index}].timeoutMs`,
+    MAX_COMMAND_BATCH_TIMEOUT_MS,
+  );
+  const maxOutputChars = positiveInteger(
+    item.maxOutputChars,
+    `command batch items[${index}].maxOutputChars`,
+    MAX_COMMAND_BATCH_OUTPUT_CHARS,
+  );
+  return { id, command, args: [...item.args] as string[], cwd, timeoutMs, maxOutputChars };
+}
+
+async function runItem(
+  item: CommandBatchItem,
+  signal?: AbortSignal,
+): Promise<CommandBatchItemResult> {
+  try {
+    const result = await runShellAction(
+      {
+        command: item.command,
+        args: item.args,
+        cwd: item.cwd,
+        timeoutMs: item.timeoutMs,
+        maxOutputChars: item.maxOutputChars,
+      },
+      signal,
+    );
+    return itemResult(item.id, "succeeded", result);
+  } catch (error) {
+    const result = shellResultFromError(error) ?? emptyShellResult(item);
+    const outcome =
+      error instanceof TimeoutError
+        ? "timedOut"
+        : error instanceof CancelledError || isAbortLikeError(error)
+          ? "cancelled"
+          : "failed";
+    return itemResult(item.id, outcome, result, boundedError(error));
+  }
+}
+
+function itemResult(
+  id: string,
+  outcome: CommandBatchItemOutcome,
+  result: ShellActionResult,
+  error?: string,
+): CommandBatchItemResult {
+  const truncation = shellOutputTruncation(result);
+  return {
+    id,
+    outcome,
+    ...result,
+    stdoutTruncated: truncation.stdout,
+    stderrTruncated: truncation.stderr,
+    ...(error !== undefined ? { error } : {}),
+  };
+}
+
+function cancelledResult(item: CommandBatchItem): CommandBatchItemResult {
+  return itemResult(item.id, "cancelled", emptyShellResult(item), "Command was not started");
+}
+
+function emptyShellResult(item: CommandBatchItem): ShellActionResult {
+  return {
+    command: item.command,
+    args: [...item.args],
+    cwd: item.cwd,
+    stdout: "",
+    stderr: "",
+    exitCode: null,
+    signal: null,
+    durationMs: 0,
+  };
+}
+
+function boundedError(error: unknown): string {
+  const message = errorMessage(error);
+  return message.length <= MAX_ERROR_CHARS ? message : `${message.slice(0, MAX_ERROR_CHARS)}…`;
+}
+
+function positiveInteger(value: unknown, label: string, maximum: number): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 1 || (value as number) > maximum) {
+    throw new Error(`${label} must be an integer from 1 through ${maximum}`);
+  }
+  return value as number;
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireString(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value;
+}

package/src/workflows/composition.ts

@@ -480,6 +480,7 @@ function wrapNode(
     case "checkpoint": {
       const human = node.humanDecision;
       const audience = human?.audience;
+      const onTimeout = human?.onTimeout;
       return {
         ...common,
         nodeType: "checkpoint",
@@ -496,6 +497,14 @@ function wrapNode(
                     : audience!,
                 choices: human.choices,
                 request: (context: WorkflowNodeContext) => human.request(project(context)),
+                ...(onTimeout !== undefined
+                  ? {
+                      onTimeout:
+                        typeof onTimeout === "function"
+                          ? (context: WorkflowNodeContext) => onTimeout(project(context))
+                          : onTimeout,
+                    }
+                  : {}),
               },
             }
           : {}),