@stigmer/react 1.0.4 → 2.0.0

package/src/workflow/useWorkflowDiffGraph.ts

@@ -0,0 +1,161 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import type { Node, Edge } from "@xyflow/react";
+import { yamlToGraph, toReactFlowElements } from "./workflow-graph-conversions";
+import type { CanvasTaskNodeData, CanvasTransitionEdgeData } from "./workflow-graph-conversions";
+import { applyDagreLayout } from "./layout";
+import { computeGraphDiff, buildDiffGraph } from "./diff";
+import type { GraphDiff, NodeDiffEntry } from "./diff";
+
+/** Options for {@link useWorkflowDiffGraph}. */
+export interface UseWorkflowDiffGraphOptions {
+  /** YAML content of the original (before) workflow. Empty string for generate scenarios. */
+  readonly beforeYaml: string;
+  /** YAML content of the updated (after) workflow. */
+  readonly afterYaml: string;
+}
+
+/** Return value of {@link useWorkflowDiffGraph}. */
+export interface UseWorkflowDiffGraphReturn {
+  /** React Flow nodes with diff state merged into data. */
+  readonly nodes: Node[];
+  /** React Flow edges with diff state merged into data. */
+  readonly edges: Edge[];
+  /** Computed graph diff (null on error or empty input). */
+  readonly diff: GraphDiff | null;
+  /** Parse or build error message. */
+  readonly error: string | null;
+  /** Currently selected task name. */
+  readonly selectedTaskName: string | null;
+  /** Set the selected task. */
+  readonly setSelectedTaskName: (name: string | null) => void;
+}
+
+const EMPTY_NODES: Node[] = [];
+const EMPTY_EDGES: Edge[] = [];
+
+/**
+ * Behavior hook that builds a complete diff visualization from two YAML strings.
+ *
+ * Pipeline (all in useMemo for referential stability — DD-010):
+ * 1. Parse beforeYaml → before graph model (empty string → empty model)
+ * 2. Parse afterYaml → after graph model
+ * 3. Compute diff between before and after
+ * 4. Build merged graph containing all nodes/edges
+ * 5. Apply dagre layout to merged graph
+ * 6. Convert to React Flow elements
+ * 7. Merge diff status into node/edge data
+ *
+ * @since T14 (AI-Assisted Workflow Creation)
+ */
+export function useWorkflowDiffGraph(
+  options: UseWorkflowDiffGraphOptions,
+): UseWorkflowDiffGraphReturn {
+  const { beforeYaml, afterYaml } = options;
+  const [selectedTaskName, setSelectedTaskName] = useState<string | null>(null);
+
+  const result = useMemo(() => {
+    // Both empty → no diff
+    if (!afterYaml.trim()) {
+      return { nodes: EMPTY_NODES, edges: EMPTY_EDGES, diff: null, error: null };
+    }
+
+    try {
+      const afterGraph = yamlToGraph(afterYaml);
+
+      // Empty before → generate scenario: all nodes are "added"
+      if (!beforeYaml.trim()) {
+        const emptyBefore = {
+          document: afterGraph.document,
+          nodes: [],
+          edges: [],
+        };
+        const diff = computeGraphDiff(emptyBefore, afterGraph);
+        const merged = buildDiffGraph(emptyBefore, afterGraph, diff);
+        const laidOut = applyDagreLayout(merged);
+        const elements = toReactFlowElements(laidOut);
+        return {
+          ...mergeOverlays(elements, diff),
+          diff,
+          error: null,
+        };
+      }
+
+      const beforeGraph = yamlToGraph(beforeYaml);
+      const diff = computeGraphDiff(beforeGraph, afterGraph);
+      const merged = buildDiffGraph(beforeGraph, afterGraph, diff);
+      const laidOut = applyDagreLayout(merged);
+      const elements = toReactFlowElements(laidOut);
+
+      return {
+        ...mergeOverlays(elements, diff),
+        diff,
+        error: null,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Failed to compute diff";
+      return { nodes: EMPTY_NODES, edges: EMPTY_EDGES, diff: null, error: message };
+    }
+  }, [beforeYaml, afterYaml]);
+
+  return {
+    nodes: result.nodes,
+    edges: result.edges,
+    diff: result.diff,
+    error: result.error,
+    selectedTaskName,
+    setSelectedTaskName,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Overlay merging
+// ---------------------------------------------------------------------------
+
+function mergeOverlays(
+  elements: { nodes: Node[]; edges: Edge[] },
+  diff: GraphDiff,
+): { nodes: Node[]; edges: Edge[] } {
+  const nodes = elements.nodes.map((node) => {
+    const nodeData = node.data as CanvasTaskNodeData;
+    const entry = diff.nodes.get(node.id);
+    if (!entry) return node;
+
+    return {
+      ...node,
+      data: {
+        ...nodeData,
+        diffState: {
+          status: entry.status,
+          changedFields: entry.changedFields,
+        },
+      },
+      draggable: false,
+      connectable: false,
+      deletable: false,
+    };
+  });
+
+  const edges = elements.edges.map((edge) => {
+    const edgeData = (edge.data ?? {}) as CanvasTransitionEdgeData;
+    const edgeKey = edge.data?.sourceHandle
+      ? `${edge.source}|${edge.target}|${(edge as { sourceHandle?: string }).sourceHandle}`
+      : `${edge.source}|${edge.target}`;
+
+    const entry = diff.edges.get(edgeKey);
+    if (!entry) return edge;
+
+    return {
+      ...edge,
+      data: {
+        ...edgeData,
+        diffState: entry.status,
+      },
+    };
+  });
+
+  return { nodes, edges };
+}
+
+export type { GraphDiff, NodeDiffEntry };

package/src/workflow/useWorkflowEditor.ts

@@ -38,6 +38,10 @@ export interface UseWorkflowEditorReturn {
   readonly errorCount: number;
   /** Count of warning-level diagnostics. */
   readonly warningCount: number;
+  /** Current version message (optional description of what changed). */
+  readonly versionMessage: string;
+  /** Update the version message. */
+  readonly setVersionMessage: (value: string) => void;
 }
 
 /**
@@ -56,6 +60,7 @@ export function useWorkflowEditor(
   options: UseWorkflowEditorOptions,
 ): UseWorkflowEditorReturn {
   const [yaml, setYaml] = useState(initialYaml);
+  const [versionMessage, setVersionMessage] = useState("");
   const initialRef = useRef(initialYaml);
 
   const registry = useTaskKindRegistry();
@@ -66,12 +71,16 @@ export function useWorkflowEditor(
   const isDirty = yaml !== initialRef.current;
 
   const save = useCallback(async (): Promise<boolean> => {
-    const success = await applySave(yaml);
+    const saveOpts = versionMessage.trim()
+      ? { versionMessage: versionMessage.trim() }
+      : undefined;
+    const success = await applySave(yaml, saveOpts);
     if (success) {
       initialRef.current = yaml;
+      setVersionMessage("");
     }
     return success;
-  }, [applySave, yaml]);
+  }, [applySave, yaml, versionMessage]);
 
   const reset = useCallback(() => {
     setYaml(initialRef.current);
@@ -100,7 +109,9 @@ export function useWorkflowEditor(
       topology,
       errorCount,
       warningCount,
+      versionMessage,
+      setVersionMessage,
     }),
-    [yaml, setYaml, diagnostics, isDirty, isSaving, saveError, save, reset, topology, errorCount, warningCount],
+    [yaml, setYaml, diagnostics, isDirty, isSaving, saveError, save, reset, topology, errorCount, warningCount, versionMessage, setVersionMessage],
   );
 }

package/src/workflow/useWorkflowExecution.ts

@@ -1,9 +1,20 @@
 "use client";
 
+import { useEffect, useRef } from "react";
 import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
 import { isNotFound } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
 import { useFetch } from "../internal/useFetch";
+import { useRunnerAdapter } from "../runner-adapter";
+import { useExecutionTarget } from "../execution-target-context";
+
+const TERMINAL_EXECUTION_PHASES = new Set([
+  ExecutionPhase.EXECUTION_COMPLETED,
+  ExecutionPhase.EXECUTION_FAILED,
+  ExecutionPhase.EXECUTION_CANCELLED,
+  ExecutionPhase.EXECUTION_TERMINATED,
+]);
 
 /** Return value of {@link useWorkflowExecution}. */
 export interface UseWorkflowExecutionReturn {
@@ -44,6 +55,9 @@ export function useWorkflowExecution(
   executionId: string | null,
 ): UseWorkflowExecutionReturn {
   const stigmer = useStigmer();
+  const adapter = useRunnerAdapter();
+  const contextTarget = useExecutionTarget();
+  const terminatedRef = useRef<string | null>(null);
 
   const fetchFn = executionId
     ? async () => {
@@ -63,5 +77,26 @@ export function useWorkflowExecution(
     { cacheKey: executionId ? `workflow-execution:${executionId}` : undefined },
   );
 
+  useEffect(() => {
+    const phase = execution?.status?.phase;
+    const fetchedId = execution?.metadata?.id;
+    if (
+      adapter &&
+      contextTarget === "local" &&
+      executionId &&
+      phase != null &&
+      TERMINAL_EXECUTION_PHASES.has(phase) &&
+      fetchedId === executionId &&
+      terminatedRef.current !== executionId
+    ) {
+      terminatedRef.current = executionId;
+      adapter.onWorkflowExecutionTerminated(executionId).catch(() => {});
+    }
+  }, [execution?.status?.phase, execution?.metadata?.id, executionId, adapter, contextTarget]);
+
+  useEffect(() => {
+    terminatedRef.current = null;
+  }, [executionId]);
+
   return { execution, isLoading, isRefetching, error, refetch };
 }

package/src/workflow/useWorkflowExecutionActions.ts

@@ -3,7 +3,7 @@
 import { useCallback, useRef, useState } from "react";
 import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
 import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { create } from "@bufbuild/protobuf";
+import { create, type JsonObject } from "@bufbuild/protobuf";
 import {
   CancelWorkflowExecutionInputSchema,
   TerminateWorkflowExecutionInputSchema,
@@ -11,10 +11,25 @@ import {
   ResumeWorkflowExecutionInputSchema,
   RecoverWorkflowExecutionInputSchema,
   SubmitWorkflowApprovalInputSchema,
+  SubmitWorkflowTaskApprovalInputSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Options for {@link useWorkflowExecutionActions}. */
+export interface UseWorkflowExecutionActionsOptions {
+  /**
+   * Called after any lifecycle action (cancel, terminate, pause, resume,
+   * recover) succeeds. Receives the updated execution returned by the
+   * server. Useful for triggering a refetch of execution data so the UI
+   * reflects the new phase.
+   *
+   * Not called for approval submissions — those are background operations
+   * whose effects arrive via the event stream.
+   */
+  readonly onSuccess?: (execution: WorkflowExecution) => void;
+}
+
 /** Return value of {@link useWorkflowExecutionActions}. */
 export interface UseWorkflowExecutionActionsReturn {
   /** Cancel a running execution gracefully. */
@@ -25,7 +40,17 @@ export interface UseWorkflowExecutionActionsReturn {
   readonly pause: (reason?: string) => Promise<WorkflowExecution | null>;
   /** Resume a paused execution. */
   readonly resume: () => Promise<WorkflowExecution | null>;
-  /** Recover a failed execution from its last checkpoint. */
+  /**
+   * Recover a failed execution with task-level resume.
+   *
+   * Terminates stale workflows, re-resolves environment variables (picks up
+   * any config fixes), and starts a fresh run in recovery mode. Completed
+   * tasks are skipped — their outputs are restored from the event log —
+   * and execution resumes from the first incomplete or failed task.
+   *
+   * @param reason - Optional audit trail message explaining why recovery
+   *   was triggered (e.g., "Rotated API key").
+   */
   readonly recover: (reason?: string) => Promise<WorkflowExecution | null>;
   /** Submit an approval decision for a child agent's tool execution. */
   readonly submitApproval: (
@@ -33,10 +58,25 @@ export interface UseWorkflowExecutionActionsReturn {
     action: ApprovalAction,
     comment?: string,
   ) => Promise<WorkflowExecution | null>;
+  /**
+   * Submit a reviewer's decision for a workflow-level human_input task.
+   *
+   * Unlike `submitApproval` (which forwards agent tool approvals),
+   * this sends a Temporal signal to the workflow runner's human_input
+   * orchestrator, unblocking the task with the selected outcome.
+   */
+  readonly submitTaskApproval: (
+    taskName: string,
+    outcome: string,
+    formData?: Record<string, unknown>,
+    comment?: string,
+  ) => Promise<WorkflowExecution | null>;
   /** `true` while any action is in flight. */
   readonly isSubmitting: boolean;
   /** Error from the last failed action, or `null`. */
   readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
 }
 
 /**
@@ -50,7 +90,9 @@ export interface UseWorkflowExecutionActionsReturn {
  *
  * @example
  * ```tsx
- * const actions = useWorkflowExecutionActions(executionId);
+ * const actions = useWorkflowExecutionActions(executionId, {
+ *   onSuccess: () => refetchExecution(),
+ * });
  *
  * <button onClick={() => actions.cancel("No longer needed")} disabled={actions.isSubmitting}>
  *   Cancel
@@ -59,6 +101,7 @@ export interface UseWorkflowExecutionActionsReturn {
  */
 export function useWorkflowExecutionActions(
   executionId: string | null,
+  options?: UseWorkflowExecutionActionsOptions,
 ): UseWorkflowExecutionActionsReturn {
   const stigmer = useStigmer();
   const [isSubmitting, setIsSubmitting] = useState(false);
@@ -68,14 +111,22 @@ export function useWorkflowExecutionActions(
   executionIdRef.current = executionId;
   const stigmerRef = useRef(stigmer);
   stigmerRef.current = stigmer;
+  const onSuccessRef = useRef(options?.onSuccess);
+  onSuccessRef.current = options?.onSuccess;
+
+  const clearError = useCallback(() => setError(null), []);
 
   const wrap = useCallback(
-    async (fn: () => Promise<WorkflowExecution>): Promise<WorkflowExecution | null> => {
+    async (
+      fn: () => Promise<WorkflowExecution>,
+      fireOnSuccess = true,
+    ): Promise<WorkflowExecution | null> => {
       if (!executionIdRef.current) return null;
       setIsSubmitting(true);
       setError(null);
       try {
         const result = await fn();
+        if (fireOnSuccess) onSuccessRef.current?.(result);
         return result;
       } catch (err) {
         setError(toError(err));
@@ -153,15 +204,36 @@ export function useWorkflowExecutionActions(
 
   const submitApproval = useCallback(
     (toolCallId: string, action: ApprovalAction, comment?: string) =>
-      wrap(() =>
-        stigmerRef.current.workflowExecution.submitApproval(
-          create(SubmitWorkflowApprovalInputSchema, {
-            executionId: executionIdRef.current!,
-            toolCallId,
-            action,
-            comment: comment ?? "",
-          }),
-        ),
+      wrap(
+        () =>
+          stigmerRef.current.workflowExecution.submitApproval(
+            create(SubmitWorkflowApprovalInputSchema, {
+              executionId: executionIdRef.current!,
+              toolCallId,
+              action,
+              comment: comment ?? "",
+            }),
+          ),
+        false,
+      ),
+    [wrap],
+  );
+
+  const submitTaskApproval = useCallback(
+    (taskName: string, outcome: string, formData?: Record<string, unknown>, comment?: string) =>
+      wrap(
+        () =>
+          stigmerRef.current.workflowExecution.submitWorkflowTaskApproval(
+            create(SubmitWorkflowTaskApprovalInputSchema, {
+              executionId: executionIdRef.current!,
+              taskName,
+              outcome,
+              formData: formData as JsonObject | undefined,
+              reviewer: "",
+              comment: comment ?? "",
+            }),
+          ),
+        false,
       ),
     [wrap],
   );
@@ -173,7 +245,9 @@ export function useWorkflowExecutionActions(
     resume,
     recover,
     submitApproval,
+    submitTaskApproval,
     isSubmitting,
     error,
+    clearError,
   };
 }

package/src/workflow/useWorkflowExecutionEventStream.ts

@@ -72,6 +72,24 @@ const TERMINAL_PHASES = new Set<ExecutionPhase>([
   ExecutionPhase.EXECUTION_TERMINATED,
 ]);
 
+/**
+ * Pure function that detects a terminal-to-active phase transition —
+ * the signal that a recovery has begun and the event store should be
+ * reset to clear stale events from the previous run.
+ *
+ * Returns `false` when either phase is `undefined` (initial load or
+ * unresolved execution), preventing false resets on first render.
+ *
+ * Extracted for testability (DD-003).
+ */
+export function isRecoveryTransition(
+  prevPhase: ExecutionPhase | undefined,
+  nextPhase: ExecutionPhase | undefined,
+): boolean {
+  if (prevPhase === undefined || nextPhase === undefined) return false;
+  return TERMINAL_PHASES.has(prevPhase) && !TERMINAL_PHASES.has(nextPhase);
+}
+
 /**
  * Behavior hook that manages a live event stream subscription for a
  * workflow execution, or batch-loads events for completed executions.
@@ -87,6 +105,16 @@ const TERMINAL_PHASES = new Set<ExecutionPhase>([
  * For terminal executions: loads the full event log via paginated
  * `getEventLog` calls.
  *
+ * On recovery (terminal → active phase transition for the same
+ * execution), the store is reset so stale events from the failed run
+ * are cleared before the new subscription begins.
+ *
+ * When `executionId` changes to a different execution, the store is
+ * reset before subscribing — mirroring `useFetch`'s identity-change
+ * reset — so the previous run's append-only events neither render as
+ * stale progress nor cause the live subscription to resume from the
+ * wrong `afterSequence`.
+ *
  * Pass `null` for `executionId` to skip (stable no-op).
  */
 export function useWorkflowExecutionEventStream(
@@ -113,9 +141,21 @@ export function useWorkflowExecutionEventStream(
   const storeRef = useRef(store);
   storeRef.current = store;
 
+  // Track previous phase to detect recovery (terminal → active).
+  // useRef (not useState) because the transition drives an effect-time
+  // side effect (store reset + gRPC subscription), not a rendered value.
+  const prevPhaseRef = useRef<ExecutionPhase | undefined>(undefined);
+
+  // Track the execution the store is currently populated for, so we can
+  // detect a switch to a different execution (vs. a reconnect or phase
+  // change for the same one). Same role as useFetch's prevIdentityDepsRef.
+  const prevExecutionIdRef = useRef<string | null>(null);
+
   useEffect(() => {
     if (!executionId) {
       store.reset();
+      prevPhaseRef.current = undefined;
+      prevExecutionIdRef.current = null;
       return;
     }
 
@@ -123,6 +163,40 @@ export function useWorkflowExecutionEventStream(
     const currentStore = storeRef.current;
     const isTerminal = executionPhase !== undefined && TERMINAL_PHASES.has(executionPhase);
 
+    // Execution switch (A → B): the store is append-only and holds the
+    // previous run's events. Clear it before subscribing so we neither
+    // render B with A's progress nor resume B's live stream from A's
+    // afterSequence (which would silently drop B's earlier events).
+    // This is distinct from reconnect (connectKey) and recovery (phase
+    // transition), both of which must preserve/replay events for the
+    // SAME execution. Resetting prevPhaseRef here prevents the A→B phase
+    // delta from being misread as a recovery transition below.
+    const isExecutionSwitch =
+      prevExecutionIdRef.current !== null &&
+      prevExecutionIdRef.current !== executionId;
+    if (isExecutionSwitch) {
+      currentStore.reset();
+      prevPhaseRef.current = undefined;
+    }
+    prevExecutionIdRef.current = executionId;
+
+    // When an execution transitions from a terminal phase back to an
+    // active phase (recovery), clear the store so stale events from the
+    // failed run don't produce contradictory UI (header says "running"
+    // while task badges still show "failed"). After reset,
+    // getLatestSequence() returns 0 and the subscription replays the
+    // full event history — including task_skipped events from the
+    // recovery engine that correctly represent the new run's state.
+    //
+    // Note: unlike useExecutionStream, this hook does NOT reset in the
+    // cleanup function. connectKey (reconnect) is in the deps array —
+    // resetting on cleanup would destroy events on reconnect. The store
+    // is only reset here (recovery) and when executionId becomes null.
+    if (isRecoveryTransition(prevPhaseRef.current, executionPhase)) {
+      currentStore.reset();
+    }
+    prevPhaseRef.current = executionPhase;
+
     if (isTerminal) {
       // Batch-load all events for completed executions
       currentStore.setStreamState({ stage: "connecting", executionId });