pi-workflow-engine 0.10.2 → 0.11.0

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

@@ -2,10 +2,12 @@ import { readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
-import type { WorkflowModule } from "./types.ts";
+import type { LoadedWorkflow, WorkflowSourceIdentity } from "./types.ts";
 import type { PerfSink } from "./perf.ts";
-import { parseWorkflowModule } from "./workflow-module.ts";
-import { BUILTIN_WORKFLOW_FILES, BUILTIN_WORKFLOWS } from "./workflows.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";
 
 export interface DiscoverWorkflowsOptions {
   readonly refresh?: boolean;
@@ -13,10 +15,14 @@ export interface DiscoverWorkflowsOptions {
   readonly userWorkflowDir?: string;
 }
 
-const discoveryCache = new Map<string, Map<string, WorkflowModule>>();
-
+const discoveryCache = new Map<string, Map<string, LoadedWorkflow>>();
 /** Best-effort dynamic load of every `*.ts` workflow in a directory. */
-async function loadDir(dir: string, excludeFiles: ReadonlySet<string> = new Set()): Promise<WorkflowModule[]> {
+async function loadDir(
+  dir: string,
+  sourceIdentity: (path: string) => WorkflowSourceIdentity,
+  excludeFiles: ReadonlySet<string> = new Set(),
+  provenanceRoot?: string,
+): Promise<LoadedWorkflow[]> {
   let entries: string[];
   try {
     entries = await readdir(dir);
@@ -24,14 +30,18 @@ async function loadDir(dir: string, excludeFiles: ReadonlySet<string> = new Set(
     return [];
   }
 
-  const modules: WorkflowModule[] = [];
+  const before = provenanceRoot ? await captureDiscoveryFingerprint(provenanceRoot) : undefined;
+  const modules: Array<{ readonly path: string; readonly module: Parameters<typeof loadWorkflow>[0] }> = [];
   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 path = join(dir, name);
+      const importUrl = pathToFileURL(path);
+      if (before?.kind === "verified") importUrl.searchParams.set("workflowSource", before.fingerprint);
+      const loaded: unknown = await import(importUrl.href);
       const parsed = parseWorkflowModule(loaded);
-      if ("module" in parsed) modules.push(parsed.module);
+      if ("module" in parsed) modules.push({ path, module: 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.
@@ -39,14 +49,23 @@ async function loadDir(dir: string, excludeFiles: ReadonlySet<string> = new Set(
       console.error(`[workflow-engine] skipped ${name}: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  return modules;
+  return modules.map(({ path, module }) => loadWorkflow(module, sourceIdentity(path)));
+}
+
+async function captureDiscoveryFingerprint(root: string) {
+  return await captureTreeFingerprint({
+    root,
+    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
+    maxBytes: 32 << 20,
+    maxFiles: 4096,
+  });
 }
 
 /**
  * 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>> {
+export async function discoverWorkflows(repoDir: string, options: DiscoverWorkflowsOptions = {}): Promise<Map<string, LoadedWorkflow>> {
   const userWorkflowDir = options.userWorkflowDir ?? join(homedir(), ".pi", "agent", "workflows");
   const cacheKey = `${repoDir}\0${userWorkflowDir}`;
   const cached = discoveryCache.get(cacheKey);
@@ -56,13 +75,43 @@ export async function discoverWorkflows(repoDir: string, options: DiscoverWorkfl
   }
 
   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 next = new Map<string, LoadedWorkflow>();
+    const builtinSource = await captureDiscoveryFingerprint(BUILTIN_SOURCE_ROOT);
+    for (const definition of BUILTIN_WORKFLOW_DEFINITIONS) {
+      const source: WorkflowSourceIdentity =
+        builtinSource.kind === "verified"
+          ? {
+              kind: "file",
+              path: definition.path,
+              root: definition.root,
+              fingerprint: builtinSource.fingerprint,
+            }
+          : {
+              kind: "unverifiable",
+              reason: `built-in workflow source capture failed: ${builtinSource.reason}`,
+            };
+      next.set(definition.module.meta.name, loadWorkflow(definition.module, source));
+    }
 
     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)),
+      timed(options.perf, "discovery.repo_dir_ms", () =>
+        loadDir(
+          repoWorkflowDir,
+          () => ({
+            kind: "unverifiable",
+            reason: "dynamic workflow module graphs are not loaded from an immutable source snapshot",
+          }),
+          BUILTIN_WORKFLOW_FILES,
+          repoDir,
+        ),
+      ),
+      timed(options.perf, "discovery.user_dir_ms", () =>
+        loadDir(userWorkflowDir, () => ({
+          kind: "unverifiable",
+          reason: "dynamic user workflow dependencies do not have a declared trusted source root",
+        })),
+      ),
     ]);
 
     for (const mod of repoDynamic) {

package/.pi/extensions/pi-workflow-engine/src/dynamax-shortcuts.ts

@@ -1,18 +1,21 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import type { KeyId } from "@earendil-works/pi-tui";
+import { Key, type KeyId } from "@earendil-works/pi-tui";
 
 export const DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT = "ctrl+shift+m" satisfies KeyId;
+export const DEFAULT_REVIEW_RESULTS_SHORTCUT = "ctrl+shift+r" satisfies KeyId;
 
 const CONFIG_FILE_NAME = "pi-workflow-engine.json";
 
 export interface DynamaxShortcuts {
   inspector: KeyId | null;
+  results: KeyId | null;
 }
 
 interface DynamaxShortcutConfig {
   inspector?: unknown;
+  results?: unknown;
 }
 
 export function dynamaxShortcutsConfigPath(agentDir: string = getAgentDir()): string {
@@ -25,9 +28,15 @@ export function resolveDynamaxShortcuts(configPath: string = dynamaxShortcutsCon
   const config = readShortcutConfig(configPath);
   if (!config) return defaultDynamaxShortcuts();
 
-  return {
-    inspector: shortcutFromConfig(config.inspector, DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT),
+  const shortcuts = {
+    inspector: shortcutFromConfig("inspector", config.inspector, DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT, configPath),
+    results: shortcutFromConfig("results", config.results, DEFAULT_REVIEW_RESULTS_SHORTCUT, configPath),
   };
+  if (shortcuts.inspector && shortcuts.results && shortcutIdentity(shortcuts.inspector) === shortcutIdentity(shortcuts.results)) {
+    console.warn(`Duplicate pi-workflow-engine shortcut ${shortcuts.inspector} in ${configPath}; disabling the results shortcut.`);
+    return { inspector: shortcuts.inspector, results: null };
+  }
+  return shortcuts;
 }
 
 function readShortcutConfig(configPath: string): DynamaxShortcutConfig | null {
@@ -41,7 +50,7 @@ function readShortcutConfig(configPath: string): DynamaxShortcutConfig | null {
 
   const shortcuts = isRecord(parsed) ? parsed.shortcuts : undefined;
   if (shortcuts === undefined) return {};
-  if (!isRecord(shortcuts) || !hasValidShortcutValues(shortcuts)) {
+  if (!isRecord(shortcuts)) {
     warnUsingDefaults("Invalid", configPath);
     return null;
   }
@@ -49,21 +58,58 @@ function readShortcutConfig(configPath: string): DynamaxShortcutConfig | null {
   return shortcuts;
 }
 
-function hasValidShortcutValues(shortcuts: Record<string, unknown>): boolean {
-  return isValidShortcutConfigValue(shortcuts.inspector);
+function shortcutFromConfig(
+  name: keyof DynamaxShortcutConfig,
+  configured: unknown,
+  fallback: KeyId,
+  configPath: string,
+): KeyId | null {
+  if (configured === null) return null;
+  if (configured === undefined) return fallback;
+  if (typeof configured === "string") {
+    const normalized = configured.trim();
+    if (isKeyId(normalized)) return normalized;
+  }
+  console.warn(`Invalid ${name} shortcut in ${configPath}; using ${fallback}.`);
+  return fallback;
 }
 
-function isValidShortcutConfigValue(value: unknown): value is string | null | undefined {
-  return value === undefined || value === null || (typeof value === "string" && value.trim().length > 0);
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+const NAMED_BASE_KEYS = new Set<string>(Object.values(Key).flatMap((value) => (typeof value === "string" ? [String(value)] : [])));
+
+function isKeyId(value: string): value is KeyId {
+  return parseKeyId(value) !== undefined;
 }
 
-function shortcutFromConfig(configured: unknown, fallback: KeyId): KeyId | null {
-  if (configured === null) return null;
-  return typeof configured === "string" ? (configured.trim() as KeyId) : fallback;
+function parseKeyId(value: string): { readonly modifiers: readonly string[]; readonly base: string } | undefined {
+  const seen = new Set<string>();
+  let base = value;
+  while (true) {
+    const separator = base.indexOf("+");
+    if (separator < 0) break;
+    const modifier = base.slice(0, separator);
+    if (!MODIFIERS.has(modifier) || seen.has(modifier)) break;
+    seen.add(modifier);
+    base = base.slice(separator + 1);
+  }
+  return isBaseKey(base) ? { modifiers: [...seen], base } : undefined;
+}
+
+function isBaseKey(value: string): boolean {
+  return /^[a-z0-9]$/.test(value) || NAMED_BASE_KEYS.has(value);
+}
+
+function shortcutIdentity(shortcut: KeyId): string {
+  const parsed = parseKeyId(shortcut);
+  if (!parsed) return shortcut;
+  let base = parsed.base;
+  if (base === "esc") base = "escape";
+  else if (base === "return") base = "enter";
+  return `${[...parsed.modifiers].sort().join("+")}+${base}`;
 }
 
 function defaultDynamaxShortcuts(): DynamaxShortcuts {
-  return { inspector: DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT };
+  return { inspector: DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT, results: DEFAULT_REVIEW_RESULTS_SHORTCUT };
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -71,5 +117,5 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function warnUsingDefaults(reason: "Could not read" | "Invalid", configPath: string): void {
-  console.warn(`${reason} pi-workflow-engine config at ${configPath}; using default Dynamax shortcuts.`);
+  console.warn(`${reason} pi-workflow-engine config at ${configPath}; using default workflow shortcuts.`);
 }

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

@@ -23,6 +23,15 @@ export const DYNAMAX_TOKEN_PATTERN = /(^|[^A-Za-z0-9_])dynamax([^A-Za-z0-9_]|$)/
 export const DYNAMAX_STATUS_KEY = "dynamax";
 export const DYNAMAX_WIDGET_KEY = "workflow-dynamax";
 
+export const ADAPTIVE_WORKFLOW_GUIDANCE = `
+Adaptive multi-pass workflows are optional. Use a simple single-pass fan-out when it is sufficient. When the first pass may expose gaps, conflicts, weak claims, or missing evidence:
+- run the bounded first-pass agents;
+- give their surviving results to a structured gap-analysis agent so the LLM decides what needs follow-up;
+- put a hard maxItems bound on LLM-authored task arrays and defensively slice them before fan-out;
+- use ordinary TypeScript conditionals or bounded loops to launch follow-up agents only when gaps exist;
+- synthesize the first-pass and follow-up results together.
+Do not generate a second pass when the first pass is sufficient, and do not invent iteration, quorum, graph, reduction, or retry primitives for this pattern.`;
+
 export const DYNAMAX_REMINDER = `
 ## dynamax workflow opt-in
 
@@ -34,6 +43,8 @@ Inline workflow rules:
 - Set thinkingLevel explicitly on each agent() call so fan-out remains bounded.
 - Subagents receive no skills by default. Add \`skills: ["skill-name"]\` per agent only when that stage should load that skill; grant the smallest useful set.
 - Provide exactly one of workflow.name or workflow.script.
+
+${ADAPTIVE_WORKFLOW_GUIDANCE}
 `;
 
 const DYNAMAX_CONTEXT_CUSTOM_TYPE = "workflow-dynamax-reminder";
@@ -145,7 +156,7 @@ export function registerDynamax(
   });
 
   pi.on("session_shutdown", (_event, ctx) => {
-    clearDynamaxSurfaces(ctx, getDynamaxRuntime(runtimes, ctx));
+    clearDynamaxSurfaces(ctx);
   });
 
   pi.on("input", (event, ctx) => {
@@ -266,7 +277,7 @@ export function updateDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui"
   ctx.ui.setWidget(DYNAMAX_WIDGET_KEY, undefined);
   ctx.ui.setStatus(DYNAMAX_WIDGET_KEY, undefined);
   if (!isDynamaxActive(runtime.state) && !runtime.runningWorkflow) {
-    clearDynamaxSurfaces(ctx, runtime);
+    clearDynamaxSurfaces(ctx);
     return;
   }
 
@@ -274,7 +285,7 @@ export function updateDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui"
   ctx.ui.setStatus(DYNAMAX_STATUS_KEY, status);
 }
 
-export function clearDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">, runtime: DynamaxRuntime): void {
+export function clearDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">): void {
   if (!ctx.hasUI) return;
   ctx.ui.setWidget(DYNAMAX_WIDGET_KEY, undefined);
   ctx.ui.setStatus(DYNAMAX_STATUS_KEY, undefined);