@matatbread/matbot-core 0.4.4 → 0.4.5

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.4",
+  "version": "0.4.5",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.4"
+    "@matatbread/matbot-plugin-api": "^0.4.5"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/index.ts

@@ -28,7 +28,7 @@ export {
   unifyServices, forwardingProxy, makeSwappable, singleTurnRequest, createMountTable,
   createBroadcaster, subscribable, createNotifier, scopedNotifier,
   installPrincipalCarrier, enterPrincipal, createConstantPrincipalCarrier,
-  contextSwitch, machineBusy, quiesced, onContextQuiesce, flushIfQuiescent,
+  contextSwitch, machineBusy, quiesced, onContextQuiesce, scheduleAtEdge,
   installUsageCarrier, createSerialUsageCarrier, recordUsage, recordSpan, currentUsageSink,
   currentUsageScope, currentUsageSite, withUsageScope, withUsageSite,
 } from '@matatbread/matbot-plugin-api/host';

package/src/loader.ts

@@ -62,8 +62,17 @@ let freshSeq = 0;
  *   - `name` — the canonical plugin name, when the host has already derived it (e.g. by
  *     reading the resolved package.json). Bypasses `resolver.identify(spec)` — necessary
  *     because `spec` (a remote URL, a versioned npm range) may not itself identify the name.
+ *   - `version` — the package.json `version`, when the host has already read it. Same reason as
+ *     `name`: `resolver.version(spec)` starts from `spec`, which for a bare name, a URL or a
+ *     version range locates no manifest at all.
  *   - `runtimes` — the package.json `matbotRuntime`, when the host has already read it; used
  *     for the pre-import gate in place of `resolver.runtimes(spec)`.
+ *   - `notes` — what the host noticed while resolving that would explain a failure but does not
+ *     itself cause one: a dependency it could not satisfy, an import shape it cannot fetch, a fetch
+ *     that failed before the import was even attempted. Appended to any failure recorded for this
+ *     spec, because the failure that surfaces is downstream of the cause (a missing dependency
+ *     arrives as ERR_MODULE_NOT_FOUND naming a file) — and dropped entirely if the plugin loads,
+ *     since a host cannot tell an unused declaration from a fatal one.
  *
  * @param bustCache When true, the URL imported for each specifier gets a unique
  *   `${FRESH_PARAM}` query stamp appended before importing — either a host-pre-resolved
@@ -91,13 +100,22 @@ let freshSeq = 0;
  *   only as a confusing empty-result error downstream — fail loudly with the reason instead.
  */
 export async function loadPlugins(
-  specifiers: readonly (string | { spec: string; importSpec?: string; name?: string; runtimes?: readonly Runtime[] })[],
+  specifiers: readonly (string | { spec: string; importSpec?: string; name?: string; version?: string; runtimes?: readonly Runtime[]; notes?: readonly string[] })[],
   services:   MatbotMachine,
   bustCache = false,
   prompt?:    PromptFn,
   onLoadError: 'skip' | 'throw' = 'skip',
 ): Promise<MatbotPlugin[]> {
-  const reqs = specifiers.map(s => (typeof s === 'string' ? { spec: s } : s) as { spec: string; importSpec?: string; name?: string; runtimes?: readonly Runtime[] });
+  const reqs = specifiers.map(s => (typeof s === 'string' ? { spec: s } : s) as { spec: string; importSpec?: string; name?: string; version?: string; runtimes?: readonly Runtime[]; notes?: readonly string[] });
+
+  // A reason reaching a user, decorated with what the host noticed while resolving this spec. The
+  // failure a load reports is usually downstream of its cause, and the host is the only layer that
+  // saw the cause.
+  const notesBySpec = new Map(reqs.filter(r => r.notes !== undefined && r.notes.length > 0).map(r => [r.spec, r.notes!]));
+  const withNotes = (spec: string, reason: string): string => {
+    const notes = notesBySpec.get(spec);
+    return notes === undefined ? reason : `${reason}\nNoted while resolving it:\n${notes.map(n => `  - ${n}`).join('\n')}`;
+  };
   if (bustCache) {
     console.debug(
       `[matbot] cache-bust requested for ${specifiers.length} plugin(s); the entry is re-evaluated, ` +
@@ -118,9 +136,9 @@ export async function loadPlugins(
     ),
   );
 
-  const toLoad: { spec: string; importSpec: string; resolvedUrl: string; name?: string; runtimes?: readonly Runtime[] }[] = [];
+  const toLoad: { spec: string; importSpec: string; resolvedUrl: string; name?: string; version?: string; runtimes?: readonly Runtime[] }[] = [];
   for (let i = 0; i < reqs.length; i++) {
-    const { spec, importSpec, name } = reqs[i]!;
+    const { spec, importSpec, name, version } = reqs[i]!;
     const runtimes = declared[i];
     if (runtimes !== undefined && runtimes.length > 0 && !runtimes.includes(CURRENT_RUNTIME)) {
       if (onLoadError === 'throw') {
@@ -139,6 +157,7 @@ export async function loadPlugins(
       // live plugin set). Falls back to the bare spec when the host pre-resolved nothing.
       resolvedUrl: importSpec ?? spec,
       ...(name     !== undefined ? { name }     : {}),
+      ...(version  !== undefined ? { version }  : {}),
       ...(runtimes !== undefined ? { runtimes } : {}),
     });
   }
@@ -157,7 +176,8 @@ export async function loadPlugins(
   // from a `'load'` failure (import rejection — a bad path, a syntax error). Only the former is
   // permanently-not-a-plugin: it throws NotAPluginError so the `add` flow can roll back the config
   // write, where an import failure may be a fixable typo and is left in config.
-  const failLoad = (spec: string, reason: string, kind: 'load' | 'shape' = 'load'): void => {
+  const failLoad = (spec: string, rawReason: string, kind: 'load' | 'shape' = 'load'): void => {
+    const reason = withNotes(spec, rawReason);
     if (onLoadError === 'throw') throw kind === 'shape' ? notAPluginError(spec, reason) : new Error(reason);
     console.warn(`[matbot] Skipping plugin "${spec}": ${reason}`);
     recordFailedPlugin({ specifier: spec, error: reason });
@@ -216,7 +236,11 @@ export async function loadPlugins(
     const name     = toLoad[i]!.name ?? (services.resolver !== undefined ? await services.resolver.identify(spec) : defaultIdentify(spec));
     const source   = sourceOf(spec);
     const runtimes = toLoad[i]!.runtimes;
-    const version  = services.resolver?.version !== undefined ? await services.resolver.version(spec) : undefined;
+    // Like `name`: the host's own reading wins, because it read the package.json it actually
+    // imported. `resolver.version(spec)` cannot — `spec` may be a bare name, a URL or a version
+    // range, none of which locate a manifest, so a plugin configured by name reported no version.
+    const version  = toLoad[i]!.version
+      ?? (services.resolver?.version !== undefined ? await services.resolver.version(spec) : undefined);
     const plugin: MatbotPlugin = {
       ...spec_obj,
       name,
@@ -248,7 +272,7 @@ export async function loadPlugins(
       // Graceful but not silent: record the setup failure (skip mode — the boot batch) so the `plugin`
       // tool and web UI can show it. Explicit single loads (`onLoadError: 'throw'`) surface the error to
       // the caller directly, so they are not added to the persistent failed list.
-      if (onLoadError === 'skip') recordFailedPlugin({ specifier: spec, name: plugin.name, error: reason });
+      if (onLoadError === 'skip') recordFailedPlugin({ specifier: spec, name: plugin.name, error: withNotes(spec, reason) });
       // Roll back partial registration so a failed load leaves no ghost state. setupPlugin
       // can throw after the plugin is already in the registry with some of its tools / hooks /
       // services / provider / storage wired (a wrong-platform plugin touching a missing

package/src/session-runner.ts

@@ -9,7 +9,7 @@ import type { HookRegistry } from './hooks.js';
 import type { ToolTypeIndex, ToolPresenter } from '@matatbread/matbot-plugin-api';
 import { appendMessage, createMessage } from './session.js';
 import { isReadOnlyError, foldOntoUserTurn, lastUserIndex, runAs } from '@matatbread/matbot-plugin-api';
-import { machineBusy, quiesced, withUsageScope } from '@matatbread/matbot-plugin-api/host';
+import { machineBusy, withUsageScope } from '@matatbread/matbot-plugin-api/host';
 import { runSession } from './runner.js';
 
 export interface SessionRunnerDeps {
@@ -264,12 +264,13 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
     // usage flushes at, for the same reason. `machineBusy` releases on every exit including a throw,
     // so no early return out of the loop below can leave the machine held.
     //
-    // Wait out any deferred work still settling BEFORE holding: a flusher that rewrites this very
-    // session (a `session_edit` deferred out of the last turn) must finish before this turn reads its
-    // copy, or the read would take the pre-edit document and the write-back below would put it back.
-    // The edge is only reachable while nothing holds the machine, so the wait comes first and the
-    // hold second — the reverse would deadlock on an edge this pump is itself preventing.
-    return quiesced().then(() => machineBusy(async () => {
+    // It also waits for deferred work to land before taking the hold, which is why there is no separate
+    // `quiesced()` here any more: a flusher that rewrites this very session (a `session_edit` deferred
+    // out of the last turn) finishes before the loop below reads its copy, or the read would take the
+    // pre-edit document and the write-back would put it back. That wait used to be spelled at this call
+    // site, and spelling it here made it something the next caller of `machineBusy` could omit without
+    // any symptom — so it moved inside the hold it guards.
+    return machineBusy(async () => {
     try {
       while (s.queue.length > 0) {
         // Per-submission concat: the head always runs; if the head is a concat submission it absorbs
@@ -545,7 +546,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
       notify(s, { type: 'idle', sessionId: id });
       maybeCleanup(id, s);
     }
-    }));
+    });
   };
 
   return {