@rebon/cli-win32-x64 1.3.0 → 1.5.0

package/payload/compose-runtime/src/registry.mjs

@@ -1,191 +1,191 @@
-// What one Cordis entry registered, captured while it mounts.
-//
-// A Cordis plugin does not know the plugin plane exists: it calls
-// `ctx.tools.register(...)`, `ctx.llm.registerAdapter(...)`,
-// `ctx.systemPrompt.section(...)`, and the seats it calls are the ones that
-// have to turn those into something `plugin/load` can answer with. This is
-// where they put it.
-//
-// The sink reaches a seat through the registering context — `ctx[SINK]`, set
-// when the entry's context is derived — for the same reason the old ledger's
-// owner stamp did: it is read synchronously at registration time, so an async
-// interleaving cannot attribute one plugin's registration to another.
-//
-// Two rules it enforces, both borrowed from the host's own registrar because a
-// composition entry is a plugin and should not get a weaker contract:
-//
-//   * **Declared first.** A registration the load request did not declare is
-//     refused where the plugin made it, rather than arriving later as a ready
-//     report rebon has to reject.
-//   * **Registration closes.** Once the entry's fiber has resolved, the host
-//     has already been told what this plugin provides; a later registration
-//     would be a capability nothing downstream knows about.
-
-/** The key an entry's context carries its sink under. */
-export const SINK = Symbol.for('rebon.composeSink');
-/** The key an entry's context carries its plugin id under. */
-export const OWNER = Symbol.for('rebon.composeOwner');
-
-class RegistrationError extends Error {
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = 'RegistrationError';
-  }
-}
-
-export class RegistrationSink {
-  #sealed = false;
-
-  constructor(pluginId, declared = {}) {
-    this.pluginId = pluginId;
-    this.declared = {
-      services: new Set(declared.services ?? []),
-      eventTopics: new Set(declared.eventTopics ?? []),
-      llmProviders: new Set(declared.llmProviders ?? []),
-      tools: new Set(declared.tools ?? []),
-    };
-    /** Protocol-shaped registrations, answered by `plugin/load`. */
-    this.services = new Map();
-    this.topics = new Map();
-    this.llmProviders = new Map();
-    this.tools = new Map();
-    /** Handles on a session, handed out when a scope opens. */
-    this.scopeHandlers = [];
-    /** The sessions this plugin is currently attached to.
-     *
-     *  Every entry gets one of these, not just the ones that ask: it is how a
-     *  seat reaches rebon on behalf of code running outside any inbound call.
-     *  An agent loop drives its own turn, and the adapter it reaches for a
-     *  credential is running on the loop's schedule rather than answering
-     *  anything — but it is still that plugin's code, in that session, and the
-     *  call it makes should say so. */
-    this.sessions = new Set();
-    this.scopeHandlers.push((scopeCtx) => {
-      this.sessions.add(scopeCtx);
-      return () => this.sessions.delete(scopeCtx);
-    });
-    /** Facts with no protocol counterpart, fetched from the `compose` service. */
-    this.sections = [];
-    this.catalogs = new Map();
-    this.webProviders = [];
-  }
-
-  #admit(kind, name, declared) {
-    if (this.#sealed) {
-      throw new RegistrationError(
-        '[REGISTRATION_CLOSED]',
-        `${kind} ${JSON.stringify(name)} was registered after ${this.pluginId} finished loading`,
-      );
-    }
-    if (typeof name !== 'string' || name.length === 0) {
-      throw new RegistrationError('[WRONG_SHAPE]', `a ${kind} needs a non-empty name`);
-    }
-    if (!declared.has(name)) {
-      throw new RegistrationError(
-        '[UNAUTHORIZED_REGISTER]',
-        `${kind} ${JSON.stringify(name)} is not declared by ${this.pluginId}'s manifest`,
-      );
-    }
-  }
-
-  service(name, handler) {
-    this.#admit('service', name, this.declared.services);
-    this.services.set(name, handler);
-  }
-
-  topic(name, handler) {
-    this.#admit('topic', name, this.declared.eventTopics);
-    this.topics.set(name, handler);
-  }
-
-  llm(provider, handler) {
-    this.#admit('provider', provider, this.declared.llmProviders);
-    this.llmProviders.set(provider, handler);
-  }
-
-  tool(definition, handler) {
-    this.#admit('tool', definition?.name, this.declared.tools);
-    this.tools.set(definition.name, { definition, handler });
-  }
-
-  /// A handle on the session, for a plugin that acts rather than only answers.
-  ///
-  /// Not declared, because it is not a capability: every power the handle
-  /// carries is one of the declarations above, checked when it is used.
-  scope(handler) {
-    if (typeof handler !== 'function') {
-      throw new RegistrationError('[WRONG_SHAPE]', 'a scope handler must be a function');
-    }
-    this.scopeHandlers.push(handler);
-  }
-
-  // ---- extras ----------------------------------------------------------
-  //
-  // A model catalog, a prompt section and a web provider are things rebon
-  // needs and the protocol has no field for. They are reported by the
-  // composition's own `compose` service rather than by widening the ready
-  // report, which every plugin shares and only this one would use.
-
-  section(entry) {
-    this.sections.push(entry);
-  }
-
-  catalog(provider, catalog) {
-    this.catalogs.set(provider, catalog);
-  }
-
-  webProvider(kind, id, available) {
-    this.webProviders.push({ kind, id, available });
-  }
-
-  /// Closes registration and hands back what the host asked for.
-  seal() {
-    this.#sealed = true;
-    return this;
-  }
-
-  /// The `plugin/load` answer, in the shape the host's own loader produces.
-  loaded() {
-    return {
-      services: [...this.services.keys()],
-      eventTopics: [...this.topics.keys()],
-      llmProviders: [...this.llmProviders.keys()],
-      tools: [...this.tools.values()].map((entry) => entry.definition),
-      serviceHandlers: this.services,
-      topicHandlers: this.topics,
-      llmAdapters: this.llmProviders,
-      toolHandlers: new Map([...this.tools].map(([name, entry]) => [name, entry.handler])),
-      scopeHandlers: [...this.scopeHandlers],
-    };
-  }
-
-  /// What the `compose` service reports for this plugin.
-  report() {
-    return {
-      sections: this.sections.map((section) => ({ ...section })),
-      providers: [...this.catalogs].map(([provider, catalog]) => ({ provider, ...catalog })),
-      webProviders: this.webProviders.map((entry) => ({ ...entry })),
-    };
-  }
-}
-
-/// The session this plugin is attached to, if it is attached to one.
-///
-/// With more than one open, the first is used: a plugin acting on its own
-/// schedule is acting in one session, and which one is a fact about how rebon
-/// opened them rather than something guessable here.
-export function sessionOf(ctx) {
-  const sink = ctx?.[SINK];
-  if (sink === undefined) return undefined;
-  for (const session of sink.sessions) return session;
-  return undefined;
-}
-
-/// The sink the code currently registering belongs to, or undefined.
-///
-/// Undefined is normal: the built-in seats mount into the realm itself, and a
-/// seat calling another seat is not a registration by any plugin.
-export function sinkOf(ctx) {
-  return ctx?.[SINK];
-}
+// What one Cordis entry registered, captured while it mounts.
+//
+// A Cordis plugin does not know the plugin plane exists: it calls
+// `ctx.tools.register(...)`, `ctx.llm.registerAdapter(...)`,
+// `ctx.systemPrompt.section(...)`, and the seats it calls are the ones that
+// have to turn those into something `plugin/load` can answer with. This is
+// where they put it.
+//
+// The sink reaches a seat through the registering context — `ctx[SINK]`, set
+// when the entry's context is derived — for the same reason the old ledger's
+// owner stamp did: it is read synchronously at registration time, so an async
+// interleaving cannot attribute one plugin's registration to another.
+//
+// Two rules it enforces, both borrowed from the host's own registrar because a
+// composition entry is a plugin and should not get a weaker contract:
+//
+//   * **Declared first.** A registration the load request did not declare is
+//     refused where the plugin made it, rather than arriving later as a ready
+//     report rebon has to reject.
+//   * **Registration closes.** Once the entry's fiber has resolved, the host
+//     has already been told what this plugin provides; a later registration
+//     would be a capability nothing downstream knows about.
+
+/** The key an entry's context carries its sink under. */
+export const SINK = Symbol.for('rebon.composeSink');
+/** The key an entry's context carries its plugin id under. */
+export const OWNER = Symbol.for('rebon.composeOwner');
+
+class RegistrationError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = 'RegistrationError';
+  }
+}
+
+export class RegistrationSink {
+  #sealed = false;
+
+  constructor(pluginId, declared = {}) {
+    this.pluginId = pluginId;
+    this.declared = {
+      services: new Set(declared.services ?? []),
+      eventTopics: new Set(declared.eventTopics ?? []),
+      llmProviders: new Set(declared.llmProviders ?? []),
+      tools: new Set(declared.tools ?? []),
+    };
+    /** Protocol-shaped registrations, answered by `plugin/load`. */
+    this.services = new Map();
+    this.topics = new Map();
+    this.llmProviders = new Map();
+    this.tools = new Map();
+    /** Handles on a session, handed out when a scope opens. */
+    this.scopeHandlers = [];
+    /** The sessions this plugin is currently attached to.
+     *
+     *  Every entry gets one of these, not just the ones that ask: it is how a
+     *  seat reaches rebon on behalf of code running outside any inbound call.
+     *  An agent loop drives its own turn, and the adapter it reaches for a
+     *  credential is running on the loop's schedule rather than answering
+     *  anything — but it is still that plugin's code, in that session, and the
+     *  call it makes should say so. */
+    this.sessions = new Set();
+    this.scopeHandlers.push((scopeCtx) => {
+      this.sessions.add(scopeCtx);
+      return () => this.sessions.delete(scopeCtx);
+    });
+    /** Facts with no protocol counterpart, fetched from the `compose` service. */
+    this.sections = [];
+    this.catalogs = new Map();
+    this.webProviders = [];
+  }
+
+  #admit(kind, name, declared) {
+    if (this.#sealed) {
+      throw new RegistrationError(
+        '[REGISTRATION_CLOSED]',
+        `${kind} ${JSON.stringify(name)} was registered after ${this.pluginId} finished loading`,
+      );
+    }
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new RegistrationError('[WRONG_SHAPE]', `a ${kind} needs a non-empty name`);
+    }
+    if (!declared.has(name)) {
+      throw new RegistrationError(
+        '[UNAUTHORIZED_REGISTER]',
+        `${kind} ${JSON.stringify(name)} is not declared by ${this.pluginId}'s manifest`,
+      );
+    }
+  }
+
+  service(name, handler) {
+    this.#admit('service', name, this.declared.services);
+    this.services.set(name, handler);
+  }
+
+  topic(name, handler) {
+    this.#admit('topic', name, this.declared.eventTopics);
+    this.topics.set(name, handler);
+  }
+
+  llm(provider, handler) {
+    this.#admit('provider', provider, this.declared.llmProviders);
+    this.llmProviders.set(provider, handler);
+  }
+
+  tool(definition, handler) {
+    this.#admit('tool', definition?.name, this.declared.tools);
+    this.tools.set(definition.name, { definition, handler });
+  }
+
+  /// A handle on the session, for a plugin that acts rather than only answers.
+  ///
+  /// Not declared, because it is not a capability: every power the handle
+  /// carries is one of the declarations above, checked when it is used.
+  scope(handler) {
+    if (typeof handler !== 'function') {
+      throw new RegistrationError('[WRONG_SHAPE]', 'a scope handler must be a function');
+    }
+    this.scopeHandlers.push(handler);
+  }
+
+  // ---- extras ----------------------------------------------------------
+  //
+  // A model catalog, a prompt section and a web provider are things rebon
+  // needs and the protocol has no field for. They are reported by the
+  // composition's own `compose` service rather than by widening the ready
+  // report, which every plugin shares and only this one would use.
+
+  section(entry) {
+    this.sections.push(entry);
+  }
+
+  catalog(provider, catalog) {
+    this.catalogs.set(provider, catalog);
+  }
+
+  webProvider(kind, id, available) {
+    this.webProviders.push({ kind, id, available });
+  }
+
+  /// Closes registration and hands back what the host asked for.
+  seal() {
+    this.#sealed = true;
+    return this;
+  }
+
+  /// The `plugin/load` answer, in the shape the host's own loader produces.
+  loaded() {
+    return {
+      services: [...this.services.keys()],
+      eventTopics: [...this.topics.keys()],
+      llmProviders: [...this.llmProviders.keys()],
+      tools: [...this.tools.values()].map((entry) => entry.definition),
+      serviceHandlers: this.services,
+      topicHandlers: this.topics,
+      llmAdapters: this.llmProviders,
+      toolHandlers: new Map([...this.tools].map(([name, entry]) => [name, entry.handler])),
+      scopeHandlers: [...this.scopeHandlers],
+    };
+  }
+
+  /// What the `compose` service reports for this plugin.
+  report() {
+    return {
+      sections: this.sections.map((section) => ({ ...section })),
+      providers: [...this.catalogs].map(([provider, catalog]) => ({ provider, ...catalog })),
+      webProviders: this.webProviders.map((entry) => ({ ...entry })),
+    };
+  }
+}
+
+/// The session this plugin is attached to, if it is attached to one.
+///
+/// With more than one open, the first is used: a plugin acting on its own
+/// schedule is acting in one session, and which one is a fact about how rebon
+/// opened them rather than something guessable here.
+export function sessionOf(ctx) {
+  const sink = ctx?.[SINK];
+  if (sink === undefined) return undefined;
+  for (const session of sink.sessions) return session;
+  return undefined;
+}
+
+/// The sink the code currently registering belongs to, or undefined.
+///
+/// Undefined is normal: the built-in seats mount into the realm itself, and a
+/// seat calling another seat is not a registration by any plugin.
+export function sinkOf(ctx) {
+  return ctx?.[SINK];
+}

package/payload/compose-runtime/src/resolve.mjs

@@ -1,115 +1,115 @@
-// Module resolution for the composition, on real Node.
-//
-// Node has no import map, but it has `module.registerHooks()` — synchronous,
-// in-thread resolve/load hooks — and this is the composition's map written in
-// that vocabulary. There used to be a second map, in the deno_core host's
-// `build_import_map`, and a test here holding the two to the same specifier
-// set; that host is gone, so this is the only map there is.
-//
-// Two entries it does not carry, both from the deleted one and both in the
-// direction of deleting code:
-//
-//   * the four `node:` entries. `node:async_hooks`, `node:util/types`,
-//     `node:path` and `node:crypto` resolved to hand-written shims because bare
-//     deno_core has no standard library; real Node has all four.
-//   * `eventsource-parser/stream` resolves to this package's module rather than
-//     the vendored one. The vendored build is not the published package: it was
-//     rewritten against the "Mini streams" protocol the old host installed,
-//     because the published `EventSourceParserStream` extends the WHATWG
-//     `TransformStream` and bare deno_core has none. On real Node that
-//     rewrite breaks — `body.pipeThrough(new EventSourceParserStream())` throws
-//     `ERR_INVALID_ARG_TYPE` — so the upstream shape comes back. See
-//     `eventsource-stream.mjs`.
-import { registerHooks } from 'node:module';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { payloadDir } from './payload.mjs';
-
-/// Payload-relative module map, keyed by bare specifier.
-///
-/// Mirrors `build_import_map` entry for entry, minus the `node:` shims.
-export function payloadModules(dir) {
-  const at = (relative) => pathToFileURL(path.join(dir, relative)).href;
-  return new Map(Object.entries({
-    cordis: at('vendor/cordis/index.js'),
-    cosmokit: at('vendor/cosmokit/index.mjs'),
-    schemastery: at('vendor/schemastery/index.mjs'),
-    '@deepseek-ai/cordis': at('vendor/cordis/index.js'),
-    '@deepseek-ai/cosmokit': at('vendor/cosmokit/index.mjs'),
-    '@deepseek-ai/schemastery': at('vendor/schemastery/index.mjs'),
-    '@deepseek-ai/cordis-plugin-timer': at('vendor/dsh/timer.js'),
-    '@deepseek-ai/cordis-plugin-logger-console': at('vendor/dsh/logger-console.js'),
-    '@deepseek-ai/dsh-llm-deepseek': at('vendor/dsh/llm-deepseek.js'),
-    '@deepseek-ai/dsh-timeout': at('vendor/dsh/timeout.js'),
-    '@deepseek-ai/dsh-llm': at('compose/shims/dsh-llm.js'),
-    '@deepseek-ai/dsh-credentials': at('compose/shims/dsh-credentials.js'),
-    '@deepseek-ai/dsh-settings': at('compose/shims/dsh-settings.js'),
-    '@deepseek-ai/dsh-launch-environment': at('compose/shims/dsh-launch-environment.js'),
-    '@deepseek-ai/dsh-anonymous-user-id': at('compose/shims/dsh-anonymous-user-id.js'),
-    'eventsource-parser': at('vendor/eventsource-parser/index.js'),
-    '@deepseek-ai/dsh-tools': at('compose/shims/dsh-tools.js'),
-    '@deepseek-ai/dsh-tool-todo': at('vendor/dsh/tool-todo.js'),
-    zod: at('compose/shims/zod-lite.js'),
-    '@deepseek-ai/dsh-web': at('compose/shims/dsh-web.js'),
-    '@deepseek-ai/dsh-web-search-exa': at('vendor/dsh/web-search-exa.js'),
-    '@deepseek-ai/dsh-tool-web': at('vendor/dsh/tool-web.js'),
-    '@deepseek-ai/dsh-scope': at('vendor/dsh/scope.js'),
-    '@deepseek-ai/dsh-session': at('vendor/dsh/session.js'),
-    '@deepseek-ai/dsh-agent': at('vendor/dsh/agent.js'),
-    '@deepseek-ai/dsh-system-prompt': at('vendor/dsh/system-prompt.js'),
-    '@deepseek-ai/dsh-agent-loop': at('vendor/dsh/agent-loop.js'),
-  }));
-}
-
-/// Specifiers this package answers itself rather than from the payload.
-export function localModules() {
-  const at = (relative) => new URL(relative, import.meta.url).href;
-  return new Map(Object.entries({
-    rebon: at('./bridge.mjs'),
-    'eventsource-parser/stream': at('./eventsource-stream.mjs'),
-  }));
-}
-
-let installed;
-
-/// Installs the composition's module resolution, once per process.
-///
-/// `extraModules` is the embedder's own map (the `modules` half of a
-/// composition config: plugin name → absolute module file), which is how a
-/// plugin outside the vendored payload gets a name.
-///
-/// Returns the resolved map so callers can report what a specifier became
-/// without repeating the lookup rules.
-export function installModuleResolution({ dir = payloadDir(), extraModules = {} } = {}) {
-  const map = new Map([...payloadModules(dir), ...localModules()]);
-  for (const [name, file] of Object.entries(extraModules)) {
-    map.set(name, pathToFileURL(path.resolve(file)).href);
-  }
-  if (installed) {
-    // Hooks are process-wide and cannot be unregistered per call; re-running
-    // with a different map would leave two resolvers disagreeing about the
-    // same specifier, which is a debugging trap rather than a feature.
-    for (const [name, url] of map) installed.map.set(name, url);
-    return installed.map;
-  }
-
-  const payloadPrefix = pathToFileURL(dir.endsWith(path.sep) ? dir : dir + path.sep).href;
-  const state = { map };
-  registerHooks({
-    resolve(specifier, context, next) {
-      const mapped = state.map.get(specifier);
-      if (mapped !== undefined) return { url: mapped, format: 'module', shortCircuit: true };
-      return next(specifier, context);
-    },
-    // The payload's ESM is `.js` under no `package.json`, so Node's own rules
-    // read it as CommonJS and every `import` in it is a syntax error. The
-    // deno_core loader had no such ambiguity — everything it loaded was a
-    // module — so this is a fact about Node, not about the payload.
-    load(url, context, next) {
-      if (url.startsWith(payloadPrefix)) return next(url, { ...context, format: 'module' });
-      return next(url, context);
-    },
-  });
-  installed = state;
-  return state.map;
-}
+// Module resolution for the composition, on real Node.
+//
+// Node has no import map, but it has `module.registerHooks()` — synchronous,
+// in-thread resolve/load hooks — and this is the composition's map written in
+// that vocabulary. There used to be a second map, in the deno_core host's
+// `build_import_map`, and a test here holding the two to the same specifier
+// set; that host is gone, so this is the only map there is.
+//
+// Two entries it does not carry, both from the deleted one and both in the
+// direction of deleting code:
+//
+//   * the four `node:` entries. `node:async_hooks`, `node:util/types`,
+//     `node:path` and `node:crypto` resolved to hand-written shims because bare
+//     deno_core has no standard library; real Node has all four.
+//   * `eventsource-parser/stream` resolves to this package's module rather than
+//     the vendored one. The vendored build is not the published package: it was
+//     rewritten against the "Mini streams" protocol the old host installed,
+//     because the published `EventSourceParserStream` extends the WHATWG
+//     `TransformStream` and bare deno_core has none. On real Node that
+//     rewrite breaks — `body.pipeThrough(new EventSourceParserStream())` throws
+//     `ERR_INVALID_ARG_TYPE` — so the upstream shape comes back. See
+//     `eventsource-stream.mjs`.
+import { registerHooks } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { payloadDir } from './payload.mjs';
+
+/// Payload-relative module map, keyed by bare specifier.
+///
+/// Mirrors `build_import_map` entry for entry, minus the `node:` shims.
+export function payloadModules(dir) {
+  const at = (relative) => pathToFileURL(path.join(dir, relative)).href;
+  return new Map(Object.entries({
+    cordis: at('vendor/cordis/index.js'),
+    cosmokit: at('vendor/cosmokit/index.mjs'),
+    schemastery: at('vendor/schemastery/index.mjs'),
+    '@deepseek-ai/cordis': at('vendor/cordis/index.js'),
+    '@deepseek-ai/cosmokit': at('vendor/cosmokit/index.mjs'),
+    '@deepseek-ai/schemastery': at('vendor/schemastery/index.mjs'),
+    '@deepseek-ai/cordis-plugin-timer': at('vendor/dsh/timer.js'),
+    '@deepseek-ai/cordis-plugin-logger-console': at('vendor/dsh/logger-console.js'),
+    '@deepseek-ai/dsh-llm-deepseek': at('vendor/dsh/llm-deepseek.js'),
+    '@deepseek-ai/dsh-timeout': at('vendor/dsh/timeout.js'),
+    '@deepseek-ai/dsh-llm': at('compose/shims/dsh-llm.js'),
+    '@deepseek-ai/dsh-credentials': at('compose/shims/dsh-credentials.js'),
+    '@deepseek-ai/dsh-settings': at('compose/shims/dsh-settings.js'),
+    '@deepseek-ai/dsh-launch-environment': at('compose/shims/dsh-launch-environment.js'),
+    '@deepseek-ai/dsh-anonymous-user-id': at('compose/shims/dsh-anonymous-user-id.js'),
+    'eventsource-parser': at('vendor/eventsource-parser/index.js'),
+    '@deepseek-ai/dsh-tools': at('compose/shims/dsh-tools.js'),
+    '@deepseek-ai/dsh-tool-todo': at('vendor/dsh/tool-todo.js'),
+    zod: at('compose/shims/zod-lite.js'),
+    '@deepseek-ai/dsh-web': at('compose/shims/dsh-web.js'),
+    '@deepseek-ai/dsh-web-search-exa': at('vendor/dsh/web-search-exa.js'),
+    '@deepseek-ai/dsh-tool-web': at('vendor/dsh/tool-web.js'),
+    '@deepseek-ai/dsh-scope': at('vendor/dsh/scope.js'),
+    '@deepseek-ai/dsh-session': at('vendor/dsh/session.js'),
+    '@deepseek-ai/dsh-agent': at('vendor/dsh/agent.js'),
+    '@deepseek-ai/dsh-system-prompt': at('vendor/dsh/system-prompt.js'),
+    '@deepseek-ai/dsh-agent-loop': at('vendor/dsh/agent-loop.js'),
+  }));
+}
+
+/// Specifiers this package answers itself rather than from the payload.
+export function localModules() {
+  const at = (relative) => new URL(relative, import.meta.url).href;
+  return new Map(Object.entries({
+    rebon: at('./bridge.mjs'),
+    'eventsource-parser/stream': at('./eventsource-stream.mjs'),
+  }));
+}
+
+let installed;
+
+/// Installs the composition's module resolution, once per process.
+///
+/// `extraModules` is the embedder's own map (the `modules` half of a
+/// composition config: plugin name → absolute module file), which is how a
+/// plugin outside the vendored payload gets a name.
+///
+/// Returns the resolved map so callers can report what a specifier became
+/// without repeating the lookup rules.
+export function installModuleResolution({ dir = payloadDir(), extraModules = {} } = {}) {
+  const map = new Map([...payloadModules(dir), ...localModules()]);
+  for (const [name, file] of Object.entries(extraModules)) {
+    map.set(name, pathToFileURL(path.resolve(file)).href);
+  }
+  if (installed) {
+    // Hooks are process-wide and cannot be unregistered per call; re-running
+    // with a different map would leave two resolvers disagreeing about the
+    // same specifier, which is a debugging trap rather than a feature.
+    for (const [name, url] of map) installed.map.set(name, url);
+    return installed.map;
+  }
+
+  const payloadPrefix = pathToFileURL(dir.endsWith(path.sep) ? dir : dir + path.sep).href;
+  const state = { map };
+  registerHooks({
+    resolve(specifier, context, next) {
+      const mapped = state.map.get(specifier);
+      if (mapped !== undefined) return { url: mapped, format: 'module', shortCircuit: true };
+      return next(specifier, context);
+    },
+    // The payload's ESM is `.js` under no `package.json`, so Node's own rules
+    // read it as CommonJS and every `import` in it is a syntax error. The
+    // deno_core loader had no such ambiguity — everything it loaded was a
+    // module — so this is a fact about Node, not about the payload.
+    load(url, context, next) {
+      if (url.startsWith(payloadPrefix)) return next(url, { ...context, format: 'module' });
+      return next(url, context);
+    },
+  });
+  installed = state;
+  return state.map;
+}