feat(deployments): human-readable version descriptions

Author: waleedlatif1

apps/sim/hooks/queries/deployments.ts

@@ -421,28 +421,27 @@ interface GenerateVersionDescriptionVariables {
   onStreamChunk?: (accumulated: string) => void
 }
 
-const VERSION_DESCRIPTION_SYSTEM_PROMPT = `You are a technical writer generating concise deployment version descriptions.
+const VERSION_DESCRIPTION_SYSTEM_PROMPT = `You are writing deployment version descriptions for a workflow automation platform.
 
-Given a diff of changes between two workflow versions, write a brief, factual description (1-2 sentences, under 300 characters) that states ONLY what changed.
+Write a brief, factual description (1-3 sentences, under 400 characters) that states what changed between versions.
 
-RULES:
-- State specific values when provided (e.g. "model changed from X to Y")
-- Do NOT wrap your response in quotes
-- Do NOT add filler phrases like "streamlining the workflow", "for improved efficiency"
-- Do NOT use markdown formatting
-- Do NOT include version numbers
-- Do NOT start with "This version" or similar phrases
+Guidelines:
+- Use the specific values provided (credential names, channel names, model names)
+- Be precise: "Changes Slack channel from #general to #alerts" not "Updates channel configuration"
+- Combine related changes: "Updates Agent model to claude-sonnet-4-5 and increases temperature to 0.8"
+- For added/removed blocks, mention their purpose if clear from the type
 
-Good examples:
-- Changes model in Agent 1 from gpt-4o to claude-sonnet-4-20250514.
-- Adds Slack notification block. Updates webhook URL to production endpoint.
-- Removes Function block and its connection to Router.
+Format rules:
+- Plain text only, no quotes around the response
+- No markdown formatting
+- No filler phrases ("for improved efficiency", "streamlining the workflow")
+- No version numbers or "This version" prefixes
 
-Bad examples:
-- "Changes model..." (NO - don't wrap in quotes)
-- Changes model, streamlining the workflow. (NO - don't add filler)
-
-Respond with ONLY the plain text description.`
+Examples:
+- Switches Agent model from gpt-4o to claude-sonnet-4-5. Changes Slack credential to Production OAuth.
+- Adds Gmail notification block for sending alerts. Removes unused Function block. Updates Router conditions.
+- Updates system prompt for more concise responses. Reduces temperature from 0.7 to 0.3.
+- Connects Slack block to Router. Adds 2 new workflow connections. Configures error handling path.`
 
 /**
  * Hook for generating a version description using AI based on workflow diff
@@ -454,7 +453,7 @@ export function useGenerateVersionDescription() {
       version,
       onStreamChunk,
     }: GenerateVersionDescriptionVariables): Promise<string> => {
-      const { generateWorkflowDiffSummary, formatDiffSummaryForDescription } = await import(
+      const { generateWorkflowDiffSummary, formatDiffSummaryForDescriptionAsync } = await import(
         '@/lib/workflows/comparison/compare'
       )
 
@@ -470,7 +469,11 @@ export function useGenerateVersionDescription() {
       }
 
       const diffSummary = generateWorkflowDiffSummary(currentState, previousState)
-      const diffText = formatDiffSummaryForDescription(diffSummary)
+      const diffText = await formatDiffSummaryForDescriptionAsync(
+        diffSummary,
+        currentState,
+        workflowId
+      )
 
       const wandResponse = await fetch('/api/wand', {
         method: 'POST',

apps/sim/lib/workflows/comparison/compare.ts

@@ -1,3 +1,4 @@
+import { createLogger } from '@sim/logger'
 import type { WorkflowState } from '@/stores/workflows/workflow/types'
 import {
   extractBlockFieldsForComparison,
@@ -12,6 +13,9 @@ import {
   normalizeVariables,
   sanitizeVariable,
 } from './normalize'
+import { resolveValueForDisplay } from './resolve-values'
+
+const logger = createLogger('WorkflowComparison')
 
 /**
  * Compare the current workflow state with the deployed state to detect meaningful changes.
@@ -406,3 +410,130 @@ export function formatDiffSummaryForDescription(summary: WorkflowDiffSummary): s
 
   return changes.join('\n')
 }
+
+/**
+ * Converts a WorkflowDiffSummary to a human-readable string with resolved display names.
+ * Resolves IDs (credentials, channels, workflows, etc.) to human-readable names using
+ * the selector registry infrastructure.
+ *
+ * @param summary - The diff summary to format
+ * @param currentState - The current workflow state for context extraction
+ * @param workflowId - The workflow ID for API calls
+ * @returns A formatted string describing the changes with resolved names
+ */
+export async function formatDiffSummaryForDescriptionAsync(
+  summary: WorkflowDiffSummary,
+  currentState: WorkflowState,
+  workflowId: string
+): Promise<string> {
+  if (!summary.hasChanges) {
+    return 'No structural changes detected (configuration may have changed)'
+  }
+
+  const changes: string[] = []
+
+  for (const block of summary.addedBlocks) {
+    const name = block.name || block.type
+    changes.push(`Added block: ${name} (${block.type})`)
+  }
+
+  for (const block of summary.removedBlocks) {
+    const name = block.name || block.type
+    changes.push(`Removed block: ${name} (${block.type})`)
+  }
+
+  const modifiedBlockPromises = summary.modifiedBlocks.map(async (block) => {
+    const name = block.name || block.type
+    const blockChanges: string[] = []
+
+    const changesToProcess = block.changes.slice(0, 3)
+    const resolvedChanges = await Promise.all(
+      changesToProcess.map(async (change) => {
+        const context = {
+          blockType: block.type,
+          subBlockId: change.field,
+          workflowId,
+          currentState,
+          blockId: block.id,
+        }
+
+        const [oldResolved, newResolved] = await Promise.all([
+          resolveValueForDisplay(change.oldValue, context),
+          resolveValueForDisplay(change.newValue, context),
+        ])
+
+        return {
+          field: change.field,
+          oldLabel: oldResolved.displayLabel,
+          newLabel: newResolved.displayLabel,
+        }
+      })
+    )
+
+    for (const resolved of resolvedChanges) {
+      blockChanges.push(
+        `Modified ${name}: ${resolved.field} changed from "${resolved.oldLabel}" to "${resolved.newLabel}"`
+      )
+    }
+
+    if (block.changes.length > 3) {
+      blockChanges.push(`  ...and ${block.changes.length - 3} more changes in ${name}`)
+    }
+
+    return blockChanges
+  })
+
+  const allModifiedBlockChanges = await Promise.all(modifiedBlockPromises)
+  for (const blockChanges of allModifiedBlockChanges) {
+    changes.push(...blockChanges)
+  }
+
+  if (summary.edgeChanges.added > 0) {
+    changes.push(`Added ${summary.edgeChanges.added} connection(s)`)
+  }
+  if (summary.edgeChanges.removed > 0) {
+    changes.push(`Removed ${summary.edgeChanges.removed} connection(s)`)
+  }
+
+  if (summary.loopChanges.added > 0) {
+    changes.push(`Added ${summary.loopChanges.added} loop(s)`)
+  }
+  if (summary.loopChanges.removed > 0) {
+    changes.push(`Removed ${summary.loopChanges.removed} loop(s)`)
+  }
+  if (summary.loopChanges.modified > 0) {
+    changes.push(`Modified ${summary.loopChanges.modified} loop(s)`)
+  }
+
+  if (summary.parallelChanges.added > 0) {
+    changes.push(`Added ${summary.parallelChanges.added} parallel group(s)`)
+  }
+  if (summary.parallelChanges.removed > 0) {
+    changes.push(`Removed ${summary.parallelChanges.removed} parallel group(s)`)
+  }
+  if (summary.parallelChanges.modified > 0) {
+    changes.push(`Modified ${summary.parallelChanges.modified} parallel group(s)`)
+  }
+
+  const varChanges: string[] = []
+  if (summary.variableChanges.added > 0) {
+    varChanges.push(`${summary.variableChanges.added} added`)
+  }
+  if (summary.variableChanges.removed > 0) {
+    varChanges.push(`${summary.variableChanges.removed} removed`)
+  }
+  if (summary.variableChanges.modified > 0) {
+    varChanges.push(`${summary.variableChanges.modified} modified`)
+  }
+  if (varChanges.length > 0) {
+    changes.push(`Variables: ${varChanges.join(', ')}`)
+  }
+
+  logger.info('Generated async diff description', {
+    workflowId,
+    changeCount: changes.length,
+    modifiedBlocks: summary.modifiedBlocks.length,
+  })
+
+  return changes.join('\n')
+}

apps/sim/lib/workflows/comparison/index.ts

@@ -1,6 +1,7 @@
 export type { FieldChange, WorkflowDiffSummary } from './compare'
 export {
   formatDiffSummaryForDescription,
+  formatDiffSummaryForDescriptionAsync,
   generateWorkflowDiffSummary,
   hasWorkflowChanged,
 } from './compare'
@@ -28,3 +29,9 @@ export {
   sanitizeVariable,
   sortEdges,
 } from './normalize'
+export type { ResolutionContext, ResolvedValue } from './resolve-values'
+export {
+  extractExtendedContext,
+  getBlockCredentialId,
+  resolveValueForDisplay,
+} from './resolve-values'