pi-workflow-engine 0.10.3 → 0.12.0

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

@@ -1,7 +1,17 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { KeyId } from "@earendil-works/pi-tui";
+import { CustomEditor, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { EditorComponent, KeyId } from "@earendil-works/pi-tui";
+import { completeCurrentArgument } from "./command-completions.ts";
 import { resolveDynamaxShortcuts, type DynamaxShortcuts } from "./dynamax-shortcuts.ts";
+import { sessionKey } from "./session-identity.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import {
+  decorateDynamaxEditor,
+  resolveDynamaxEffect,
+  type DynamaxAnimationScheduler,
+  type DynamaxEditorDecoration,
+  type DynamaxEffect,
+} from "./ui/dynamax-editor-decoration.ts";
 
 export interface DynamaxState {
   sticky: boolean;
@@ -15,13 +25,43 @@ export interface DynamaxRuntime {
 }
 
 export type DynamaxRuntimeStore = Map<string, DynamaxRuntime>;
+
 export interface DynamaxRegistrationOptions {
   openInspector?: (ctx: ExtensionContext) => Promise<void> | void;
+  effect?: DynamaxEffect;
+  animationScheduler?: DynamaxAnimationScheduler;
 }
 
 export const DYNAMAX_TOKEN_PATTERN = /(^|[^A-Za-z0-9_])dynamax([^A-Za-z0-9_]|$)/i;
 export const DYNAMAX_STATUS_KEY = "dynamax";
-export const DYNAMAX_WIDGET_KEY = "workflow-dynamax";
+
+type EditorFactory = NonNullable<ReturnType<ExtensionContext["ui"]["getEditorComponent"]>>;
+
+interface DynamaxEditorInstallation {
+  factory: EditorFactory;
+  previousFactory: EditorFactory | undefined;
+  decorations: Set<DynamaxEditorDecoration>;
+}
+
+function disposeDynamaxDecorations(decorations: Set<DynamaxEditorDecoration>): void {
+  for (const decoration of decorations) decoration.dispose();
+  decorations.clear();
+}
+
+const DYNAMAX_ACTION_COMPLETIONS = [
+  { value: "on", description: "Keep Dynamax enabled for this session" },
+  { value: "off", description: "Disable sticky and pending Dynamax modes" },
+  { value: "status", description: "Show the current Dynamax state" },
+] as const;
+
+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
@@ -31,9 +71,11 @@ The user has opted into dynamax multi-agent orchestration. The workflow tool is
 Inline workflow rules:
 - Use the injected Type object for schemas, for example Type.Object({ ok: Type.Boolean() }); do not import typebox.
 - Do not use import statements or dynamic import() in inline workflow scripts.
-- Set thinkingLevel explicitly on each agent() call so fan-out remains bounded.
+- Set profile to "small", "medium", or "big" on each agent() call so routing remains explicit; use model/thinkingLevel only for an intentional override.
 - 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";
@@ -46,12 +88,8 @@ export function createDynamaxRuntime(): DynamaxRuntime {
   return { state: createDynamaxState() };
 }
 
-export function dynamaxSessionKey(ctx: Pick<ExtensionContext, "sessionManager">): string {
-  return ctx.sessionManager.getSessionFile() ?? ctx.sessionManager.getSessionId();
-}
-
 export function getDynamaxRuntime(store: DynamaxRuntimeStore, ctx: Pick<ExtensionContext, "sessionManager">): DynamaxRuntime {
-  const key = dynamaxSessionKey(ctx);
+  const key = sessionKey(ctx);
   const existing = store.get(key);
   if (existing) return existing;
   const runtime = createDynamaxRuntime();
@@ -67,12 +105,8 @@ export function markDynamaxOneShot(state: DynamaxState): void {
   state.oneShotPending = true;
 }
 
-export function setDynamaxSticky(state: DynamaxState, sticky: boolean): void {
-  state.sticky = sticky;
-  if (!sticky) {
-    state.oneShotPending = false;
-    state.turnActive = false;
-  }
+export function enableDynamaxSticky(state: DynamaxState): void {
+  state.sticky = true;
 }
 
 export function clearDynamax(state: DynamaxState): void {
@@ -81,12 +115,6 @@ export function clearDynamax(state: DynamaxState): void {
   state.turnActive = false;
 }
 
-export function consumeDynamaxOneShot(state: DynamaxState): boolean {
-  const pending = state.oneShotPending;
-  state.oneShotPending = false;
-  return pending;
-}
-
 export function isDynamaxActive(state: DynamaxState): boolean {
   return state.sticky || state.oneShotPending || state.turnActive;
 }
@@ -128,24 +156,85 @@ export function registerDynamax(
   options: DynamaxRegistrationOptions = {},
 ): void {
   const runtimes: DynamaxRuntimeStore = new Map();
+  const effect = options.effect ?? resolveDynamaxEffect();
+  let editorInstallation: DynamaxEditorInstallation | undefined;
   const openInspector =
     options.openInspector ??
     ((ctx: ExtensionContext): void => {
       ctx.ui.notify("No workflow inspector is available yet", "warning");
     });
-  const refreshIfVisible = (ctx: ExtensionContext): void => {
-    const runtime = getDynamaxRuntime(runtimes, ctx);
-    if (isDynamaxActive(runtime.state) || runtime.runningWorkflow) {
-      updateDynamaxSurfaces(ctx, runtime, shortcuts);
+  const installEditor = (ctx: ExtensionContext): void => {
+    if (ctx.mode !== "tui" || effect === "off") return;
+    const previousFactory = ctx.ui.getEditorComponent();
+    if (editorInstallation && editorInstallation.factory === previousFactory) return;
+
+    const decorations = new Set<DynamaxEditorDecoration>();
+    const installation: DynamaxEditorInstallation = {
+      previousFactory,
+      decorations,
+      factory: (tui, theme, keybindings) => {
+        const decorate = (editor: EditorComponent): EditorComponent => {
+          const decoration = decorateDynamaxEditor(editor, () => tui.requestRender(), {
+            effect,
+            scheduler: options.animationScheduler,
+            isActive: () => editorInstallation === installation && ctx.ui.getEditorComponent() === installation.factory,
+          });
+          decorations.add(decoration);
+          return decoration.editor;
+        };
+        if (!previousFactory) return decorate(new CustomEditor(tui, theme, keybindings));
+
+        let editor: EditorComponent;
+        try {
+          editor = previousFactory(tui, theme, keybindings);
+        } catch (error) {
+          ctx.ui.notify(
+            `Dynamax could not compose the existing custom editor (${unknownErrorMessage(error)}); using pi's stock-compatible CustomEditor so highlighting stays enabled`,
+            "warning",
+          );
+          installation.previousFactory = undefined;
+          return decorate(new CustomEditor(tui, theme, keybindings));
+        }
+
+        try {
+          return decorate(editor);
+        } catch (error) {
+          ctx.ui.notify(
+            `Dynamax could not decorate the existing custom editor (${unknownErrorMessage(error)}); using pi's stock-compatible CustomEditor so highlighting stays enabled`,
+            "warning",
+          );
+          return decorate(new CustomEditor(tui, theme, keybindings));
+        }
+      },
+    };
+
+    try {
+      ctx.ui.setEditorComponent(installation.factory);
+    } catch (error) {
+      disposeDynamaxDecorations(decorations);
+      ctx.ui.notify(`Dynamax highlighting could not be installed: ${unknownErrorMessage(error)}`, "error");
+      throw error;
+    }
+    editorInstallation = installation;
+  };
+  const uninstallEditor = (ctx: ExtensionContext): void => {
+    const installation = editorInstallation;
+    if (!installation) return;
+    editorInstallation = undefined;
+    disposeDynamaxDecorations(installation.decorations);
+    if (ctx.mode === "tui" && ctx.ui.getEditorComponent() === installation.factory) {
+      ctx.ui.setEditorComponent(installation.previousFactory);
     }
   };
 
   pi.on("session_start", (_event, ctx) => {
+    installEditor(ctx);
     updateDynamaxSurfaces(ctx, getDynamaxRuntime(runtimes, ctx), shortcuts);
   });
 
   pi.on("session_shutdown", (_event, ctx) => {
-    clearDynamaxSurfaces(ctx, getDynamaxRuntime(runtimes, ctx));
+    uninstallEditor(ctx);
+    clearDynamaxSurfaces(ctx);
   });
 
   pi.on("input", (event, ctx) => {
@@ -166,26 +255,6 @@ export function registerDynamax(
     return { systemPrompt };
   });
 
-  pi.on("agent_start", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
-  pi.on("message_start", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
-  pi.on("message_update", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
-  pi.on("message_end", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
-  pi.on("turn_end", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
   pi.on("agent_end", (_event, ctx) => {
     const runtime = getDynamaxRuntime(runtimes, ctx);
     runtime.runningWorkflow = undefined;
@@ -194,23 +263,17 @@ export function registerDynamax(
   });
 
   pi.on("tool_execution_start", (event, ctx) => {
+    if (event.toolName !== "workflow") return undefined;
     const runtime = getDynamaxRuntime(runtimes, ctx);
-    if (event.toolName === "workflow") {
-      runtime.runningWorkflow = workflowLabel(event.args);
-    }
+    runtime.runningWorkflow = workflowLabel(event.args);
     updateDynamaxSurfaces(ctx, runtime, shortcuts);
     return undefined;
   });
 
-  pi.on("tool_execution_update", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
   pi.on("tool_execution_end", (event, ctx) => {
+    if (event.toolName !== "workflow") return undefined;
     const runtime = getDynamaxRuntime(runtimes, ctx);
-    if (event.toolName === "workflow") {
-      runtime.runningWorkflow = undefined;
-    }
+    runtime.runningWorkflow = undefined;
     updateDynamaxSurfaces(ctx, runtime, shortcuts);
     return undefined;
   });
@@ -233,6 +296,7 @@ export function registerDynamax(
 
   pi.registerCommand("workflow:dynamax", {
     description: "Toggle Dynamax workflow orchestration: /workflow:dynamax [on|off|status]",
+    getArgumentCompletions: (argumentPrefix) => completeCurrentArgument(argumentPrefix, DYNAMAX_ACTION_COMPLETIONS),
     handler: async (args, ctx) => {
       const runtime = getDynamaxRuntime(runtimes, ctx);
       const action = args.trim().toLowerCase();
@@ -241,7 +305,7 @@ export function registerDynamax(
         return;
       }
       if (action === "on") {
-        setDynamaxSticky(runtime.state, true);
+        enableDynamaxSticky(runtime.state);
         updateDynamaxSurfaces(ctx, runtime, shortcuts);
         ctx.ui.notify("Dynamax workflow orchestration is on for this session", "info");
         return;
@@ -263,10 +327,8 @@ export function registerDynamax(
 
 export function updateDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">, runtime: DynamaxRuntime, shortcuts: DynamaxShortcuts): void {
   if (!ctx.hasUI) return;
-  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,11 +336,9 @@ 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);
-  ctx.ui.setStatus(DYNAMAX_WIDGET_KEY, undefined);
 }
 
 function workflowLabel(args: unknown): string {