What the agent does
The error appears the moment a project on uuid 3 moves to a current release. const uuidv4 = require('uuid/v4') was the documented way to import in version 3. Version 7 kept it working and printed a warning when the function was called ("Deep requiring like const uuidv4 = require('uuid/v4'); is deprecated as of uuid@7.x"), and version 8 added an exports map to its package.json that lists no ./v4 path, so Node refuses the import with Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './v4' is not defined by "exports". The agent starts with the manifest and the lockfile. In a library like ruidfigueiredo/electron-cgi, package.json declares "uuid": "^3.3.2" as its only runtime dependency, package-lock.json holds 3.3.2, and npm ci prints npm's notice that uuid 10 and below is no longer supported.
It finds the imports next. Here there is one, the first line of request.js, where the Request constructor gives each message an id with this.id = uuidv4(). connection.js requires request.js, and index.js reaches it through connection-builder.js, so a failure in that one line stops the whole package from loading. The agent upgrades the dependency in the sandbox and runs node -e "require('./index.js')" to capture the error and its stack.
Then it runs the test suite, and notes the result carefully: npm test runs jasmine, and all 7 specs pass with the package unable to load. The only spec file, spec/input-stream-parser.spec.js, requires tab-separated-input-stream-parser.js and nothing else, so no test ever touches request.js. A green check on a pull request that bumps uuid would be reporting on a different file. The agent adds a spec that requires index.js, constructs a Request, and checks that its id is a version 4 UUID, and shows that spec failing before the code change.
The code fix is const { v4: uuidv4 } = require('uuid'). Which version to depend on needs more thought. The newest uuid releases are ES modules only, with "type": "module" in their package.json. Loading one with require works on recent Node releases that can require ES modules and fails on older ones, and this package declares no engines field while its users run it inside Electron, whose bundled Node varies by release. uuid 11 still ships a CommonJS build beside the ES module one, and npm's own deprecation notice points CommonJS code at it. The agent sets the range to ^11, runs the new spec, and reports the alternative it did not take: crypto.randomUUID() is built into Node and would remove the dependency altogether, at the cost of a minimum Node version the maintainer has to choose.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade the uuid package in this repository off version 3 and fix the deep imports that break. Read package.json and the lockfile and say which uuid version is installed, which range is declared, and whether uuid is a direct dependency or only arrives through another package. Find every require or import of a uuid subpath (uuid/v1, uuid/v3, uuid/v4, uuid/v5) and every default import of uuid. Install the newest uuid in the sandbox, load the package's entry point with node, and quote the error. Run the existing tests before and after the upgrade and say plainly whether any test loads the files that import uuid; if none does, add one that loads the entry point and checks a generated id, and show it failing before the fix. Replace each deep import with the named export from the top-level module. Choose the uuid major from the facts: whether this code is CommonJS or ES modules, the engines field, the Node versions in CI, and whether it runs under Electron or a bundler. If the newest uuid cannot be loaded by every supported runtime, use the newest major that can and say why. Mention crypto.randomUUID as an alternative only in the description; do not switch to it. Update the lockfile with the package manager the repository uses. Open a pull request with the error before, the test results before and after, and the reason for the chosen version.",
"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 with four files: request.js with the named import, package.json with the new uuid range, the regenerated package-lock.json, and one new spec under spec/. The description quotes the ERR_PACKAGE_PATH_NOT_EXPORTED error, and it states the test finding in a sentence a reviewer cannot miss: the existing suite passed while the package could not be loaded.
The version choice is laid out as a short argument the reviewer can disagree with. It names the module format of the repository, the absence of an engines field, and what each candidate major ships. If your project is already ES modules or pins a recent Node, the same reasoning lands on the newest uuid instead, and the description says which fact decided it.
Before merging, check two things the agent cannot know. One is the oldest Node or Electron version your users run, since that decides whether a CommonJS build is still needed. The other is any other package in your tree that pulls in its own old uuid: the agent lists them from the lockfile, and they are fixed upstream, not here.
Run it on every Monday morning
Old uuid imports hide in many small services and libraries, and the upgrade is the same in each. Create an automation in the Project for each repository with this prompt and a schedule trigger, for example a cron of 0 8 * * 1. A run that finds no deep imports left and a current uuid range says so and opens nothing.
To sweep an organisation once, list the repositories that contain require('uuid/ and start one run for each through the API with the body above, changing only the resources URL. A run past the key's max_concurrent limit is created queued and starts when a slot frees, so the script needs no retry loop.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
This is an upgrade where the usual safety net lies. A version bump that turns CI green looks finished, and here the tests are green because they never import the file that broke. Finding that out means loading the real entry point on a clean install, which the agent does as its first step in a sandbox that has nothing cached from an older install.
The second reason is the version decision. Reading what a uuid major actually ships, CommonJS, ES modules or both, means installing it and looking at its package.json. The agent installs the candidates one after another, loads the package under each, and keeps the commands and their output. The pull request's argument for the chosen range rests on that output.
Frequently asked questions
What is the replacement for require('uuid/v4')?
const { v4: uuidv4 } = require('uuid') in CommonJS, or import { v4 as uuidv4 } from 'uuid' in an ES module. The function is the same. The other versions follow the same pattern with v1, v3 and v5.
Why not stay on uuid 3?
It still works, and npm marks it as unsupported on every install. Staying also blocks any other dependency that needs a newer uuid from sharing one copy. The import change is a line per file, so there is little reason to wait.
Can I just use crypto.randomUUID() and drop the package?
For version 4 ids on a current Node, yes. It is built in and needs no dependency. It does not produce v1, v3 or v5 ids, and browsers only offer it in secure contexts. The agent describes that option in the pull request and leaves the choice to you.
Does the agent fix deep imports inside node_modules?
No. If a dependency of yours still calls require('uuid/v4'), it resolves its own nested copy of uuid 3 and keeps working. The agent lists those packages from the lockfile so you can see them, and changes only your code.
More jobs like this: Upgrade dependencies weekly
- Fix Vulnerable Go Modules in an Echo API (Echo)
- Fix Vulnerable Dependencies in a NestJS App (NestJS)
- Fix Vulnerable Dependencies in a Node.js App (Node.js)
- Fix Vulnerable Dependencies in a React App (React)
- Fix Vulnerable Dependencies in a Rust Project (Rust)
- Replace appdirs With platformdirs in a Python Package (appdirs)