What the agent does
ReferenceError: primordials is not defined is what gulp 3 prints on Node 12 and every version since. The stack trace runs through natives and an old graceful-fs that gulp 3's vinyl-fs depends on, which tried to re-evaluate Node's internal fs source. No gulpfile change fixes it; the supported fix is a current gulp, and that means rewriting how tasks are composed. The agent begins by reproducing the error on the Node version in use. In a project like 720kb/radiobox.css, package.json has gulp at ^3.9.1 with gulp-sass at ^2.3.2 and run-sequence, no lockfile and no scripts. After npm install, npx gulp build on Node 22 fails at fs.js:44 with exactly this error.
It then reads the build. The six-line gulpfile.js only calls require('require-dir')('conf/tasks'), and the nine files in that folder each register one task. build.js chains seven of them with runSequence('clean', 'sass', 'autoprefixer', 'minify', 'banner', 'copy', 'finalize'). watcher.js calls gulp.watch(glob, ['build']). sass.js pipes through gulp-sass version 2, which wraps node-sass. The agent upgrades gulp and the plugins, passes a compiler to the new gulp-sass as require('gulp-sass')(require('sass')), and replaces run-sequence with gulp.series, which is built in.
The direct translation fails, and the reason is specific to this layout. gulp.task('build', gulp.series('clean', ...)) throws Error: Task never defined: clean, because gulp.series looks its task names up immediately and require-dir loads build.js before clean.js, in alphabetical order. gulp 3 with run-sequence resolved names when the task ran, so load order never mattered. The agent builds the series inside the task function so the lookup happens at run time, and applies the same change to the watcher, whose second argument must now be a function and no longer an array of names.
With that, gulp build runs all seven steps. The agent does not stop at a green run; it compares the output with the dist folder committed in the repository. The same 28 files are produced, and all fourteen minified stylesheets differ. One cause is harmless: the banner from conf/paths.js embeds today's date. The other is not cosmetic. The committed radiobox.min.css contains @-webkit-keyframes and -webkit-transform, and the new one has neither and is about a third of the size, because a current gulp-autoprefixer targets current browsers by default. The agent reports this with the byte counts and asks whether to add a browserslist entry that restores the old targets. It also notes the @import deprecation warnings Dart Sass now prints for the entry stylesheet.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This project's gulp build fails on current Node with \"ReferenceError: primordials is not defined\". Fix it by upgrading from gulp 3 to the current gulp release, not by pinning an old Node or overriding graceful-fs. First install dependencies and run the build on the current Node LTS to reproduce the error, and record the exact message and the gulp version. Read the gulpfile and every task file it loads, and list each task, what it depends on, and how tasks are sequenced (run-sequence, dependency arrays, gulp.start). Upgrade gulp and each plugin to a release that supports it; replace node-sass based plugins with ones that take the sass package. Rewrite dependency arrays, run-sequence and gulp.start as gulp.series and gulp.parallel, make every task signal completion (return its stream or call the callback), and update gulp.watch calls to the new signature. If tasks are registered across several files, make sure names are resolved in an order that works, and explain what you did. If any task copies images, fonts or other binary files, pass encoding: false to gulp.src so they are not corrupted. Run every task that does not need a browser or a deploy target. Then compare the build output with the previous output, using committed build files if there are any: list files added, missing and changed, and for changed files explain each cause (timestamps, vendor prefixes, minifier differences, Sass compiler differences). Do not commit regenerated build output unless it was already tracked. Add a lockfile if the project has none and say so. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that changes package.json, adds a lockfile, and edits the task files that compose other tasks. For radiobox.css that is build.js, watcher.js and sass.js; the six tasks that only pipe a stream through a plugin are untouched. The description shows the error before and the task log after, with each of the seven steps starting and finishing in order.
The output comparison is the part that needs a human decision. It lists the changed files and attributes each difference: the date in the banner, and the vendor prefixes that a newer autoprefixer no longer adds. A reviewer who still supports old browsers answers with a browser list and the agent regenerates; one who does not accepts the smaller files. Either way the choice is made knowingly and written down in the pull request.
The reviewer also checks the dependencies that were removed. run-sequence goes because gulp replaces it, and gulp-watch goes because watcher.js imported it and then called gulp.watch anyway.
Run it on every pull request labelled node-upgrade
This error usually appears the day someone raises the Node version in CI or in a Dockerfile, and the build of an older front-end package turns red. Add an automation to the repository's Project with a github trigger on pull_request.labeled, set its labels filter to node-upgrade, and save the prompt above. When a maintainer labels the pull request that raises Node, the run starts and the pull request event is placed after the saved prompt as event text. The agent opens its own pull request with the gulp upgrade, which you merge first.
The trigger fires only for labels applied by an owner, member or collaborator, and never for pull requests from forks. Use branch_patterns if only pull requests into your main branch should start it.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The common answers to this error are workarounds: run Node 10 through a version manager, or force a newer graceful-fs with an override and leave gulp 3 in place. Both keep an unmaintained build alive. Doing the upgrade properly is a loop of install, run, read the error, fix, run again, and then a file-by-file comparison of the output, which is exactly the sort of work that gets postponed. The agent does the loop in its own sandbox, on the Node version you actually deploy with, and the commands and output are kept in the session transcript.
The comparison is why the result can be trusted. A build that exits zero says nothing about whether the CSS it wrote is the CSS you shipped last time. Here it is not: the new file is a third of the size, and nothing in the task log says so. A pull request that puts that difference in front of the reviewer, with its cause, is worth more than one that only turns the build green.
Frequently asked questions
Why does gulp 3 fail on newer Node versions?
gulp 3 depends on an old graceful-fs that patched Node's file system module by evaluating its internal source. Node 12 changed those internals to use an object called primordials that exists only inside Node itself, so the evaluated copy fails. gulp 4 and later do not use that technique.
Can I fix it without upgrading gulp?
As a stopgap. An overrides entry in package.json (or resolutions with Yarn) that forces graceful-fs to a 4.x release lets gulp 3 start on some newer Node versions. It leaves you on a gulp that no longer receives fixes, with plugins that may fail for their own reasons, so treat it as a way to buy time.
What replaces run-sequence and task dependency arrays?
gulp.series for tasks that must run in order and gulp.parallel for tasks that can run together. gulp.task('name', ['dep'], fn) becomes gulp.task('name', gulp.series('dep', fn)). Every task must return its stream or a promise, or call its callback, or gulp reports that it did not complete.
Why do I get "Task never defined" after converting?
gulp.series and gulp.parallel resolve task names when they are called, not when the task runs. If the named task is registered later, in another file or further down the gulpfile, the lookup fails. Register tasks before composing them, or create the series inside a function so it is evaluated at run time.
Will the upgraded build produce the same files?
The same file names, usually. Contents can change because the plugins were upgraded along with gulp: a newer autoprefixer adds fewer vendor prefixes, Dart Sass formats output differently from node-sass, and minifiers make different choices. The agent compares old and new output and explains each difference so you can decide which to keep.