pi-workflow-engine 0.3.0 → 0.4.0

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

@@ -0,0 +1,152 @@
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import type { PerfSink } from "./perf.ts";
+
+export interface AllowedDiffCommand {
+  readonly file: "git" | "gh";
+  readonly args: readonly string[];
+}
+
+export interface DiffCaptureResult {
+  readonly ok: boolean;
+  readonly stdout: string;
+  readonly durationMs: number;
+  readonly bytes: number;
+  readonly error?: string;
+}
+
+export interface DiffCaptureOptions {
+  readonly cwd: string;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+  readonly maxBufferBytes: number;
+  readonly perf?: PerfSink;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly killGraceMs?: number;
+}
+
+const SAFE_REF_OR_PATH = /^[A-Za-z0-9_./:@~+=,\-]+$/;
+const SAFE_GH_FLAG = /^--[A-Za-z0-9-]+(=[A-Za-z0-9_./:@~+=,\-]+)?$/;
+const SAFE_GIT_DIFF_FLAGS = new Set(["--cached", "--staged", "--no-color", "--color=never", "--no-ext-diff"]);
+
+export function parseAllowedDiffCommand(command: string): AllowedDiffCommand | { 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") return parseGitDiff(tokens);
+  if (tokens[0] === "gh" && tokens[1] === "pr" && tokens[2] === "diff" && /^\d+$/.test(tokens[3] ?? "")) {
+    const flags = tokens.slice(4);
+    const unsafe = flags.find((token) => !SAFE_GH_FLAG.test(token));
+    if (unsafe) return { error: `unsupported gh pr diff token: ${unsafe}` };
+    return { file: "gh", args: ["pr", "diff", tokens[3], ...flags] };
+  }
+  return { error: "diff command is not in the git/gh allowlist" };
+}
+
+function parseGitDiff(tokens: readonly string[]): AllowedDiffCommand | { error: string } {
+  const args = tokens.slice(2);
+  const safeArgs = ["diff", "--no-ext-diff"];
+  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}` };
+      if (token !== "--no-ext-diff") safeArgs.push(token);
+      continue;
+    }
+    safeArgs.push(token);
+  }
+
+  return { file: "git", args: safeArgs };
+}
+
+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) {
+    return { ok: false, stdout: "", durationMs: 0, bytes: 0, error: parsed.error };
+  }
+
+  const start = performance.now();
+  let stdout = "";
+  let stderr = "";
+  let bytes = 0;
+  let error: string | undefined;
+  const child = spawn(parsed.file, [...parsed.args], {
+    cwd: options.cwd,
+    env: diffCaptureEnv(options.env),
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  return await new Promise<DiffCaptureResult>((resolve) => {
+    let settled = false;
+    let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+    const killGraceMs = Math.max(1, options.killGraceMs ?? 100);
+    const finish = (ok: boolean, finishError?: string) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      const durationMs = performance.now() - start;
+      options.perf?.observe("diff.capture_ms", durationMs);
+      options.perf?.observe("diff.bytes", bytes);
+      resolve({ ok, stdout, durationMs, bytes, error: finishError });
+    };
+    const kill = (message: string) => {
+      error = error ?? message;
+      child.kill("SIGTERM");
+      forceKillTimer ??= setTimeout(() => {
+        child.kill("SIGKILL");
+        finish(false, error);
+      }, killGraceMs);
+    };
+    const onAbort = () => kill("diff capture aborted");
+    const timeout = setTimeout(() => kill(`diff capture timed out after ${options.timeoutMs}ms`), options.timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timeout);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+
+    if (options.signal?.aborted) {
+      kill("diff capture aborted");
+    } else {
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+    }
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      bytes += chunk.length;
+      if (bytes > options.maxBufferBytes) {
+        kill(`diff capture exceeded ${options.maxBufferBytes} bytes`);
+        return;
+      }
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", (spawnError) => finish(false, spawnError.message));
+    child.on("close", (code, signal) => {
+      if (error) {
+        finish(false, error);
+        return;
+      }
+      if (code === 0) {
+        finish(true);
+        return;
+      }
+      finish(false, stderr.trim() || `diff command exited with code ${code ?? `signal ${signal ?? "unknown"}`}`);
+    });
+  });
+}
+
+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

@@ -0,0 +1,114 @@
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { WorkflowMeta, WorkflowModule } from "./types.ts";
+import type { PerfSink } from "./perf.ts";
+import { BUILTIN_WORKFLOW_FILES, BUILTIN_WORKFLOWS } from "./workflows.ts";
+
+type WorkflowModuleCandidate = {
+  meta?: { name?: unknown; description?: unknown; phases?: unknown };
+  default?: unknown;
+};
+
+export interface DiscoverWorkflowsOptions {
+  readonly refresh?: boolean;
+  readonly perf?: PerfSink;
+  readonly userWorkflowDir?: string;
+}
+
+const discoveryCache = new Map<string, Map<string, WorkflowModule>>();
+
+function parseWorkflowModule(value: unknown): { module: WorkflowModule } | { reason: string } {
+  if (!value || typeof value !== "object") return { reason: "module export is not an object" };
+  const candidate = value as WorkflowModuleCandidate;
+  const meta = candidate.meta;
+  if (!meta || typeof meta !== "object") return { reason: "missing meta export" };
+  if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
+
+  const description = meta.description;
+  if (description !== undefined && typeof description !== "string") return { reason: "meta.description must be a string when provided" };
+
+  const phases = meta.phases;
+  if (phases !== undefined && !isWorkflowPhases(phases)) return { reason: "meta.phases must be an array of { title: string }" };
+  if (!isWorkflowRun(candidate.default)) return { reason: "default export must be a function" };
+
+  const workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
+  if (phases !== undefined) workflowMeta.phases = phases;
+  return { module: { meta: workflowMeta, default: candidate.default } };
+}
+
+function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
+  return typeof value === "function";
+}
+
+function isWorkflowPhases(value: unknown): value is Array<{ title: string }> {
+  return Array.isArray(value) && value.every((phase) => typeof phase === "object" && phase !== null && typeof (phase as { title?: unknown }).title === "string");
+}
+
+/** Best-effort dynamic load of every `*.ts` workflow in a directory. */
+async function loadDir(dir: string, excludeFiles: ReadonlySet<string> = new Set()): Promise<WorkflowModule[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const modules: WorkflowModule[] = [];
+  for (const name of entries) {
+    if (excludeFiles.has(name)) continue;
+    if (!name.endsWith(".ts") || name.startsWith("_") || name.startsWith(".")) continue;
+    try {
+      const loaded: unknown = await import(pathToFileURL(join(dir, name)).href);
+      const parsed = parseWorkflowModule(loaded);
+      if ("module" in parsed) modules.push(parsed.module);
+      else console.error(`[workflow-engine] skipped ${name}: ${parsed.reason}`);
+    } 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)}`);
+    }
+  }
+  return modules;
+}
+
+/**
+ * All available workflows by name. Static registry wins on name collisions, so the
+ * 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, WorkflowModule>> {
+  const userWorkflowDir = options.userWorkflowDir ?? join(homedir(), ".pi", "agent", "workflows");
+  const cacheKey = `${repoDir}\0${userWorkflowDir}`;
+  const cached = discoveryCache.get(cacheKey);
+  if (cached && !options.refresh) {
+    options.perf?.counter("discovery.cache_hit");
+    return new Map(cached);
+  }
+
+  const byName = await timed(options.perf, "discovery.total_ms", async () => {
+    const next = new Map<string, WorkflowModule>();
+    for (const mod of BUILTIN_WORKFLOWS) next.set(mod.meta.name, mod);
+
+    const repoWorkflowDir = join(repoDir, "workflows");
+    const [repoDynamic, userDynamic] = await Promise.all([
+      timed(options.perf, "discovery.repo_dir_ms", () => loadDir(repoWorkflowDir, BUILTIN_WORKFLOW_FILES)),
+      timed(options.perf, "discovery.user_dir_ms", () => loadDir(userWorkflowDir)),
+    ]);
+
+    for (const mod of repoDynamic) {
+      if (!next.has(mod.meta.name)) next.set(mod.meta.name, mod);
+    }
+    for (const mod of userDynamic) {
+      if (!next.has(mod.meta.name)) next.set(mod.meta.name, mod);
+    }
+    return next;
+  });
+
+  discoveryCache.set(cacheKey, byName);
+  return new Map(byName);
+}
+
+async function timed<T>(perf: PerfSink | undefined, name: string, fn: () => Promise<T>): Promise<T> {
+  return perf ? await perf.time(name, fn) : await fn();
+}

package/{src → .pi/extensions/pi-workflow-engine/src}/engine.ts

@@ -1,13 +1,15 @@
-import { cpus } from "node:os";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { parallel, pipeline, Semaphore } from "./concurrency.ts";
+import { linkAbortSignal } from "./cancellation.ts";
 import { runAgent, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
+import { createPerfRecorder, type PerfSnapshot } from "./perf.ts";
+import { defaultConcurrency, resolveWorkflowRunOptions } from "./options.ts";
 import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowRunOptions } from "./types.ts";
 import { WorkflowInspector } from "./ui/workflow-inspector.ts";
 
 /** Default global cap on concurrent agents per run. */
-const DEFAULT_CONCURRENCY = Math.min(8, Math.max(2, cpus().length));
+const DEFAULT_CONCURRENCY = defaultConcurrency();
 
 /**
  * Run a workflow module: build the per-run primitives (binding agent/parallel/pipeline
@@ -19,8 +21,9 @@ export async function runWorkflow(
   args: string,
   options: WorkflowRunOptions = {},
 ): Promise<unknown> {
+  const resolvedOptions = resolveWorkflowRunOptions(options);
   const progress = new ProgressTracker(ctx, mod.meta.name);
-  if (options.inspect && ctx.hasUI) {
+  if (resolvedOptions.inspect && ctx.hasUI) {
     void ctx.ui
       .custom<void>(
         (tui, theme, _keybindings, done) => new WorkflowInspector(() => progress.snapshot(), tui, theme, () => done(undefined)),
@@ -29,32 +32,57 @@ export async function runWorkflow(
       .catch((error: unknown) => progress.log(`inspector failed: ${error instanceof Error ? error.message : String(error)}`));
   }
 
+  const perf = resolvedOptions.perfRecorder ?? createPerfRecorder(resolvedOptions.perf);
+  const runAbortController = new AbortController();
+  const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
+  const unlinkOptionAbortSignal = linkAbortSignal(resolvedOptions.signal, runAbortController);
   const rc: RunContext = {
     cwd: ctx.cwd,
     hostModel: ctx.model,
     modelRegistry: ctx.modelRegistry,
-    semaphore: new Semaphore(DEFAULT_CONCURRENCY),
+    semaphore: new Semaphore(resolvedOptions.concurrency ?? DEFAULT_CONCURRENCY),
     progress,
-    signal: ctx.signal,
+    signal: runAbortController.signal,
+    perf,
   };
 
   const agent = ((prompt: string, opts?: AgentOptions) => runAgent(rc, prompt, opts)) as WorkflowApi["agent"];
 
   const api: WorkflowApi = {
     agent,
-    parallel,
+    parallel: (thunks) =>
+      parallel(thunks, {
+        signal: runAbortController.signal,
+        abortController: runAbortController,
+        limit: resolvedOptions.parallelSubmissionLimit ?? resolvedOptions.concurrency * 2,
+      }),
     pipeline,
     phase: (title) => progress.phase(title),
     log: (message) => progress.log(message),
     progress: (event) => progress.event(event),
     args,
     cwd: ctx.cwd,
-    signal: ctx.signal,
+    signal: runAbortController.signal,
   };
 
   try {
-    return await mod.default(api);
+    return await perf.time("workflow.total_ms", () => mod.default(api));
   } finally {
+    const snapshot = perf.snapshot();
+    if (resolvedOptions.perf) {
+      resolvedOptions.onPerfSnapshot?.(snapshot);
+      progress.log(formatPerfSummary(snapshot));
+    }
+    unlinkContextAbortSignal();
+    unlinkOptionAbortSignal();
     progress.done();
   }
 }
+
+function formatPerfSummary(snapshot: PerfSnapshot): string {
+  const parts = snapshot.aggregates
+    .filter((aggregate) => aggregate.count > 0)
+    .slice(0, 5)
+    .map((aggregate) => `${aggregate.name} ${Math.round(aggregate.total)}ms`);
+  return parts.length > 0 ? `perf: ${parts.join(", ")}` : "perf: no samples";
+}

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

@@ -0,0 +1,46 @@
+import { cpus } from "node:os";
+import type { WorkflowRunOptions } from "./types.ts";
+
+export interface ResolvedWorkflowRunOptions extends WorkflowRunOptions {
+  readonly perf: boolean;
+  readonly concurrency: number;
+  readonly parallelSubmissionLimit?: number;
+}
+
+export function defaultConcurrency(cpuCount = cpus().length): number {
+  return Math.min(8, Math.max(2, cpuCount));
+}
+
+export function resolveWorkflowRunOptions(
+  input: WorkflowRunOptions = {},
+  env: Record<string, string | undefined> = process.env,
+): ResolvedWorkflowRunOptions {
+  const concurrency = clampInteger(input.concurrency ?? parseInteger(env.PI_WORKFLOW_CONCURRENCY), 1, 64, defaultConcurrency());
+  const parallelSubmissionLimit = optionalClampedInteger(
+    input.parallelSubmissionLimit ?? parseInteger(env.PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT),
+    1,
+    10_000,
+  );
+  return {
+    ...input,
+    perf: input.perf ?? env.PI_WORKFLOW_PERF === "1",
+    concurrency,
+    parallelSubmissionLimit,
+  };
+}
+
+function optionalClampedInteger(value: number | undefined, min: number, max: number): number | undefined {
+  if (value === undefined) return undefined;
+  return clampInteger(value, min, max, value);
+}
+
+function clampInteger(value: number | undefined, min: number, max: number, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+
+function parseInteger(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === "") return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : undefined;
+}

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

@@ -0,0 +1,139 @@
+import { performance } from "node:perf_hooks";
+
+export type PerfTags = Record<string, string | number>;
+
+export interface PerfSample {
+  readonly name: string;
+  readonly durationMs?: number;
+  readonly value?: number;
+  readonly tags?: PerfTags;
+}
+
+export interface PerfAggregate {
+  readonly name: string;
+  readonly count: number;
+  readonly total: number;
+  readonly min: number;
+  readonly max: number;
+  readonly mean: number;
+  readonly p50: number;
+  readonly p95: number;
+}
+
+export interface PerfSnapshot {
+  readonly enabled: boolean;
+  readonly startedAt: number;
+  readonly samples: readonly PerfSample[];
+  readonly aggregates: readonly PerfAggregate[];
+}
+
+export interface PerfSink {
+  time<T>(name: string, fn: () => Promise<T>, tags?: PerfTags): Promise<T>;
+  timeSync<T>(name: string, fn: () => T, tags?: PerfTags): T;
+  observe(name: string, value: number, tags?: PerfTags): void;
+  counter(name: string, delta?: number, tags?: PerfTags): void;
+  snapshot(): PerfSnapshot;
+}
+
+export class PerfRecorder implements PerfSink {
+  private readonly samples: PerfSample[] = [];
+
+  constructor(private readonly startedAt = Date.now()) {}
+
+  async time<T>(name: string, fn: () => Promise<T>, tags?: PerfTags): Promise<T> {
+    const start = performance.now();
+    try {
+      return await fn();
+    } finally {
+      this.observeDuration(name, performance.now() - start, tags);
+    }
+  }
+
+  timeSync<T>(name: string, fn: () => T, tags?: PerfTags): T {
+    const start = performance.now();
+    try {
+      return fn();
+    } finally {
+      this.observeDuration(name, performance.now() - start, tags);
+    }
+  }
+
+  observe(name: string, value: number, tags?: PerfTags): void {
+    if (!Number.isFinite(value)) return;
+    this.samples.push({ name, value, tags });
+  }
+
+  counter(name: string, delta = 1, tags?: PerfTags): void {
+    this.observe(name, delta, tags);
+  }
+
+  snapshot(): PerfSnapshot {
+    return {
+      enabled: true,
+      startedAt: this.startedAt,
+      samples: this.samples.map((sample) => ({ ...sample, tags: sample.tags ? { ...sample.tags } : undefined })),
+      aggregates: aggregateSamples(this.samples),
+    };
+  }
+
+  private observeDuration(name: string, durationMs: number, tags?: PerfTags): void {
+    if (!Number.isFinite(durationMs)) return;
+    this.samples.push({ name, durationMs, tags });
+  }
+}
+
+export class NoopPerfRecorder implements PerfSink {
+  constructor(private readonly startedAt = Date.now()) {}
+
+  async time<T>(_name: string, fn: () => Promise<T>, _tags?: PerfTags): Promise<T> {
+    return await fn();
+  }
+
+  timeSync<T>(_name: string, fn: () => T, _tags?: PerfTags): T {
+    return fn();
+  }
+
+  observe(_name: string, _value: number, _tags?: PerfTags): void {}
+
+  counter(_name: string, _delta?: number, _tags?: PerfTags): void {}
+
+  snapshot(): PerfSnapshot {
+    return { enabled: false, startedAt: this.startedAt, samples: [], aggregates: [] };
+  }
+}
+
+export function createPerfRecorder(enabled: boolean, startedAt?: number): PerfSink {
+  return enabled ? new PerfRecorder(startedAt) : new NoopPerfRecorder(startedAt);
+}
+
+function aggregateSamples(samples: readonly PerfSample[]): PerfAggregate[] {
+  const byName = new Map<string, number[]>();
+  for (const sample of samples) {
+    const value = sample.durationMs ?? sample.value;
+    if (value === undefined || !Number.isFinite(value)) continue;
+    const values = byName.get(sample.name) ?? [];
+    values.push(value);
+    byName.set(sample.name, values);
+  }
+
+  return [...byName.entries()].map(([name, rawValues]) => {
+    const values = [...rawValues].sort((a, b) => a - b);
+    const total = values.reduce((sum, value) => sum + value, 0);
+    return {
+      name,
+      count: values.length,
+      total,
+      min: values[0] ?? 0,
+      max: values[values.length - 1] ?? 0,
+      mean: values.length === 0 ? 0 : total / values.length,
+      p50: percentile(values, 0.5),
+      p95: percentile(values, 0.95),
+    };
+  });
+}
+
+function percentile(sortedValues: readonly number[], p: number): number {
+  if (sortedValues.length === 0) return 0;
+  const index = Math.min(sortedValues.length - 1, Math.max(0, Math.ceil(sortedValues.length * p) - 1));
+  return sortedValues[index] ?? 0;
+}