pi-workflow-engine 0.11.0 → 0.13.0

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

@@ -5,6 +5,14 @@ export class WorkflowAbortError extends Error {
   }
 }
 
+/** Abort reason used when a durable run can be resumed after its host session shuts down. */
+export class WorkflowPauseError extends WorkflowAbortError {
+  constructor(message = "Workflow paused because its host session shut down") {
+    super(message);
+    this.name = "WorkflowPauseError";
+  }
+}
+
 export function abortReason(signal: AbortSignal | undefined): Error {
   const reason = signal?.reason;
   if (safeInstanceOf(reason, Error)) return reason;
@@ -29,6 +37,10 @@ export function isFatalWorkflowError(error: unknown, signal: AbortSignal | undef
   return false;
 }
 
+export function isWorkflowPauseError(error: unknown): error is WorkflowPauseError {
+  return safeInstanceOf(error, WorkflowPauseError);
+}
+
 export function linkAbortSignal(parent: AbortSignal | undefined, controller: AbortController): () => void {
   if (!parent) return () => {};
   if (parent.aborted) {
@@ -40,6 +52,32 @@ export function linkAbortSignal(parent: AbortSignal | undefined, controller: Abo
   return () => parent.removeEventListener("abort", onAbort);
 }
 
+export async function raceWithAbort<T>(operation: () => Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  throwIfAborted(signal);
+  if (!signal) return await operation();
+
+  return await new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const finish = (action: () => void) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      action();
+    };
+    const onAbort = () => finish(() => reject(abortReason(signal)));
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    void operation().then(
+      (value) => finish(() => resolve(value)),
+      (error: unknown) => finish(() => reject(error)),
+    );
+  });
+}
+
 function safeInstanceOf<T>(value: unknown, constructor: abstract new (...args: never[]) => T): value is T {
   try {
     return value instanceof constructor;

package/.pi/extensions/pi-workflow-engine/src/command-completions.ts

@@ -0,0 +1,36 @@
+import { fuzzyFilter, type AutocompleteItem } from "@earendil-works/pi-tui";
+
+interface ArgumentCompletionCandidate {
+  readonly value: string;
+  readonly description?: string;
+}
+
+interface ArgumentPrefixParts {
+  readonly completed: readonly string[];
+  readonly current: string;
+  readonly base: string;
+}
+
+/** Split a slash-command argument prefix while retaining the text Pi will replace. */
+export function splitArgumentPrefix(argumentPrefix: string): ArgumentPrefixParts {
+  const match = /(\S*)$/.exec(argumentPrefix);
+  const current = match?.[1] ?? "";
+  const base = argumentPrefix.slice(0, argumentPrefix.length - current.length);
+  const completed = base.trim().split(/\s+/).filter(Boolean);
+  return { completed, current, base };
+}
+
+/** Complete the current argument and return full replacement values, as Pi expects. */
+export function completeCurrentArgument(
+  argumentPrefix: string,
+  candidates: readonly ArgumentCompletionCandidate[],
+): AutocompleteItem[] | null {
+  const { current, base } = splitArgumentPrefix(argumentPrefix);
+  const matches = fuzzyFilter([...candidates], current, (candidate) => candidate.value)
+    .map((candidate) => ({
+      value: `${base}${candidate.value}`,
+      label: candidate.value,
+      ...(candidate.description === undefined ? {} : { description: candidate.description }),
+    }));
+  return matches.length > 0 ? matches : null;
+}

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

@@ -14,22 +14,28 @@ export class Semaphore {
   private active = 0;
   private readonly waiters: Array<() => void> = [];
 
-  constructor(private readonly max: number) {}
+  constructor(private readonly max: number) {
+    if (!Number.isInteger(max) || max < 1) throw new RangeError("Semaphore capacity must be a positive integer");
+  }
 
   async run<T>(fn: () => Promise<T>, options: { onQueueWaitMs?: (durationMs: number) => void; signal?: AbortSignal } = {}): Promise<T> {
     throwIfAborted(options.signal);
     const queuedAt = performance.now();
     if (this.active >= this.max) {
       await this.waitForSlot(options.signal);
+    } else {
+      this.active++;
     }
-    options.onQueueWaitMs?.(performance.now() - queuedAt);
-    throwIfAborted(options.signal);
-    this.active++;
     try {
+      options.onQueueWaitMs?.(performance.now() - queuedAt);
+      throwIfAborted(options.signal);
       return await fn();
     } finally {
-      this.active--;
-      this.waiters.shift()?.();
+      // Transfer ownership directly. A selected waiter owns this reservation
+      // even before its continuation runs, including if it is then cancelled.
+      const next = this.waiters.shift();
+      if (next) next();
+      else this.active--;
     }
   }
 
@@ -78,6 +84,8 @@ export interface ParallelSettledOptions {
 export interface ParallelSettledError {
   readonly name?: string;
   readonly message: string;
+  readonly code?: string;
+  readonly details?: Readonly<Record<string, string | number | boolean | null>>;
 }
 
 export type ParallelSettledResult<T> =
@@ -229,14 +237,48 @@ async function runParallel<T, Result>(
 function serializeParallelError(error: unknown): ParallelSettledError {
   const message = readStringProperty(error, "message") ?? unknownErrorMessage(error);
   const name = readStringProperty(error, "name");
-  return name && name.length > 0 ? { name, message } : { message };
+  const code = readStringProperty(error, "code");
+  const details = readSerializableDetails(error);
+  return {
+    ...(name && name.length > 0 ? { name } : {}),
+    message,
+    ...(code && code.length > 0 ? { code } : {}),
+    ...(details ? { details } : {}),
+  };
 }
 
-function readStringProperty(value: unknown, property: "message" | "name"): string | undefined {
+function readStringProperty(value: unknown, property: "message" | "name" | "code"): string | undefined {
+  const candidate = readProperty(value, property);
+  return typeof candidate === "string" ? candidate : undefined;
+}
+
+function readSerializableDetails(
+  value: unknown,
+): Readonly<Record<string, string | number | boolean | null>> | undefined {
+  const candidate = readProperty(value, "details");
+  if (typeof candidate !== "object" || candidate === null) return undefined;
+  try {
+    const details: Record<string, string | number | boolean | null> = {};
+    for (const [key, detail] of Object.entries(candidate)) {
+      if (
+        typeof detail === "string" ||
+        typeof detail === "boolean" ||
+        detail === null ||
+        (typeof detail === "number" && Number.isFinite(detail))
+      ) {
+        details[key] = detail;
+      }
+    }
+    return Object.keys(details).length > 0 ? details : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readProperty(value: unknown, property: string): unknown {
   if ((typeof value !== "object" && typeof value !== "function") || value === null) return undefined;
   try {
-    const candidate = Reflect.get(value, property);
-    return typeof candidate === "string" ? candidate : undefined;
+    return Reflect.get(value, property);
   } catch {
     return undefined;
   }
@@ -275,6 +317,21 @@ export async function pipeline<Item, A, B, C>(
   stage2: (prev: A, item: Item, index: number) => Promise<B>,
   stage3: (prev: B, item: Item, index: number) => Promise<C>,
 ): Promise<Array<C | null>>;
+export async function pipeline<Item, A, B, C, D>(
+  items: readonly Item[],
+  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+  stage2: (prev: A, item: Item, index: number) => Promise<B>,
+  stage3: (prev: B, item: Item, index: number) => Promise<C>,
+  stage4: (prev: C, item: Item, index: number) => Promise<D>,
+): Promise<Array<D | null>>;
+export async function pipeline<Item, A, B, C, D, E>(
+  items: readonly Item[],
+  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+  stage2: (prev: A, item: Item, index: number) => Promise<B>,
+  stage3: (prev: B, item: Item, index: number) => Promise<C>,
+  stage4: (prev: C, item: Item, index: number) => Promise<D>,
+  stage5: (prev: D, item: Item, index: number) => Promise<E>,
+): Promise<Array<E | null>>;
 export async function pipeline(
   items: readonly unknown[],
   ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
@@ -302,6 +359,21 @@ export function bindPipeline(options: PipelineOptions): Pipeline {
     stage2: (prev: A, item: Item, index: number) => Promise<B>,
     stage3: (prev: B, item: Item, index: number) => Promise<C>,
   ): Promise<Array<C | null>>;
+  async function boundPipeline<Item, A, B, C, D>(
+    items: readonly Item[],
+    stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+    stage2: (prev: A, item: Item, index: number) => Promise<B>,
+    stage3: (prev: B, item: Item, index: number) => Promise<C>,
+    stage4: (prev: C, item: Item, index: number) => Promise<D>,
+  ): Promise<Array<D | null>>;
+  async function boundPipeline<Item, A, B, C, D, E>(
+    items: readonly Item[],
+    stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+    stage2: (prev: A, item: Item, index: number) => Promise<B>,
+    stage3: (prev: B, item: Item, index: number) => Promise<C>,
+    stage4: (prev: C, item: Item, index: number) => Promise<D>,
+    stage5: (prev: D, item: Item, index: number) => Promise<E>,
+  ): Promise<Array<E | null>>;
   async function boundPipeline(
     items: readonly unknown[],
     ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>

package/.pi/extensions/pi-workflow-engine/src/diff-capture.ts

@@ -1,30 +1,21 @@
-import { Type, type Static } from "typebox";
-import { Value } from "typebox/value";
 import type { PerfSink } from "./perf.ts";
 import { runBoundedProcess, type BoundedProcessFailure } from "./process-runner.ts";
-
-export type GitDiffBaselineTarget =
-  | { readonly kind: "working-tree" }
-  | { readonly kind: "index" }
-  | { readonly kind: "range"; readonly ref: string };
-
-export const GitReviewDiffTargetSchema = Type.Object({
-  kind: Type.Literal("git"),
-  args: Type.Array(Type.String()),
-});
-
-export const PullRequestReviewDiffTargetSchema = Type.Object({
-  kind: Type.Literal("pull-request"),
-  number: Type.Integer({ minimum: 1 }),
-});
-
-export const ReviewDiffTargetSchema = Type.Union([GitReviewDiffTargetSchema, PullRequestReviewDiffTargetSchema]);
-
-export type GitReviewDiffTarget = Static<typeof GitReviewDiffTargetSchema>;
-export type PullRequestReviewDiffTarget = Static<typeof PullRequestReviewDiffTargetSchema>;
-
-/** Serializable semantic identity of the diff being reviewed. */
-export type ReviewDiffTarget = Static<typeof ReviewDiffTargetSchema>;
+import { parseAllowedDiffCommand, reviewDiffCommand, type ReviewDiffTarget } from "./review-diff-target.ts";
+
+export {
+  formatReviewDiffTarget,
+  GitReviewDiffTargetSchema,
+  isReviewDiffTarget,
+  parseAllowedDiffCommand,
+  PullRequestReviewDiffTargetSchema,
+  reviewDiffCommand,
+  ReviewDiffTargetSchema,
+  reviewGitDiffBaseline,
+  type GitDiffBaselineTarget,
+  type GitReviewDiffTarget,
+  type PullRequestReviewDiffTarget,
+  type ReviewDiffTarget,
+} from "./review-diff-target.ts";
 
 interface DiffCaptureResultBase {
   readonly stdout: string;
@@ -48,78 +39,6 @@ export interface DiffCaptureOptions {
   readonly killGraceMs?: number;
 }
 
-const SAFE_REF_OR_PATH = /^[A-Za-z0-9_./:@~+=,\-]+$/;
-const SAFE_GH_DIFF_FLAGS = new Set(["--color=never"]);
-const SAFE_GIT_DIFF_FLAGS = new Set(["--binary", "--cached", "--staged", "--no-color", "--color=never", "--no-ext-diff"]);
-
-export function parseAllowedDiffCommand(command: string): ReviewDiffTarget | { error: string } {
-  const tokens = command.trim().split(/\s+/).filter(Boolean);
-  if (tokens.length < 2) return { error: "empty or incomplete diff command" };
-  if (tokens[0] === "git" && tokens[1] === "diff") {
-    const parsed = parseGitDiff(tokens);
-    return "error" in parsed ? parsed : parsed.target;
-  }
-  if (tokens[0] === "gh" && tokens[1] === "pr" && tokens[2] === "diff" && /^\d+$/.test(tokens[3] ?? "")) {
-    const number = Number(tokens[3]);
-    if (!Number.isSafeInteger(number) || number <= 0) return { error: "pull-request number must be a positive safe integer" };
-    const flags = tokens.slice(4);
-    if (flags.includes("--patch")) return { error: "gh pr diff --patch is not supported because reviews require the cumulative pull-request diff" };
-    const unsupported = flags.find((token) => !SAFE_GH_DIFF_FLAGS.has(token));
-    if (unsupported) return { error: `unsupported gh pr diff option: ${unsupported}` };
-    return { kind: "pull-request", number };
-  }
-  return { error: "diff command is not in the git/gh allowlist" };
-}
-
-function parseGitDiff(
-  tokens: readonly string[],
-): { readonly target: GitReviewDiffTarget; readonly baseline: GitDiffBaselineTarget } | { readonly error: string } {
-  const args = tokens.slice(2);
-  const safeArgs = ["diff", "--no-ext-diff"];
-  const operands: string[] = [];
-  let staged = false;
-  let pathMode = false;
-
-  for (const token of args) {
-    if (!SAFE_REF_OR_PATH.test(token)) return { error: `unsupported git diff token: ${token}` };
-    if (token === "--") {
-      pathMode = true;
-      safeArgs.push(token);
-      continue;
-    }
-    if (!pathMode && token.startsWith("-")) {
-      if (!isAllowedGitDiffFlag(token)) return { error: `unsupported git diff option: ${token}` };
-      staged ||= token === "--cached" || token === "--staged";
-      if (token !== "--no-ext-diff") safeArgs.push(token);
-      continue;
-    }
-    if (!pathMode) operands.push(token);
-    safeArgs.push(token);
-  }
-
-  const baseline = classifyGitDiffBaseline(staged, operands);
-  return "error" in baseline ? baseline : { target: { kind: "git", args: safeArgs }, baseline };
-}
-
-function classifyGitDiffBaseline(staged: boolean, operands: readonly string[]): GitDiffBaselineTarget | { readonly error: string } {
-  if (operands.length > 1) {
-    return { error: "ambiguous git diff operands; use A..B or A...B for revisions, or -- before multiple paths" };
-  }
-  if (staged) return { kind: "index" };
-
-  const range = operands.find((operand) => operand.includes(".."));
-  if (range) {
-    const separator = range.includes("...") ? "..." : "..";
-    return { kind: "range", ref: range.slice(range.indexOf(separator) + separator.length) || "HEAD" };
-  }
-
-  return { kind: "working-tree" };
-}
-
-function isAllowedGitDiffFlag(token: string): boolean {
-  return SAFE_GIT_DIFF_FLAGS.has(token) || /^-U\d+$/.test(token) || /^--unified=\d+$/.test(token) || /^--inter-hunk-context=\d+$/.test(token);
-}
-
 export async function captureDiff(command: string, options: DiffCaptureOptions): Promise<DiffCaptureResult> {
   const parsed = parseAllowedDiffCommand(command);
   if ("error" in parsed) {
@@ -157,39 +76,6 @@ export async function captureDiffTarget(target: ReviewDiffTarget, options: DiffC
   return result;
 }
 
-export function reviewDiffCommand(target: ReviewDiffTarget): { readonly file: "git" | "gh"; readonly args: readonly string[] } {
-  return target.kind === "pull-request"
-    ? { file: "gh", args: ["pr", "diff", String(target.number), "--color=never"] }
-    : { file: "git", args: target.args };
-}
-
-/** Canonical display form. Never execute this string directly; use reviewDiffCommand(). */
-export function formatReviewDiffTarget(target: ReviewDiffTarget): string {
-  const command = reviewDiffCommand(target);
-  return [command.file, ...command.args].join(" ");
-}
-
-/** Derive reconstruction semantics from the canonical git command instead of persisting duplicate state. */
-export function reviewGitDiffBaseline(target: GitReviewDiffTarget): GitDiffBaselineTarget {
-  const parsed = parseGitDiff(["git", ...target.args]);
-  if ("error" in parsed) throw new Error(`Invalid persisted git review target: ${parsed.error}`);
-  return parsed.baseline;
-}
-
-/** Validate persisted targets by round-tripping through the single command allowlist parser. */
-export function isReviewDiffTarget(value: unknown): value is ReviewDiffTarget {
-  if (!Value.Check(ReviewDiffTargetSchema, value)) return false;
-  const parsed = parseAllowedDiffCommand(formatReviewDiffTarget(value));
-  return !("error" in parsed) && sameReviewDiffTarget(parsed, value);
-}
-
-function sameReviewDiffTarget(left: ReviewDiffTarget, right: ReviewDiffTarget): boolean {
-  if (left.kind !== right.kind) return false;
-  if (left.kind === "pull-request") return right.kind === "pull-request" && left.number === right.number;
-  if (right.kind !== "git" || left.args.length !== right.args.length) return false;
-  return left.args.every((arg, index) => arg === right.args[index]);
-}
-
 function diffCaptureEnv(env: NodeJS.ProcessEnv | undefined): NodeJS.ProcessEnv {
   return { ...(env ?? process.env), GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" };
 }

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

@@ -1,13 +1,14 @@
 import { readdir } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { LoadedWorkflow, WorkflowSourceIdentity } from "./types.ts";
 import type { PerfSink } from "./perf.ts";
 import { loadWorkflow, parseWorkflowModule } from "./workflow-module.ts";
 import { BUILTIN_SOURCE_ROOT, BUILTIN_WORKFLOW_DEFINITIONS, BUILTIN_WORKFLOW_FILES } from "./workflows.ts";
 import { captureTreeFingerprint } from "./tree-fingerprint.ts";
 import { FINGERPRINT_EXCLUDED_RELATIVE_PATHS } from "./resume-context.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 
 export interface DiscoverWorkflowsOptions {
   readonly refresh?: boolean;
@@ -15,6 +16,9 @@ export interface DiscoverWorkflowsOptions {
   readonly userWorkflowDir?: string;
 }
 
+const DISCOVERY_FINGERPRINT_MAX_BYTES = 32 << 20;
+const DISCOVERY_FINGERPRINT_MAX_FILES = 4096;
+
 const discoveryCache = new Map<string, Map<string, LoadedWorkflow>>();
 /** Best-effort dynamic load of every `*.ts` workflow in a directory. */
 async function loadDir(
@@ -46,7 +50,7 @@ async function loadDir(
     } catch (error) {
       // Drop-in loading depends on the runtime resolving TS + the bundled typebox.
       // Failures here are non-fatal: the static registry still works.
-      console.error(`[workflow-engine] skipped ${name}: ${error instanceof Error ? error.message : String(error)}`);
+      console.error(`[workflow-engine] skipped ${name}: ${unknownErrorMessage(error)}`);
     }
   }
   return modules.map(({ path, module }) => loadWorkflow(module, sourceIdentity(path)));
@@ -56,8 +60,8 @@ async function captureDiscoveryFingerprint(root: string) {
   return await captureTreeFingerprint({
     root,
     excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
-    maxBytes: 32 << 20,
-    maxFiles: 4096,
+    maxBytes: DISCOVERY_FINGERPRINT_MAX_BYTES,
+    maxFiles: DISCOVERY_FINGERPRINT_MAX_FILES,
   });
 }
 
@@ -66,7 +70,7 @@ async function captureDiscoveryFingerprint(root: string) {
  * bundled example is always the verified one even if a same-named file is dropped in.
  */
 export async function discoverWorkflows(repoDir: string, options: DiscoverWorkflowsOptions = {}): Promise<Map<string, LoadedWorkflow>> {
-  const userWorkflowDir = options.userWorkflowDir ?? join(homedir(), ".pi", "agent", "workflows");
+  const userWorkflowDir = options.userWorkflowDir ?? join(getAgentDir(), "workflows");
   const cacheKey = `${repoDir}\0${userWorkflowDir}`;
   const cached = discoveryCache.get(cacheKey);
   if (cached && !options.refresh) {