@n8n/instance-ai 1.12.2 → 1.13.0

package/dist/tools/workflows/build-workflow.tool.js

@@ -5,22 +5,23 @@ exports.createBuildWorkflowTool = createBuildWorkflowTool;
 const agents_1 = require("@n8n/agents");
 const api_types_1 = require("@n8n/api-types");
 const utils_1 = require("@n8n/utils");
-const workflow_sdk_1 = require("@n8n/workflow-sdk");
 const nanoid_1 = require("nanoid");
 const zod_1 = require("zod");
+const plan_verification_simulation_1 = require("./plan-verification-simulation");
 const resolve_credentials_1 = require("./resolve-credentials");
 const setup_workflow_service_1 = require("./setup-workflow.service");
-const submit_workflow_tool_1 = require("./submit-workflow.tool");
+const workflow_build_context_1 = require("./workflow-build-context");
+const workflow_build_remediation_1 = require("./workflow-build-remediation");
+const workflow_build_reporting_1 = require("./workflow-build-reporting");
+const workflow_build_routing_1 = require("./workflow-build-routing");
+const workflow_build_telemetry_1 = require("./workflow-build-telemetry");
+const workflow_file_bindings_1 = require("./workflow-file-bindings");
 const workflow_json_utils_1 = require("./workflow-json-utils");
-const workflow_builder_1 = require("../../workflow-builder");
+const workflow_source_compiler_1 = require("./workflow-source-compiler");
+const workflow_validation_warnings_1 = require("./workflow-validation-warnings");
 const build_failure_tracker_1 = require("../../workflow-builder/build-failure-tracker");
-const extract_code_1 = require("../../workflow-builder/extract-code");
-const patch_code_1 = require("../../workflow-builder/patch-code");
 const remediation_1 = require("../../workflow-loop/remediation");
-const patchSchema = zod_1.z.object({
-    old_str: zod_1.z.string().describe('Exact string to find in the code'),
-    new_str: zod_1.z.string().describe('Replacement string'),
-});
+const workflow_loop_state_1 = require("../../workflow-loop/workflow-loop-state");
 const confirmationSuspendSchema = zod_1.z.object({
     requestId: zod_1.z.string(),
     message: zod_1.z.string(),
@@ -29,27 +30,25 @@ const confirmationSuspendSchema = zod_1.z.object({
 const confirmationResumeSchema = zod_1.z.object({
     approved: zod_1.z.boolean(),
 });
-function coercePatches(value) {
-    if (typeof value !== 'string')
-        return value;
-    try {
-        return JSON.parse(value);
-    }
-    catch {
-        return value;
-    }
-}
-exports.buildWorkflowInputSchema = zod_1.z.object({
-    code: zod_1.z
+exports.buildWorkflowInputSchema = zod_1.z
+    .object({
+    filePath: zod_1.z
+        .string()
+        .min(1)
+        .refine((value) => {
+        try {
+            (0, workflow_file_bindings_1.normalizeWorkflowSourceFilePath)(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { message: 'Workflow source file path must stay within the workspace root.' })
+        .describe('Workspace path to the workflow source file to build. Supports TypeScript SDK files and WorkflowJSON .json files.'),
+    workflowId: zod_1.z
         .string()
         .optional()
-        .describe('Full TypeScript workflow code using @n8n/workflow-sdk. Required for new workflows.'),
-    patches: zod_1.z
-        .preprocess(coercePatches, zod_1.z.array(patchSchema))
-        .optional()
-        .describe('Array of {old_str, new_str} replacements to apply to existing workflow code. ' +
-        'Requires workflowId. More efficient than resending full code for small fixes.'),
-    workflowId: zod_1.z.string().optional().describe('Existing workflow ID to update (omit to create new)'),
+        .describe('Existing workflow ID to bind this file to on the first update. Once bound, omit this on retries.'),
     projectId: zod_1.z
         .string()
         .optional()
@@ -58,13 +57,14 @@ exports.buildWorkflowInputSchema = zod_1.z.object({
     workItemId: zod_1.z
         .string()
         .optional()
-        .describe('Existing workflow-loop work item ID when patching a workflow from verification guidance.'),
+        .describe('Optional workflow-loop work item ID when repairing a workflow.'),
     isSupportingWorkflow: zod_1.z
         .boolean()
         .optional()
         .describe('Set true when saving a supporting sub-workflow that will be referenced by the main workflow. ' +
         'In a planned build task, this completes the task only when the task itself is marked isSupportingWorkflow; otherwise save the main workflow later.'),
-});
+})
+    .strict();
 const triggerNodeOutputSchema = zod_1.z.object({
     nodeName: zod_1.z.string(),
     nodeType: zod_1.z.string(),
@@ -95,165 +95,17 @@ const setupRequirementOutputSchema = zod_1.z.discriminatedUnion('status', [
         guidance: zod_1.z.string(),
     }),
 ]);
-function hasMockedCredentials(outcome) {
-    return ((outcome.mockedCredentialTypes?.length ?? 0) > 0 ||
-        Object.keys(outcome.mockedCredentialsByNode ?? {}).length > 0);
-}
-function hasCredentialVerificationData(outcome) {
-    return (Object.keys(outcome.verificationPinData ?? {}).length > 0 ||
-        outcome.usesWorkflowPinDataForVerification === true);
-}
-function getBuildFailureTrackingKey({ workItemId, workflowId, workflowName, isAuxiliarySupportingWorkflow, buildContext, runId, }) {
-    if (workItemId)
-        return workItemId;
-    if (isAuxiliarySupportingWorkflow) {
-        return [
-            'supporting-workflow',
-            buildContext?.taskId ?? (runId ? `run:${runId}` : 'unknown-run'),
-            workflowId ?? workflowName ?? 'new',
-        ].join(':');
-    }
-    return (buildContext?.workItemId ??
-        buildContext?.taskId ??
-        workflowId ??
-        workflowName ??
-        `run:${runId ?? 'unknown'}`);
-}
-function determineVerificationReadiness(outcome) {
-    if (!outcome.submitted) {
-        return {
-            status: 'not_verifiable',
-            reason: 'not-submitted',
-            guidance: 'The build did not submit a workflow, so there is nothing to verify.',
-        };
-    }
-    if (!outcome.workflowId) {
-        return {
-            status: 'not_verifiable',
-            reason: 'missing-workflow-id',
-            guidance: 'The build outcome does not include a workflow ID.',
-        };
-    }
-    if (outcome.hasUnresolvedPlaceholders) {
-        return {
-            status: 'needs_setup',
-            reason: 'unresolved-placeholders',
-            guidance: 'Route the workflow through setup before verification.',
-        };
-    }
-    if (hasMockedCredentials(outcome) && !hasCredentialVerificationData(outcome)) {
-        return {
-            status: 'needs_setup',
-            reason: 'missing-mocked-credential-pin-data',
-            guidance: 'Route the workflow through setup because mocked credentials cannot be verified.',
-        };
-    }
-    if (!outcome.triggerNodes?.some((node) => (0, workflow_json_utils_1.isMockableTriggerNodeType)(node.nodeType))) {
-        return {
-            status: 'not_verifiable',
-            reason: 'non-mockable-trigger',
-            guidance: 'The workflow does not have a trigger the post-build verifier can exercise.',
-        };
-    }
-    return { status: 'ready' };
-}
-function determineSetupRequirement(outcome) {
-    if (!outcome.submitted || !outcome.workflowId) {
-        return { status: 'not_required' };
-    }
-    if (outcome.hasUnresolvedPlaceholders) {
-        return {
-            status: 'required',
-            reason: 'unresolved-placeholders',
-            guidance: 'Route the workflow through setup so the user can fill unresolved values.',
-        };
-    }
-    if (hasMockedCredentials(outcome)) {
-        return {
-            status: 'required',
-            reason: 'mocked-credentials',
-            guidance: 'Route the workflow through setup so the user can add real credentials.',
-        };
-    }
-    return { status: 'not_required' };
-}
-function withDeterministicRouting(outcome) {
-    return {
-        ...outcome,
-        verificationReadiness: determineVerificationReadiness(outcome),
-        setupRequirement: determineSetupRequirement(outcome),
-    };
-}
-function isApprovedBuildContext(context) {
-    const buildContext = context.workflowBuildContext;
-    return Boolean(buildContext?.plannedTaskService ?? buildContext?.allowPostPlanWorkflowCreate);
-}
-async function resolveWorkflowName(context, workflowId) {
-    try {
-        return (await context.workflowService.getAsWorkflowJSON(workflowId)).name || 'workflow';
-    }
-    catch {
-        return 'workflow';
-    }
-}
-async function reportWorkflowBuildOutcome(context, outcome, options = {}) {
-    const buildContext = context.workflowBuildContext;
-    if (!buildContext)
-        return;
-    if (options.storeOnRunContext !== false) {
-        try {
-            await buildContext.onBuildOutcome?.(outcome);
-        }
-        catch (error) {
-            context.logger?.warn('Failed to store workflow build outcome on run context', {
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
-    }
-    try {
-        await buildContext.workflowTaskService?.reportBuildOutcome(outcome);
-    }
-    catch (error) {
-        context.logger?.warn('Failed to report workflow build outcome to workflow loop', {
-            workItemId: outcome.workItemId,
-            error: error instanceof Error ? error.message : String(error),
-        });
-    }
-    if (options.markPlannedTaskSucceeded === false)
-        return;
-    try {
-        await buildContext.plannedTaskService?.markSucceeded(buildContext.threadId, buildContext.taskId, {
-            result: outcome.summary,
-            outcome,
-        });
-    }
-    catch (error) {
-        context.logger?.warn('Failed to mark planned workflow build task succeeded', {
-            taskId: buildContext.taskId,
-            error: error instanceof Error ? error.message : String(error),
-        });
-    }
-}
-async function promoteMainWorkflow(context, workflowId) {
-    try {
-        await context.workflowService.clearAiTemporary(workflowId);
-    }
-    catch (error) {
-        context.logger?.warn(`Failed to clear AI-builder temporary marker on main workflow ${workflowId}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
 function createBuildWorkflowTool(context) {
-    let lastCode = null;
-    let lastCodeVersionId = null;
     const failureTracker = new build_failure_tracker_1.BuildFailureTracker();
     return new agents_1.Tool('build-workflow')
-        .description('Build a workflow from TypeScript SDK code. Two modes:\n' +
-        '1. Full code: pass `code` to create/update a workflow from scratch.\n' +
-        '2. Patch mode: pass `patches` (+ optional `workflowId`) to apply str_replace fixes. ' +
-        'Patches apply to last submitted code, or auto-fetch from saved workflow if workflowId given.')
+        .description('Build and save a workflow from a workspace source file. ' +
+        'Use TypeScript SDK source for new workflows, or WorkflowJSON .json source for existing workflow edits. ' +
+        'Write or edit the file with workspace file tools, then pass its filePath here.')
         .input(exports.buildWorkflowInputSchema)
         .output(zod_1.z.object({
         success: zod_1.z.boolean(),
+        filePath: zod_1.z.string(),
+        sourceHash: zod_1.z.string().optional(),
         workflowId: zod_1.z.string().optional(),
         workflowName: zod_1.z.string().optional(),
         workItemId: zod_1.z.string().optional(),
@@ -264,53 +116,189 @@ function createBuildWorkflowTool(context) {
         mockedNodeNames: zod_1.z.array(zod_1.z.string()).optional(),
         mockedCredentialTypes: zod_1.z.array(zod_1.z.string()).optional(),
         mockedCredentialsByNode: zod_1.z.record(zod_1.z.array(zod_1.z.string())).optional(),
-        verificationPinData: zod_1.z.record(zod_1.z.array(zod_1.z.record(zod_1.z.unknown()))).optional(),
-        usesWorkflowPinDataForVerification: zod_1.z.boolean().optional(),
         referencedWorkflowIds: zod_1.z.array(zod_1.z.string()).optional(),
         hasUnresolvedPlaceholders: zod_1.z.boolean().optional(),
         denied: zod_1.z.boolean().optional(),
         reason: zod_1.z.string().optional(),
+        remediation: workflow_loop_state_1.remediationMetadataSchema.optional(),
         errors: zod_1.z.array(zod_1.z.string()).optional(),
         warnings: zod_1.z.array(zod_1.z.string()).optional(),
     }))
         .suspend(confirmationSuspendSchema)
         .resume(confirmationResumeSchema)
         .handler(async (input, ctx) => {
-        const permKey = input.workflowId ? 'updateWorkflow' : 'createWorkflow';
+        const filePath = (0, workflow_file_bindings_1.normalizeWorkflowSourceFilePath)(input.filePath);
+        let binding = (await (0, workflow_file_bindings_1.getWorkflowSourceFileBinding)(context, filePath)) ?? { filePath };
+        if (input.workflowId && binding.workflowId && input.workflowId !== binding.workflowId) {
+            const remediation = (0, remediation_1.createRemediation)({
+                category: 'blocked',
+                shouldEdit: false,
+                reason: 'source_file_workflow_mismatch',
+                guidance: 'This source file is already bound to a different workflow. Use the bound workflow or start from a different filePath.',
+            });
+            (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                result: 'blocked',
+                stage: 'permission',
+                binding,
+                targetWorkflowId: binding.workflowId,
+                remediation,
+                errorCount: 1,
+            });
+            return {
+                success: false,
+                ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                workflowId: binding.workflowId,
+                errors: [
+                    `Source file ${filePath} is already bound to workflow ${binding.workflowId}; cannot bind it to ${input.workflowId}.`,
+                ],
+                remediation,
+            };
+        }
+        if (input.workflowId && !binding.workflowId) {
+            binding = await (0, workflow_file_bindings_1.saveWorkflowSourceFileBinding)(context, {
+                ...binding,
+                workflowId: input.workflowId,
+            });
+        }
+        const targetWorkflowId = binding.workflowId;
+        const permKey = targetWorkflowId ? 'updateWorkflow' : 'createWorkflow';
         if (context.permissions?.[permKey] === 'blocked') {
-            return { success: false, errors: ['Action blocked by admin'] };
+            const remediation = (0, remediation_1.createRemediation)({
+                category: 'blocked',
+                shouldEdit: false,
+                reason: 'permission_blocked',
+                guidance: 'The requested workflow save action is blocked by admin policy.',
+            });
+            (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                result: 'blocked',
+                stage: 'permission',
+                binding,
+                targetWorkflowId,
+                isSupportingWorkflow: input.isSupportingWorkflow,
+                remediation,
+                errorCount: 1,
+            });
+            return {
+                success: false,
+                ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                workflowId: targetWorkflowId,
+                errors: ['Action blocked by admin'],
+                remediation,
+            };
         }
-        if (input.workflowId &&
-            !isApprovedBuildContext(context) &&
+        if (targetWorkflowId &&
+            !(0, workflow_build_context_1.isApprovedBuildContext)(context) &&
             context.permissions?.updateWorkflow !== 'always_allow') {
             if (ctx.resumeData && !ctx.resumeData.approved) {
+                const remediation = (0, remediation_1.createRemediation)({
+                    category: 'blocked',
+                    shouldEdit: false,
+                    reason: 'user_denied',
+                    guidance: 'The user denied permission to edit this workflow.',
+                });
+                (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                    result: 'denied',
+                    stage: 'hitl',
+                    binding,
+                    targetWorkflowId,
+                    isSupportingWorkflow: input.isSupportingWorkflow,
+                    remediation,
+                    errorCount: 1,
+                });
                 return {
                     success: false,
+                    ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                    workflowId: targetWorkflowId,
                     denied: true,
                     reason: 'User denied the action',
                     errors: ['User denied the action'],
+                    remediation,
                 };
             }
             if (!ctx.resumeData) {
                 if (!ctx.suspend) {
-                    return { success: false, errors: ['Workflow edit approval is required.'] };
+                    const remediation = (0, remediation_1.createRemediation)({
+                        category: 'blocked',
+                        shouldEdit: false,
+                        reason: 'approval_required',
+                        guidance: 'Workflow edit approval is required before saving this source file.',
+                    });
+                    (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                        result: 'blocked',
+                        stage: 'hitl',
+                        binding,
+                        targetWorkflowId,
+                        isSupportingWorkflow: input.isSupportingWorkflow,
+                        remediation,
+                        errorCount: 1,
+                    });
+                    return {
+                        success: false,
+                        ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                        workflowId: targetWorkflowId,
+                        errors: ['Workflow edit approval is required.'],
+                        remediation,
+                    };
                 }
-                const workflowName = await resolveWorkflowName(context, input.workflowId);
+                const workflowName = await (0, workflow_build_context_1.resolveWorkflowName)(context, targetWorkflowId);
+                (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                    result: 'suspended',
+                    stage: 'hitl',
+                    binding,
+                    targetWorkflowId,
+                    isSupportingWorkflow: input.isSupportingWorkflow,
+                });
                 return await ctx.suspend({
                     requestId: (0, nanoid_1.nanoid)(),
-                    message: `Edit ${workflowName} (ID: ${input.workflowId})?`,
+                    message: `Edit ${workflowName} (ID: ${targetWorkflowId})?`,
                     severity: 'warning',
                 });
             }
         }
-        const { code, patches, workflowId, projectId, name, workItemId } = input;
+        let sourceCode;
+        let sourceHash;
+        try {
+            ({ source: sourceCode, sourceHash } = await (0, workflow_file_bindings_1.readWorkflowSourceFile)(context, filePath));
+        }
+        catch (error) {
+            const remediation = (0, workflow_build_remediation_1.createCodeFixableRemediation)({
+                reason: 'workflow_source_read_failed',
+                guidance: 'The workflow source file could not be read. Recreate or edit the returned filePath, then call build-workflow again with the same filePath.',
+            });
+            (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                result: 'failure',
+                stage: 'source_read',
+                binding,
+                targetWorkflowId,
+                isSupportingWorkflow: input.isSupportingWorkflow,
+                remediation,
+                errorCount: 1,
+            });
+            return {
+                success: false,
+                ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                workflowId: targetWorkflowId,
+                errors: [error instanceof Error ? error.message : String(error)],
+                remediation,
+            };
+        }
+        if (sourceHash !== binding.sourceHash) {
+            binding = await (0, workflow_file_bindings_1.saveWorkflowSourceFileBinding)(context, { ...binding, sourceHash });
+        }
+        const { projectId, name } = input;
         const isSupportingWorkflow = input.isSupportingWorkflow === true;
         const buildContext = context.workflowBuildContext;
-        const isAuxiliarySupportingWorkflow = isSupportingWorkflow && buildContext?.isSupportingWorkflowTask !== true;
-        const workItemKey = getBuildFailureTrackingKey({
-            workItemId,
-            workflowId,
+        const { isAuxiliarySupportingWorkflow, plannedTaskId, owner, resolvedWorkItemId, resolvedTaskId, } = (0, workflow_build_context_1.resolveBuildIdentifiers)({
+            context,
+            filePath,
+            inputWorkItemId: input.workItemId,
+            isSupportingWorkflow,
+        });
+        const workItemKey = (0, workflow_build_context_1.getBuildFailureTrackingKey)({
+            workItemId: resolvedWorkItemId,
+            workflowId: targetWorkflowId,
             workflowName: name,
+            filePath,
             isAuxiliarySupportingWorkflow,
             buildContext,
             runId: context.runId,
@@ -319,101 +307,139 @@ function createBuildWorkflowTool(context) {
             const escalation = failureTracker.record(workItemKey, errors, options);
             return escalation ? [...errors, escalation] : errors;
         };
-        let finalCode;
-        if (patches) {
-            if (lastCode && lastCodeVersionId && workflowId) {
-                try {
-                    const head = await context.workflowService.getWorkflowHead(workflowId);
-                    if (head.versionId !== lastCodeVersionId) {
-                        lastCode = null;
-                        lastCodeVersionId = null;
-                    }
-                }
-                catch {
-                }
-            }
-            let baseCode = lastCode;
-            if (!baseCode && workflowId) {
-                try {
-                    const snapshot = await context.workflowService.getWorkflowSnapshot(workflowId);
-                    baseCode = (0, workflow_sdk_1.generateWorkflowCode)(snapshot.json);
-                    lastCode = baseCode;
-                    lastCodeVersionId = snapshot.versionId;
-                }
-                catch {
-                    return {
-                        success: false,
-                        errors: [
-                            'Patch mode: no previous code and could not fetch workflow. Send full code instead.',
-                        ],
-                    };
-                }
-            }
-            if (!baseCode) {
-                return {
-                    success: false,
-                    errors: [
-                        'Patch mode requires either a previous build-workflow call or a workflowId to fetch from.',
-                    ],
-                };
-            }
-            const patchResult = (0, patch_code_1.applyPatches)(baseCode, patches);
-            if (!patchResult.success) {
-                return { success: false, errors: [patchResult.error] };
-            }
-            finalCode = patchResult.code;
-        }
-        else if (code) {
-            finalCode = (0, extract_code_1.extractWorkflowCode)(code);
-        }
-        else {
-            return {
-                success: false,
-                errors: ['Either `code` (full code) or `patches` (to fix previous code) is required.'],
-            };
-        }
-        lastCode = finalCode;
-        let result;
-        try {
-            result = (0, workflow_builder_1.parseAndValidate)(finalCode, {
-                nodeTypesProvider: context.nodeTypesProvider,
+        let informational = [];
+        const compiled = await (0, workflow_source_compiler_1.compileWorkflowSource)(context, filePath, sourceCode);
+        if (!compiled.success) {
+            const errors = compiled.editable ? withEscalation(compiled.errors) : compiled.errors;
+            const remediation = (0, workflow_build_remediation_1.createSourceCompileRemediation)({
+                reason: compiled.reason,
+                editable: compiled.editable,
+            });
+            binding = await (0, workflow_build_context_1.markSourceBuildFailed)(context, binding, sourceHash);
+            await (0, workflow_build_reporting_1.reportFailedWorkflowBuildOutcome)(context, {
+                targetWorkflowId,
+                sourceFilePath: filePath,
+                workItemId: resolvedWorkItemId,
+                taskId: resolvedTaskId,
+                plannedTaskId,
+                owner,
+                remediation,
+                errors,
+                summary: compiled.summary,
+                storeOnRunContext: !isAuxiliarySupportingWorkflow,
+            });
+            (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                result: remediation.category === 'blocked' ? 'blocked' : 'failure',
+                stage: 'parse',
+                binding,
+                targetWorkflowId,
+                isSupportingWorkflow,
+                isAuxiliarySupportingWorkflow,
+                remediation,
+                errorCount: errors.length,
             });
-        }
-        catch (error) {
             return {
                 success: false,
-                errors: withEscalation([error instanceof Error ? error.message : 'Failed to parse workflow code'], {
-                    includeSdkLanguageGuidance: true,
-                }),
+                ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                workflowId: targetWorkflowId,
+                workItemId: resolvedWorkItemId,
+                errors,
+                remediation,
             };
         }
-        const { errors, informational } = (0, workflow_builder_1.partitionWarnings)(result.warnings);
-        if (errors.length > 0) {
+        const partitionedWarnings = (0, workflow_validation_warnings_1.partitionWarnings)(compiled.warnings);
+        informational = partitionedWarnings.informational;
+        if (partitionedWarnings.errors.length > 0) {
+            const formattedErrors = withEscalation(partitionedWarnings.errors.map((e) => `[${e.code}]${e.nodeName ? ` (${e.nodeName})` : ''}: ${e.message}`));
+            const remediation = (0, workflow_build_remediation_1.createCodeFixableRemediation)({
+                reason: 'workflow_source_validation_failed',
+                guidance: 'Edit the workspace source file using the validation diagnostics, then call build-workflow again with the same filePath.',
+            });
+            binding = await (0, workflow_build_context_1.markSourceBuildFailed)(context, binding, sourceHash);
+            await (0, workflow_build_reporting_1.reportFailedWorkflowBuildOutcome)(context, {
+                targetWorkflowId,
+                sourceFilePath: filePath,
+                workItemId: resolvedWorkItemId,
+                taskId: resolvedTaskId,
+                plannedTaskId,
+                owner,
+                remediation,
+                errors: formattedErrors,
+                summary: 'Workflow source failed validation.',
+                storeOnRunContext: !isAuxiliarySupportingWorkflow,
+            });
+            (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                result: 'failure',
+                stage: 'validation',
+                binding,
+                targetWorkflowId,
+                isSupportingWorkflow,
+                isAuxiliarySupportingWorkflow,
+                remediation,
+                errorCount: formattedErrors.length,
+                warningCount: informational.length,
+            });
             return {
                 success: false,
-                errors: withEscalation(errors.map((e) => `[${e.code}]${e.nodeName ? ` (${e.nodeName})` : ''}: ${e.message}`)),
-                warnings: informational.length > 0
-                    ? informational.map((w) => `[${w.code}]: ${w.message}`)
-                    : undefined,
+                ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                workflowId: targetWorkflowId,
+                workItemId: resolvedWorkItemId,
+                errors: formattedErrors,
+                remediation,
+                warnings: (0, workflow_build_context_1.combineWarnings)(informational.map((w) => (0, workflow_build_context_1.formatWarning)(w.code, w.message))),
             };
         }
-        const json = result.workflow;
+        const json = compiled.workflow;
         if (name) {
             json.name = name;
         }
-        else if (!json.name && !workflowId) {
+        else if (!json.name && !targetWorkflowId) {
+            const remediation = (0, workflow_build_remediation_1.createCodeFixableRemediation)({
+                reason: 'workflow_name_missing',
+                guidance: 'Add a workflow name in the workspace source file or pass the name parameter, then call build-workflow again with the same filePath.',
+            });
+            binding = await (0, workflow_build_context_1.markSourceBuildFailed)(context, binding, sourceHash);
+            await (0, workflow_build_reporting_1.reportFailedWorkflowBuildOutcome)(context, {
+                targetWorkflowId,
+                sourceFilePath: filePath,
+                workItemId: resolvedWorkItemId,
+                taskId: resolvedTaskId,
+                plannedTaskId,
+                owner,
+                remediation,
+                errors: [
+                    'Workflow name is required for new workflows. Provide a name parameter or set it in the SDK code.',
+                ],
+                summary: 'Workflow source is missing a workflow name.',
+                storeOnRunContext: !isAuxiliarySupportingWorkflow,
+            });
+            (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                result: 'failure',
+                stage: 'name',
+                binding,
+                targetWorkflowId,
+                isSupportingWorkflow,
+                isAuxiliarySupportingWorkflow,
+                remediation,
+                errorCount: 1,
+            });
             return {
                 success: false,
+                ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                workflowId: targetWorkflowId,
+                workItemId: resolvedWorkItemId,
                 errors: [
                     'Workflow name is required for new workflows. Provide a name parameter or set it in the SDK code.',
                 ],
+                remediation,
             };
         }
         const credentialMap = await (0, resolve_credentials_1.buildCredentialMap)(context.credentialService);
-        const mockResult = await (0, resolve_credentials_1.resolveCredentials)(json, workflowId, context, credentialMap);
+        const mockResult = await (0, resolve_credentials_1.resolveCredentials)(json, targetWorkflowId, context, credentialMap);
         await (0, setup_workflow_service_1.stripStaleCredentialsFromWorkflow)(context, json);
-        await (0, submit_workflow_tool_1.ensureWebhookIds)(json, workflowId, context);
         try {
+            await (0, workflow_json_utils_1.ensureWebhookIds)(json, targetWorkflowId, context);
+            await (0, workflow_json_utils_1.preserveExistingNodeGroupIds)(json, targetWorkflowId, context);
             const hasMockedCredentialNodes = mockResult.mockedNodeNames.length > 0;
             const referencedWorkflowIds = (0, workflow_json_utils_1.getReferencedWorkflowIds)(json);
             const triggerNodes = (json.nodes ?? [])
@@ -421,23 +447,16 @@ function createBuildWorkflowTool(context) {
                 .map((n) => ({ nodeName: n.name, nodeType: n.type }))
                 .filter((t) => Boolean(t.nodeName) && Boolean(t.nodeType));
             const hasPlaceholders = (json.nodes ?? []).some((n) => (0, utils_1.hasPlaceholderDeep)(n.parameters));
-            const plannedTaskId = buildContext?.plannedTaskService && !isAuxiliarySupportingWorkflow
-                ? buildContext.taskId
-                : undefined;
-            const owner = plannedTaskId
-                ? { type: 'planned', taskId: plannedTaskId }
-                : { type: 'direct' };
-            const resolvedWorkItemId = workItemId ??
-                (isAuxiliarySupportingWorkflow ? undefined : buildContext?.workItemId) ??
-                `wi_${(0, nanoid_1.nanoid)(8)}`;
-            const resolvedTaskId = isAuxiliarySupportingWorkflow
-                ? `${buildContext?.taskId ?? (context.runId ? `build-${context.runId}` : 'build')}:supporting-${(0, nanoid_1.nanoid)(6)}`
-                : (buildContext?.taskId ??
-                    (context.runId ? `build-${context.runId}` : `build-${(0, nanoid_1.nanoid)(8)}`));
-            const createSuccessResponse = async (savedId) => {
+            const createSuccessResponse = async (saved, operation) => {
+                const { nodeSimulationPlan, simulationFixtures } = await (0, plan_verification_simulation_1.planVerificationSimulation)({
+                    workflow: json,
+                    mockedNodeNames: mockResult.mockedNodeNames,
+                    workflowId: saved.id,
+                    logger: context.logger,
+                });
                 const runId = buildContext?.runId ?? context.runId;
                 const workflowName = json.name || 'workflow';
-                const summary = `${workflowId ? 'Updated' : 'Created'} ${isSupportingWorkflow ? 'supporting ' : ''}workflow "${workflowName}" (${savedId}).`;
+                const summary = `${operation === 'update' ? 'Updated' : 'Created'} ${isSupportingWorkflow ? 'supporting ' : ''}workflow "${workflowName}" (${saved.id}).`;
                 const placeholderRemediation = hasPlaceholders
                     ? (0, remediation_1.createRemediation)({
                         category: 'needs_setup',
@@ -446,13 +465,20 @@ function createBuildWorkflowTool(context) {
                         guidance: 'Workflow submitted successfully, but unresolved setup values remain. Stop code edits and route to workflows(action="setup").',
                     })
                     : undefined;
-                const outcome = withDeterministicRouting({
+                binding = await (0, workflow_file_bindings_1.saveWorkflowSourceFileBinding)(context, {
+                    ...binding,
+                    workflowId: saved.id,
+                    workflowVersionId: saved.versionId,
+                    sourceHash,
+                });
+                const outcome = (0, workflow_build_routing_1.withDeterministicRouting)({
                     workItemId: resolvedWorkItemId,
                     ...(runId ? { runId } : {}),
                     taskId: resolvedTaskId,
                     owner,
                     plannedTaskId,
-                    workflowId: savedId,
+                    workflowId: saved.id,
+                    sourceFilePath: filePath,
                     submitted: true,
                     triggerType: 'manual_or_testable',
                     triggerNodes,
@@ -465,24 +491,35 @@ function createBuildWorkflowTool(context) {
                     mockedCredentialsByNode: hasMockedCredentialNodes
                         ? mockResult.mockedCredentialsByNode
                         : undefined,
-                    verificationPinData: hasMockedCredentialNodes && Object.keys(mockResult.verificationPinData).length > 0
-                        ? mockResult.verificationPinData
-                        : undefined,
-                    usesWorkflowPinDataForVerification: mockResult.usesWorkflowPinDataForVerification || undefined,
+                    nodeSimulationPlan,
+                    simulationFixtures,
                     supportingWorkflowIds: referencedWorkflowIds.length > 0 ? referencedWorkflowIds : undefined,
                     hasUnresolvedPlaceholders: hasPlaceholders || undefined,
                     remediation: placeholderRemediation,
                     summary,
                 });
-                await promoteMainWorkflow(context, savedId);
-                await reportWorkflowBuildOutcome(context, outcome, {
+                await (0, workflow_build_reporting_1.promoteMainWorkflow)(context, saved.id);
+                await (0, workflow_build_reporting_1.reportWorkflowBuildOutcome)(context, outcome, {
                     storeOnRunContext: !isAuxiliarySupportingWorkflow,
                     markPlannedTaskSucceeded: !isAuxiliarySupportingWorkflow,
                 });
                 failureTracker.clear(workItemKey);
+                (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                    result: 'success',
+                    stage: 'save',
+                    binding,
+                    targetWorkflowId,
+                    savedWorkflowId: saved.id,
+                    saveOperation: operation,
+                    isSupportingWorkflow,
+                    isAuxiliarySupportingWorkflow,
+                    remediation: placeholderRemediation,
+                    warningCount: informational.length,
+                });
                 return {
                     success: true,
-                    workflowId: savedId,
+                    ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                    workflowId: saved.id,
                     workflowName: json.name || undefined,
                     workItemId: resolvedWorkItemId,
                     isSupportingWorkflow: isSupportingWorkflow || undefined,
@@ -496,38 +533,57 @@ function createBuildWorkflowTool(context) {
                     mockedCredentialsByNode: hasMockedCredentialNodes
                         ? mockResult.mockedCredentialsByNode
                         : undefined,
-                    verificationPinData: hasMockedCredentialNodes && Object.keys(mockResult.verificationPinData).length > 0
-                        ? mockResult.verificationPinData
-                        : undefined,
-                    usesWorkflowPinDataForVerification: mockResult.usesWorkflowPinDataForVerification || undefined,
                     referencedWorkflowIds: referencedWorkflowIds.length > 0 ? referencedWorkflowIds : undefined,
                     hasUnresolvedPlaceholders: hasPlaceholders || undefined,
-                    warnings: informational.length > 0
-                        ? informational.map((w) => `[${w.code}]: ${w.message}`)
-                        : undefined,
+                    warnings: (0, workflow_build_context_1.combineWarnings)(informational.map((w) => (0, workflow_build_context_1.formatWarning)(w.code, w.message))),
                 };
             };
-            if (workflowId) {
-                const updated = await context.workflowService.updateFromWorkflowJSON(workflowId, json, projectId ? { projectId } : undefined);
-                lastCodeVersionId = updated.versionId;
-                return await createSuccessResponse(updated.id);
-            }
-            else {
-                const created = await context.workflowService.createFromWorkflowJSON(json, {
-                    ...(projectId ? { projectId } : {}),
-                    markAsAiTemporary: true,
-                });
-                (context.aiCreatedWorkflowIds ??= new Set()).add(created.id);
-                lastCodeVersionId = created.versionId;
-                return await createSuccessResponse(created.id);
+            if (targetWorkflowId) {
+                const updated = await context.workflowService.updateFromWorkflowJSON(targetWorkflowId, json, projectId ? { projectId } : undefined);
+                return await createSuccessResponse(updated, 'update');
             }
+            const created = await context.workflowService.createFromWorkflowJSON(json, {
+                ...(projectId ? { projectId } : {}),
+                markAsAiTemporary: true,
+            });
+            (context.aiCreatedWorkflowIds ??= new Set()).add(created.id);
+            return await createSuccessResponse(created, 'create');
         }
         catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            const remediation = (0, workflow_build_remediation_1.createSaveFailureRemediation)(error, Boolean(binding.workflowId));
+            binding = await (0, workflow_build_context_1.markSourceBuildFailed)(context, binding, sourceHash);
+            await (0, workflow_build_reporting_1.reportFailedWorkflowBuildOutcome)(context, {
+                targetWorkflowId,
+                sourceFilePath: filePath,
+                workItemId: resolvedWorkItemId,
+                taskId: resolvedTaskId,
+                plannedTaskId,
+                owner,
+                remediation,
+                errors: [`Workflow save failed: ${message}`],
+                summary: 'Workflow source parsed but did not save.',
+                storeOnRunContext: !isAuxiliarySupportingWorkflow,
+            });
+            (0, workflow_build_telemetry_1.trackWorkflowSourceBuild)(context, {
+                result: remediation.category === 'blocked' ? 'blocked' : 'failure',
+                stage: 'save',
+                binding,
+                targetWorkflowId,
+                saveOperation: targetWorkflowId ? 'update' : 'create',
+                isSupportingWorkflow,
+                isAuxiliarySupportingWorkflow,
+                remediation,
+                errorCount: 1,
+            });
             return {
                 success: false,
-                errors: [
-                    `Workflow save failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                ],
+                ...(0, workflow_build_context_1.sourceResponseBase)(binding),
+                workflowId: targetWorkflowId,
+                workflowName: json.name || undefined,
+                workItemId: resolvedWorkItemId,
+                errors: [`Workflow save failed: ${message}`],
+                remediation,
             };
         }
     })