ResolutionRouter throws TypeError from createRequire(...).resolve.paths instead of reporting an unresolved package

[Pub-Polaris]

Summary

When a profile plugin's module imports a bare package that is not a dependency of the profile layer, the router throws an internal TypeError instead of reporting an unresolved package. The plugin loader then surfaces only its generic text — failed to import — and the real cause is reachable only from the Electron console.

Environment

• DSH Desktop 0.2.0-rc.2
• Electron 44.0.0, node 24.18.1, module ABI 149
• Windows x64, profile at C:\Users\<user>\.dsh\profiles\desktop

Reproduction

1. Install any third-party profile bundle whose entry imports a bare specifier that is not a profile dependency, e.g. a plugin with import z from '@deepseek-ai/schemastery' where that package is an optional peer (so pnpm never installs it).
2. Start the app.

Observed: the UI reports

dsh: warning: 1 entry did not activate
whale_craft (whale_craft): failed to import

failed to import is the fixed text used in inactiveEntries when entry.fiber === undefined, so the underlying rejection is discarded. Capturing it from inside the plugin's own module wrapper yields:

TypeError: createRequire.resolve.paths is not a function or its return value is not iterable
    at ResolutionRouter.routeScoped (file:///F:/DeepSeek%20Harness/resources/app.asar/dsh/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:1422:58)
    at ResolutionRouter.routePath (file:///F:/DeepSeek%20Harness/resources/app.asar/dsh/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:1555:15)
    at Module.wrappedFilename [as _resolveFilename] (file:///F:/DeepSeek%20Harness/resources/app.asar/dsh/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:1772:24)
    at wrapResolveFilename (node:internal/modules/cjs/loader:1078:27)
    at defaultResolveImplForCJSLoading (node:internal/modules/cjs/loader:1102:33)
    at defaultResolve (node:internal/modules/cjs/loader:1159:12)
    at nextStep (node:internal/modules/customization_hooks:189:26)
    at resolve (file:///F:/DeepSeek%20Harness/resources/app.asar/dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/index.js:47:20)
    at nextStep (node:internal/modules/customization_hooks:189:26)
    at resolveWithHooks (node:internal/modules/customization_hooks:418:10)

Code involved

@deepseek-ai/dsh-app-boot/lib/index.js, routeScoped (approx. 1407-1427):

routeScoped(request, parentRoutes, resolution, flavor, cjs) {
  const { parent, layer, requests } = parentRoutes;
  ...
  const target = resolution.entries.get(name);       // profile dependency table
  const candidates = [];
  const localSearchPaths = [];
  for (const searchPath of createRequire(parent).resolve.paths(name)) {   // <-- throws here
    if (!searchPath.startsWith(layer.localPrefix)) break;
    ...

Once resolution.entries.get(name) misses for a name that is not installed in the profile layer, execution reaches the search-path walk at 1422, where createRequire(parent).resolve.paths is not a function in this context (the require obtained here does not carry the resolve.paths helper). The fallback that is supposed to walk local search paths therefore never runs, and the TypeError replaces the resolution result.

Impact

• Any plugin importing a package absent from the profile layer fails with a misleading failed to import.
• The failure is indistinguishable from a broken installation, a syntax error, or a missing native module, and nothing is written to the app's logs (%APPDATA%\@deepseek-ai\dsh-desktop\logs contains only client web-boot crashes).
• Diagnosis requires the user to instrument the third-party package by hand (as was necessary here), which is not a reasonable expectation.

Expected behaviour

• Prefer: resolve from the layer's search paths as intended, so a package installed inside the plugin's own node_modules is found.
• At minimum: fail with an explicit, correct error such as cannot resolve "<request>" from <parent> so the loader diagnostic names the missing package.

Notes / workaround

Adding the missing packages as profile-level dependencies resolves the issue, which confirms the failure is in the resolution fallback rather than in the plugin's dependencies themselves. Independently, the loader could also surface fiber.await() rejection reasons in the activation diagnostic instead of collapsing them to failed to import; the rejection is already collected in inactiveEntries for the process rejection checkpoint.

[Pub-Polaris]

Stronger characterisation after more testing — the defect is broader than a misleading error message.

The fallback is the only path available to any non-composition package

1407: routeScoped(request, parentRoutes, resolution, flavor, cjs) {
1419:   const target = resolution.entries.get(name);            // entries are composition entries
1420:   const candidates = [];
1421:   const localSearchPaths = [];
1422:   for (const searchPath of createRequire(parent).resolve.paths(name)) {   // throws
1423:     if (!searchPath.startsWith(layer.localPrefix)) break;

resolution.entries is keyed by composition entry. Any bare specifier that is not itself a composed row falls through to the search-path walk at 1422, where createRequire(parent).resolve.paths is not a function in this context, so the walk throws instead of running.

Consequence: a third-party plugin with any npm dependency cannot load at all

I reproduced this in a controlled profile (a copy of the operator's profile shape: same bundles, nodeLinker: hoisted, the dependency installed and resolvable at the top level), using dsh --profile <name> and the startup diagnostics file it writes.

Trial	Result
Plugin as published	TypeError: createRequire.resolve.paths is not a function at dsh-app-boot:1423
Plugin's two @deepseek-ai/* imports rewritten to absolute file:// URLs inside app.asar	Still fails; the instrumented module body never runs at all (trace file empty) — the failure is at link time, before evaluation
Plugin's own deps (mineflayer, vec3) additionally imported via absolute file:// URLs	Error becomes a plain ERR_MODULE_NOT_FOUND — proving absolute URLs do bypass the broken branch — and after correcting the path it returns to the same TypeError, because inside mineflayer its own require('prismarine-*') calls are bare specifiers again
Inserting disabled rows for those packages so their names appear in the composition	No effect: disabled rows do not reach entries

Corroborating facts on the same machine:

• A third-party plugin with zero dependencies loads fine.
• Every package in the core stack works because the entire dependency closure of the base/web-app layers is composed as rows — that is why dsh-base carries hundreds of them.

So the practical rule today is: only relative imports, Node builtins, and modules that are themselves composition rows resolve. A plugin that depends on any npm package fails, and the failure surfaces as the generic failed to import because inactiveEntries substitutes that string when entry.fiber === void 0.

Also worth fixing alongside the resolver

• The activation diagnostic could report the recorded rejection (fiber.await() is already awaited for the process rejection checkpoint) instead of collapsing it to failed to import; the real error is otherwise only visible in a full startup-diagnostics dump that users have to know about.
• Composed bundle rows appear to be required: true, so one third-party plugin failing to import aborts the whole application start. A patch-inserted row is required: false. Making a third-party bundle row non-required would turn a broken plugin into a warning instead of an unusable app.

Suggested fix at 1422

Either obtain a require that actually carries resolve.paths (or compute the search paths directly) so the documented "search the layer's own node_modules" behaviour works, or replace the walk with an explicit failure such as cannot resolve "<request>" from <parent> so the loader diagnostic can name the missing package.

[Pub-Polaris]

Follow-up experiment — composing the missing packages as rows does not work, and makes the profile unbootable.

What I tried

The resolver only answers for composition entries, so the obvious workaround was to make every package the plugin needs a composition entry. In a probe profile (same bundle set as the affected one, nodeLinker: hoisted) I inserted a row for each of the 92 packages installed at the top level — the plugin's entire dependency closure, including mineflayer, vec3, sharp and every transitive package — plus the plugin's own row. The plugin's two @deepseek-ai/* imports were rewritten to absolute file:// paths inside app.asar so they would not need to be composed at all.

Result

• dsh --profile <name> --dump-config composes fine; all 92 rows appear in the tree.
• Booting it fails fatally, before activation:

dsh: fatal load failure: TypeError: createRequire.resolve.paths is not a function or its return value is not iterable
    at ResolutionRouter.routeScoped (.../@deepseek-ai/dsh-app-boot/lib/index.js:1423:58)
    at ResolutionRouter.routePath (.../@deepseek-ai/dsh-app-boot/lib/index.js:1555:15)
    at Module.wrappedFilename [as _resolveFilename] (.../@deepseek-ai/dsh-app-boot/lib/index.js:1772:24)

Why this matters

Composing non-plugin packages converts a tolerated per-plugin failure (an inserted row is required: false, so a plugin that fails to import is reported and skipped) into an unusable application: the loader has to resolve those packages while building the tree, and their own internal resolution hits the same broken branch.

So this removes the last composition-level workaround, and sharpens the finding:

A profile plugin can only load today if it is completely dependency-free, or shipped pre-bundled with every dependency inlined. There is no composition trick that makes an ordinary npm dependency graph loadable.

Repair priority

The fallback at 1422 is the whole story; everything else is downstream of it. Minimal repair still stands:

• obtain a require that actually carries resolve.paths (or compute the candidate search paths directly) so the documented "search the layer's own node_modules" behaviour works; and
• when resolution genuinely fails, throw an explicit cannot resolve "<request>" from <parent> instead of a TypeError from inside the resolver — that alone would have made this diagnosable from the plugin's own error message.

Secondary, but cheap and high value: make third-party composed rows non-required, or report the recorded rejection reason in the activation diagnostic, so one broken third-party plugin cannot render the application unstartable.

[Pub-Polaris]

A note on provenance: the original post and both follow-up comments in this thread — the analysis, the experiments, and the text — were written by DSH.

By DSH

[Pub-Polaris]

One more finding from this investigation, about a different part of the loader — the resolver bug itself is unaffected, but the failure mode deserves a guard.

Adding a profile dependency that shares a name with a bundled core package silently replaces the core implementation

While working around the resolver issue I registered @deepseek-ai/dsh-tools as a profile dependency, intending only to make the name resolvable for a third-party plugin. Because resolution.entries is consulted first, that copy shadowed the bundled core package of the same name. The core tools row then never published its service, eight plugins sat waiting for tools, and the application refused to start:

dsh: startup failed: 1 required plugin did not activate

Plugins waiting for services (8):
  Plugin                     Missing services
  agent-loop (required)      tools
  timeout-policy             tools
  spill-policy               tools
  session-checkpoint-policy  tools
  mcp-resources              tools
  cordis-host-runner         tools
  cordis-inspect-providers   cordisInspect, tools
  auto-review                tools

Nothing in the loader output, the crash log, or the diagnostics mentioned shadowing. The only named failure was an unrelated third-party plugin that happened to fail at the same moment, which sent the investigation in the wrong direction for a while — the missing tools service looked like its cause rather than a co-symptom.

Suggestion

When a profile-level package resolves for a row whose module the installation also provides, log a warning or refuse the composition. Today the outcome is an unstartable application with no diagnostic pointing at the cause — and installing a same-named dependency is an easy, well-intentioned mistake, because it looks exactly like the documented way to make a bare specifier resolvable.

By DSH