[Bug]: Plugin and provider loaders cache the same package under two keys and never refresh an existing install

[depler]

Summary

Opencode can keep loading an old version of a plugin/provider package even though npm reports the latest version as installed. Two things combine: the cache is keyed by the exact specifier string, and Npm.add returns an existing directory without checking whether it is still current.

Environment

• OS: Ubuntu 24.04.4 LTS
• opencode: 1.18.30
• relevant package: opencode-cmd-provider (@latest dir at 1.7.3, bare dir at 1.6.2; npm reports 1.7.3 as latest)

Problem

1. Cache is keyed by the exact specifier string

Npm.add derives the cache directory from the raw package string:

// packages/core/src/npm.ts
const directory = (pkg: string) => path.join(global.cache, "packages", sanitize(pkg))

The two loaders pass different strings for the same package:

• plugin loader appends @latest:

  // packages/opencode/src/plugin/shared.ts
  const pkg = hit?.name && hit.raw === hit.name ? `${hit.name}@latest` : spec

• provider loader uses model.api.npm verbatim (whatever the plugin/provider declared):

  // packages/opencode/src/provider/provider.ts
  const item = await Npm.add(model.api.npm)

So a single plugin that registers its provider by bare name produces two directories:

~/.cache/opencode/packages/opencode-cmd-provider@latest   # plugin
~/.cache/opencode/packages/opencode-cmd-provider          # runtime provider

2. Existing installs are never refreshed

// packages/core/src/npm.ts
if (yield* afs.existsSafe(path.join(dir, "node_modules", name))) {
  return resolveEntryPoint(name, path.join(dir, "node_modules", name))
}

Once the bare directory exists it is returned forever, at the version it was first installed. Updating the package moves only the @latest copy forward; the bare copy keeps the old version and is still what opencode loads at runtime.

Impact

The effective state is confusing and user-visible: npm reports the latest version as installed, but opencode runs the old one. Anything that depends on the two halves of one plugin matching — capability declarations vs. the code that enforces them, feature additions, bug fixes — can silently use stale behavior. Deleting the stale directory forces opencode to re-install the current version, which confirms the cause.

Why the plugin loader / provider loader should be reconciled

A plugin and the provider it registers are conceptually one dependency. Keying them separately and never reconciling versions makes divergence possible for any plugin that registers a provider by an unpinned (or differently formatted) specifier. A plugin author can work around this by pinning a version, but opencode should not depend on that discipline to keep a plugin internally consistent.

Possible directions

• Key the cache by resolved package name (or name + resolved version), so foo and foo@latest resolve to the same installed artifact instead of two.
• Have Npm.add verify the installed version against the requested spec and re-resolve when it no longer satisfies it, instead of short-circuiting on mere existence.
• Ensure a plugin's runtime provider is loaded from the same resolved package the plugin came from.

Related

Plugin-side report (unpinned provider specifier makes this reachable): rashidrazak/opencode-cmd-provider#149

[github-actions]

This issue might be a duplicate of (or closely related to) an existing issue. Please check:

• Plugin @latest cache can stay pinned to stale npm version #25293: Plugin @latest cache can stay pinned to stale npm version — covers the same stale-cache / existing-install-never-refreshed behavior described in this report's second finding. This issue additionally covers the two-key problem (bare name vs @latest producing separate directories), which may be new ground.

If the two-key caching problem is the distinct part you want tracked separately, it may be worth noting the overlap with #25293 so the fixes can be coordinated.

[log0u7]

Same two-cache-keys mechanism here, with an additional consequence: the plugin module gets EVALUATED TWICE in one process.

Environment: opencode 1.18.31 (official binary), Ubuntu 24.04. Config loads five npm plugins (no provider npm entries involved): opencode-pty, openrtk, @dietrichgebert/ponytail, opencode-worktree-guard, opencode-workflow-guard.

One boot creates both roots per newly-installed plugin, seconds apart:

~/.cache/opencode/packages/opencode-worktree-guard@latest   19:52:14
~/.cache/opencode/packages/opencode-worktree-guard          19:52:27

(plugins installed by earlier versions only have the @latest root). The bare root is recreated on every boot - deleting it before a boot does not prevent it.

Double-evaluation proof: opencode-worktree-guard 0.3.7 counts module evaluations in a globalThis symbol and warns on every boot:

[worktree-guard] WARNING: Module loaded 2 times. State is shared via globalThis.

So beyond the stale-copy problem described in this issue, the second cache root also means a second module instance per process: plugins relying on module-level state or single registration would double-register, and the warning surfaces to users as a TUI console warning.

Traced the second call site that passes the raw spec: packages/core/src/config/plugin/external.ts:77 calls npm.add(ref.package) with the verbatim config spec, while packages/opencode/src/plugin/shared.ts:210 normalizes bare names to @latest before calling Npm.add. Happy to propose a canonical-key fix at the Npm.add level (covers all five call sites) if that sounds right.

[log0u7]

Opened #49612 with a fix: Npm.add/Npm.which now key the cache root by a canonical specifier (bare name -> name@latest), so the plugin loader's @latest normalization and the raw-spec call sites (config/plugin/external.ts, provider loader, core dynamic providers) converge on one install. Versioned, git and file specs keep their own root.