DEV Community

Cover image for Coding Agents Keep Installing the Old Version of Your Library
Valentina Koniukhova
Valentina Koniukhova

Posted on AI-assisted

Coding Agents Keep Installing the Old Version of Your Library

I work on helping coding agents write better code, and one question keeps coming back. Libraries change fast: a new major, a renamed package, an API that is gone. Do agents move to the new version as willingly as a developer who reads the release notes, and do they use it as well? If you maintain a library that changed this year, the answer decides what code your users get when they ask an agent for it.

To find out, I took 20 libraries that changed in 2026, most with a new major, a rename or a removed API, and for two weeks gave Claude Code, Codex and Gemini the jobs their users would give them: add "the current" SDK to a small project, upgrade an app to the new major, write code against an API that changed. Each agent did every task several times. A hidden grader checked the code, and a log recorded everything the agent opened.

That came to 34 checks and 433 graded runs. Often the agents did not move. In 31 of the 34 checks they got something wrong in a way the library could fix. Usually the code ran fine on the old version, and the agent told the user it was current.

Asked for "the current version", agents ended on it in 32 of 66 runs

These are the 11 libraries where an agent could install the wrong version: the old package was still latest, the user used the old name, or the old API was still in the package. For the other 9, the new version was what npm or PyPI installed anyway, so the test was the code written against it. Runs on the current version, out of 6 per library: Claude Code, Codex and Gemini, 2 runs each, nothing pointing to the docs.

Runs on the current version, out of 6: Video.js 6, docx-editor 6, CopilotKit 4, Charm 4, Moss 3, OpenCode 3, Prisma 2, Camunda 2, Context.dev 2, Hedera 0, LadybugDB 0

Below is what happened, in the order an agent meets your library: npm first, then the files on disk, then the docs. The changes that moved the numbers are collected in a checklist at the end.

The test

Each check is one task, worded the way a user would ask, with nothing in the prompt that points to the docs. The task never names the version: "the current version from npm", "upgrade to the current Video.js". Each agent gets a fresh project, web access, full shell and 25 minutes. A script grades the result: which package and version ended up in the code, whether it builds and works against a real or fake server, and whether the agent told the user what it did. A second pass reads the log for what the agent opened: npm, the README, type files, docs pages, llms.txt, skills, MCP tools.

Most checks ran each task twice on each of the three agents, 6 runs per check. Where I tested a fix, I reran the same task with one change switched on: a deprecation through a local registry that behaves like npm, a patched README, a few lines in AGENTS.md. Three experiments compare docs channels with 45 runs each. Small samples like these show big effects only; I say so where it matters.

Where agents decide

Before any docs, an agent asked for "the current version" goes to the package registry. It runs npm view or just npm install, and it sees latest, the README and a deprecation notice if there is one. Most of the wrong choices were made right there, in the first minute.

After that it reads what is on disk: type definitions, the README and docs inside node_modules, error messages from the compiler, the CLI or your server. The docs site comes last, and many runs never got there. llms.txt was opened in 0 of 59 runs where nothing pointed to it.

1. Make latest mean the latest

Prisma 8's CLI was already latest on npm as a release candidate, but @prisma/client@latest still pointed to 7.10.1. Three of six runs chose Prisma 7 on purpose: they saw the CLI and the client on different majors and applied an old, correct rule that the two must match. Only 2 of 6 ended on Prisma 8.

OpenCode's v2 server came with a new SDK, but the old @opencode-ai/sdk was still latest on npm. Three of six runs started on the old one, and its calls to the v2 server got back an HTML page with status 200 instead of an error.

The counterexample is Effect. Its v4 went out under the same name with latest pointing at it, so an agent that installed the obvious package got the new version and the docs that ship with it.

When the new major is the one you want people on, move latest to it. If a companion package can't move yet, say so in its README's first line.

2. Deprecate the old package, then ship one last release that says where to go

Hedera moved its JavaScript SDK to @hiero-ledger/sdk, but the old @hashgraph/sdk was still latest, not deprecated, and its README didn't mention the move (issue). All 6 runs built a correct signed transfer on the old package. None opened the agent skill Hedera had published for exactly this.

I simulated the fix with a local registry that serves the old package as deprecated, exactly as npm would. The same task went from 0 of 6 to 3 of 6 on the new package. The logs show why only half switched. npm view old-pkg prints DEPRECATED at the top, and the runs that used it switched. npm view old-pkg version prints only the number, and npm install prints the warning after the choice is made. One run cut the warning off with | tail -5.

Moss had the same shape after renaming its scope: 3 of 6 on the new @moss-js/moss. A simulated npm deprecate brought it to 4 of 6. Deprecation plus one last release of the old package, whose README opens with "moved, same API, install @moss-js/moss", brought it to 6 of 6. That fix takes about ten minutes. If you want to know whether your own package has this problem, there's a 2-minute read-only check your agent can run.

Runs that installed the new package, out of 6: Hedera 0 as published and 3 with npm deprecate; Moss 3 as published, 4 with deprecate, 6 with deprecate and a last release saying moved

npm deprecate the old package with the new name in the message, then publish a final patch release of it whose README's first line says where it moved.

3. After a rename, agents use the name the user typed

When the user says the old name, agents follow the user. Context.dev used to be Brand.dev. With "Brand.dev" in the prompt, 4 of 6 runs installed the frozen brand.dev package. With "Context.dev", 6 of 6 used the new SDK.

LadybugDB is the maintained fork of Kùzu, which was archived. Asked to use Kùzu, 6 of 6 runs stayed on the archived kuzu package. A fix in LadybugDB's agent skill got 5 of 6 runs to tell the user Kùzu is archived, though 5 of 6 still installed it. LadybugDB merged that change.

The libraries that kept their name had it easier. Video.js 10 ships as new @videojs/* packages, but the old video.js package now contains a redirect that tells you where the player went. All 6 runs asking for "Video.js, current version" ended on v10 (results).

Keep the package name if you can. If you can't, make the old name lead to the new one everywhere a user's word can land: the old package, its README, your skill, your docs search.

4. Put deprecations where the agent reads them

A deprecation that lives only in JSDoc or on the website doesn't reach the agent that's writing code. Rivet 3.0 deprecated c.state in favor of a new API: 3 of 6 runs used c.state, and none told the user. CopilotKit's v1 API is deprecated in favor of v2: both Gemini runs used v1. Charm's Bubble Tea and Lip Gloss moved to v2 under a new module path: both Gemini runs used v1 and called it current.

Mark renamed and removed APIs @deprecated in the type files with the replacement's name. Keep removed names as stubs for a release so the compiler error points to the right thing, and log a warning at run time that names the replacement.

5. Make error messages name the fix

Kestra 2.0 removed ForEach (now Loop) and the json() function (now fromJson()), and an open issue asks for better errors for exactly these. Over 15 runs with no help, 6 wrote one of them. Each got an error that didn't name the replacement: Invalid type: io.kestra.plugin.core.flow.ForEach, or Function or Macro [json] does not exist. They found the answer by listing the server's plugins, and one run spent 25 minutes, part of it unzipping the server's jar. Claude and Gemini never opened Kestra's 2.0 docs at all, so for them the error message was the only 2.0 documentation they saw.

Mem0's upgrade from 1.x to 2.x removed graph memory from the open-source package. None of four runs told the user that it moved to Mem0's platform, and one Codex run wrote its own Neo4j layer to replace it.

Treat errors for removed things as docs. "ForEach was removed in 2.0, use io.kestra.plugin.core.flow.Loop" costs one line and reaches every agent that hits it.

6. Make the documented path work with nobody at the keyboard

Agents run your commands in a terminal nobody watches. Crash Override's CLI wanted an interactive terminal to produce a report (issue), so 6 of 6 runs had to write their own config file to get one. One Prisma run started init without --yes and waited on a prompt until time ran out.

Docs examples get copied word for word. E2B's docs showed install_cmd and run_cmd for a custom MCP server in a sandbox; all 4 runs that got that far wrote them, and the gateway ignores both. CrewAI's docs offer a prompt to paste into your agent for setup: step 6 failed in 6 of 6 runs (issue).

The default settings shaped results too. Asked to start Arize Phoenix 21 in Docker and send it traces, 6 of 6 runs turned authentication off to get it working, and none used an API key.

Show non-interactive flags in every command, make the CLI work without a terminal, run your docs examples in CI, and make the secure path the one that works on the first try.

7. Ship the docs inside the package

What's in node_modules always matches the installed version and is on disk when the agent hits an error. Video.js ships its full docs in @videojs/html, and the runs read them. Effect ships an AGENTS.md and runnable examples in its package, and every run read them or the source.

Put an upgrade note and the main guides in the tarball, with predictable names (UPGRADE.md, docs/, AGENTS.md).

8. Ten lines beat a docs MCP

Three libraries asked, in public, whether they should build a docs MCP or ship a skill. I ran the same task on each with one channel switched on at a time: nothing, a line pointing to the vendor's llms.txt, the vendor's skill, a docs MCP, and 5 to 13 lines from the vendor's own migration guide in the project's AGENTS.md. That's 9 runs per channel on each library, 135 in all.

The short brief was the only channel with a significant effect, and it was never worse than nothing:

  • Camunda 8.10, picking the current Node client: 4 of 9 with nothing, 9 of 9 with the brief (p = 0.03, results).
  • Video.js 10, upgrading a v8 app: everyone got there, but the brief cut tokens and tool calls by about a third (p ≤ 0.001).
  • Kestra 2.0: no channel made a significant difference. With the brief, the llms.txt pointer or the skill, all 9 first attempts used 2.0 constructs; with nothing or the docs MCP, 7 of 9 did.

One docs channel at a time, runs that got it right out of 9: Camunda 4, 4, 4, 6 and 9 with the brief; Video.js 8, 9, 7, 9, 9; Kestra 7, 9, 7, 7, 9

The others had specific limits. The docs MCP was called in only 16 of 27 runs, and Codex didn't call it in any of its 9: it had the tools listed and searched the web instead. Kestra's hosted MCP also advertises a login that Codex can't complete, so Codex hides its tools (how to check your own MCP server). Skills were read in 27 of 27 runs and gained nothing measurable; on Kestra the skill was the slowest channel. The llms.txt pointer was followed in 23 of 27 runs and helped exactly as much as the page it led to.

AGENTS.md lives in the user's project, so you can't add lines to it yourself. There are two ways to get them there: your CLI can write those lines during setup (@videojs/cli agents init and Camunda's c8ctl setup already write agent files), or your README can offer the block to copy.

Write the 5 to 15 lines an agent needs for your current version first: the package to install, what was removed, the new names. Ship them in the package and in your CLI's setup. Build an MCP after that, and check that each agent actually calls it.

When none of this applies: the models already know your version

If the models already know your new version, the traps above mostly don't fire. Expo's removed module was still latest and undeprecated, the same trap as Hedera, yet 12 of 12 runs used the replacement: it shipped in 2025, and the models had learned it. Ask the models with tools turned off:

claude -p "From memory, no tools: do you know <package> version <N>? Install command and a 10-line example, or say UNKNOWN." --tools ""
Enter fullscreen mode Exit fullscreen mode

If they answer UNKNOWN, your users' agents will decide from npm, from your errors and from what's on disk, and the sections above are the order to fix them in.

Check your library before the next release

Each line is one change from the sections above, in the order an agent meets your library. The first two are npm commands and take minutes.

  1. Point latest at the version you want people on.
  2. Deprecate a renamed package, and ship one last release whose README says where it moved.
  3. Make the old name lead to the new one everywhere a user might type it.
  4. Mark removed APIs @deprecated in the type files, with the replacement's name.
  5. Name the replacement in the error a removed thing throws.
  6. Make every documented command work with nobody at the keyboard.
  7. Ship an upgrade note and your guides inside the package.
  8. Write 5 to 15 lines for AGENTS.md before you build a docs MCP.

You don't have to go through this list by hand. Two ways to have it checked for your own package:

Limits

Two or three runs per agent per check: these are examples and big effects, not rates. One task per check, in my wording, on my machine. The fixes for Hedera and Moss are simulations through a local registry; the npm website still showed the old state, though no run opened it. Agents and models change every few weeks, so a check is a snapshot with a date.

The data

Every check here has its prompt, the per-run results, a short step-by-step view of what each agent did and the full logs. Each company has them in a private workspace on Ready for Agents, where they can also connect their own agent to read the results and ask the next question.

Top comments (0)