@matatbread/matbot-core 0.4.15 → 0.4.17

package/src/registry.ts

@@ -3,7 +3,7 @@ import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
 import { scopedNotifier, askPermissionGate } from '@matatbread/matbot-plugin-api/host';
 import type {
   MatbotPlugin, MatbotMachine, MatbotRuntime, Mounted,
-  ProviderAdapterFactory, StoreFactory,
+  ProviderAdapterFactory,
 } from './plugin.js';
 import { PLUGIN_API_VERSION, unifyServices } from './plugin.js';
 import { makePluginSettings } from './settings.js';
@@ -14,11 +14,9 @@ import type { SettingsDoc } from './settings.js';
 // `FailedPlugin` now lives in plugin-api: `plugin list` reports it, so it is part of that tool's
 // contract, and the contract has to be declarable from a package this one can reach.
 
-// Mutable arrays/maps held in a single object to make _resetRegistry() simple.
 const state = {
   plugins:         [] as MatbotPlugin[],
   providers:       new Map<string, ProviderAdapterFactory>(),
-  storage:         new Map<string, StoreFactory>(),
   toolRegistry:    undefined as ToolRegistry | undefined,
   frontendPlugins:  new Map<string, FrontendInfo>(),  // pluginName → info, written by services.registerFrontend()
   serviceKeys:     new Map<string, string[]>(),  // pluginName → MatbotMachine keys it registered
@@ -114,24 +112,11 @@ export function registerPlugin(plugin: MatbotPlugin): void {
     throw new Error(`Provider "${plugin.name}" is already registered.`);
   }
 
-  for (const type of Object.keys(plugin.storage ?? {})) {
-    if (state.storage.has(type)) {
-      const owner = state.plugins.find(p => p.storage?.[type] !== undefined)?.name ?? '?';
-      throw new Error(
-        `Storage type "${type}" is already registered by "${owner}". ` +
-        `"${plugin.name}" cannot register it again.`,
-      );
-    }
-  }
-
   state.plugins.push(plugin);
 
   if (plugin.provider !== undefined) {
     state.providers.set(plugin.name, plugin.provider);
   }
-  for (const [type, factory] of Object.entries(plugin.storage ?? {})) {
-    state.storage.set(type, factory);
-  }
 }
 
 // ── Resolution ────────────────────────────────────────────────────────────────
@@ -313,6 +298,9 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
   // own settings — there is no way to name another's.
   const ownSettings = makePluginSettings(services.createStore<SettingsDoc>('settings'), plugin.name);
 
+  // Plugin-scoped notifier, likewise built once. See the `Notifier` member below.
+  const ownNotifier = scopedNotifier(services.Notifier, plugin.name);
+
   // Per-plugin `mounted`: a thin adapter over the host mount table that delivers *this plugin's* scoped
   // machine (and scoped onUnmount) to handlers. The stable `scoped` object reads through the host's
   // re-pointing proxies/registry, so `scoped[key]` is the host's live service by the time a transition
@@ -353,9 +341,11 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
     // being a deliberate read of the concrete gate at that moment.
     get PermissionGate() { return services.PermissionGate; },
     // Everything this plugin publishes is attributed to it by default — the notification analogue of
-    // stamping `pluginName` on its tools. Reads through the host's swap proxy, so a registered
-    // distributed Notifier takes effect for a plugin that captured this in setup().
-    get Notifier() { return scopedNotifier(services.Notifier, plugin.name); },
+    // stamping `pluginName` on its tools. Wrapped ONCE per plugin (below), not per property read: this
+    // was a getter, so every `services.Notifier.notify(...)` minted a fresh three-method object. Swap
+    // safety is unaffected, because what is wrapped is the host's capture-safe proxy — both hosts put
+    // that stable object on the machine — so a registered distributed Notifier still takes effect.
+    Notifier: ownNotifier,
     tools: {
       register:      registerTool,
       remove:        (name: string) => services.tools.remove(name),
@@ -379,11 +369,12 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
       build:          (ctx)          => services.systemContext.build(ctx),
       parts:          (ctx)          => services.systemContext.parts(ctx),
     },
+    // Attributed only once the registration has succeeded: a key recorded for a register() that threw
+    // would make unload unregister a service this plugin never held — for a swap-member, reverting
+    // someone else's.
     async register(key, svc) {
-      const keys = state.serviceKeys.get(plugin.name) ?? [];
-      keys.push(key as string);
-      state.serviceKeys.set(plugin.name, keys);
       await services.register(key, svc);
+      recordServiceKey(plugin.name, key as string);
     },
     registerFrontend(info) {
       state.frontendPlugins.set(plugin.name, info);
@@ -420,29 +411,51 @@ export async function unloadPlugin(pluginName: string, services: MatbotMachine):
   state.systemContextPlugins.delete(pluginName);
 
   if (plugin.provider !== undefined) state.providers.delete(plugin.name);
-  for (const type of Object.keys(plugin.storage   ?? {})) state.storage.delete(type);
 
   state.frontendPlugins.delete(pluginName);
 
   state.plugins.splice(idx, 1);
   services.Notifier.notify({ kind: RegistryChangeKind, source: 'plugins', registry: 'plugins', name: pluginName, operation: 'removed' });
-  await Promise.race([
-    plugin.teardown?.(),
-    new Promise<void>((_, reject) => setTimeout(() => reject(new Error(`Teardown timeout for plugin ${pluginName}`)), 10000))
-  ]);
+  await boundedTeardown(plugin);
   return true;
 }
 
-/** Run each plugin's teardown() in reverse-registration order. Errors are logged, not thrown. */
+/** How long one plugin's teardown() may take before it is abandoned. */
+const TEARDOWN_TIMEOUT_MS = 10_000;
+
+// The one teardown both paths use, so a runtime unload and process exit cannot drift apart on the budget.
+// The timer is cleared however the race settles: left dangling it outlived every SUCCESSFUL teardown,
+// holding the event loop open for the rest of its budget — so `plugin unload` followed by exit sat there
+// with nothing to wait for.
+async function boundedTeardown(plugin: MatbotPlugin): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      plugin.teardown?.(),
+      new Promise<void>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`Teardown timeout for plugin ${plugin.name}`)), TEARDOWN_TIMEOUT_MS);
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/**
+ * Run each plugin's teardown() in reverse-registration order, one at a time, each within the same budget
+ * as {@link unloadPlugin}. Errors and timeouts are logged, not thrown, and do not stop the rest.
+ *
+ * Sequential and reversed because a plugin loaded later may depend on a service an earlier one provides,
+ * and must be able to flush through it before it closes. Bounded because a sequential loop is otherwise
+ * held hostage by one teardown that never settles — and this runs on the way to process exit.
+ */
 export async function teardownPlugins(): Promise<void> {
-  // Reverse once and keep it: indexing the *unreversed* array to name a result reported the wrong
-  // plugin for every failure but the middle one.
-  const ordered = [...state.plugins].reverse();
-  const results = await Promise.allSettled(ordered.map(plugin => plugin.teardown?.()));
-  results.forEach((result, i) => {
-    if (result.status === 'rejected') {
-      console.error(`[matbot] teardown error in plugin "${ordered[i]?.name}":`, result.reason);
+  for (const plugin of [...state.plugins].reverse()) {
+    try {
+      await boundedTeardown(plugin);
+    } catch (err) {
+      console.error(`[matbot] teardown error in plugin "${plugin.name}":`, err);
     }
-  });
+  }
 }
 

package/src/runner.ts

@@ -1,15 +1,15 @@
 import type {
   Session, Message, MessageContent, ModelContent, Usage, UsageSite, ProviderMeta, TruncatedToolResult,
   TurnEvent, RunConfig, ProviderAdapter, ProviderConfig,
-  Tool, ToolRegistry, ToolContext, Store, FileStore, MediaStore, SystemContextRegistry, Vault, PromptFn, FormField,
+  Tool, ToolRegistry, ToolContext, Store, FileStore, MediaStore, SystemContextRegistry, Vault, PromptFn,
   PermissionGate,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
 import type { ToolPresenter } from '@matatbread/matbot-plugin-api';
-import { recordSpan, recordUsage, withUsageSite } from '@matatbread/matbot-plugin-api/host';
+import { recordSpan, recordUsage, withUsageSite, scopeIterable } from '@matatbread/matbot-plugin-api/host';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
-import { foldOntoUserTurn, bindPluginOps, bindGate } from '@matatbread/matbot-plugin-api';
+import { foldOntoUserTurn, bindPluginOps, bindGate, defaultingPrompt } from '@matatbread/matbot-plugin-api';
 import { addUsage } from './usage.js';
 import { MEDIA_RESIDENCY_BYTES, resolveSessionMedia } from './media.js';
 
@@ -17,24 +17,12 @@ import { MEDIA_RESIDENCY_BYTES, resolveSessionMedia } from './media.js';
 // runner is itself an async generator, so it suspends at every `yield` and resumes under the consumer's
 // context, losing any scope entered around the loop body. Scoping each `next()` instead means the
 // tool's body — and anything it kicks off while running — always resumes under its own site.
-function siteScoped<T>(site: UsageSite, src: AsyncIterable<T>): AsyncIterable<T> {
-  return {
-    [Symbol.asyncIterator]: () => {
-      const it = src[Symbol.asyncIterator]();
-      return {
-        next:  ()  => withUsageSite(site, () => it.next()),
-        ...(it.return ? { return: (v?: never) => withUsageSite(site, () => it.return!(v)) } : {}),
-        ...(it.throw  ? { throw:  (e?: unknown) => withUsageSite(site, () => it.throw!(e))  } : {}),
-      };
-    },
-  };
-}
+//
+// `scopeIterable` is the per-pull wrap `runAs` also uses for the principal. It wraps the iterator rather
+// than replacing it, so a class-based tool iterator keeps its own members, prototype and `instanceof`.
+const siteScoped = <T>(site: UsageSite, src: AsyncIterable<T>): AsyncIterable<T> =>
+  scopeIterable(src, f => withUsageSite(site, f));
 
-// Substituted for an errored tool result when the turn was aborted (e.g. a mid-turn steer interrupt):
-// the tool was cut off, not genuinely faulty, and the raw abort reason ("Error: steer") is a leaked
-// internal token that reads as a real failure. A steer's continuation turn is the one place a model
-// reads this, so the wording tells it the call was interrupted and leaves re-running to its judgement —
-// deliberately NOT "re-run it", so a side-effecting tool isn't reflexively repeated.
 // Creator of the marker recording that a provider cut a response short. Marker-role, so it is durable
 // and visible to a reader while elided from every submission: the model's own text is already truncated
 // in the transcript, and a block telling it so invites narrating the cut-off rather than continuing.
@@ -45,6 +33,19 @@ const TRUNCATION_CREATOR = 'matbot-truncation';
 const abortReason = (signal: AbortSignal): string =>
   typeof signal.reason === 'string' ? signal.reason : 'user-abort';
 
+/**
+ * A thrown value as a turn-terminal message, with its `cause` appended when it has one.
+ *
+ * A `throw` carries anything, so this narrows before reaching for `cause`: `'cause' in e` throws
+ * TypeError on a primitive, which made the catch handler ITSELF throw for a provider that rejected
+ * with a string — escaping the generator and skipping the `end()` commit that the branch calling this
+ * exists to perform. The one place in this package that took `any` rather than narrow.
+ */
+const errorText = (e: unknown): string => {
+  const cause = typeof e === 'object' && e !== null && 'cause' in e ? (e as { cause?: unknown }).cause : undefined;
+  return cause ? `${String(e)} (${String(cause)})` : String(e);
+};
+
 /** How long a tool executor may keep the turn alive AFTER the turn was aborted, before the runner stops
  *  reading it. An abort must abort: any executor can fail to end — a child process whose stdout was
  *  inherited by an orphan, a generator awaiting something that never settles, a bridged remote that went
@@ -73,6 +74,11 @@ function abandonDeadline(signal: AbortSignal, ms: number): { wait: Promise<typeo
   };
 }
 
+// Substituted for an errored tool result when the turn was aborted (e.g. a mid-turn steer interrupt):
+// the tool was cut off, not genuinely faulty, and the raw abort reason ("Error: steer") is a leaked
+// internal token that reads as a real failure. A steer's continuation turn is the one place a model
+// reads this, so the wording tells it the call was interrupted and leaves re-running to its judgement —
+// deliberately NOT "re-run it", so a side-effecting tool isn't reflexively repeated.
 const INTERRUPTED_TOOL_RESULT = {
   error: 'Tool call interrupted before completion — the turn was interrupted while it was running. It may not have run to completion, and any side effect may or may not have occurred. Re-run it only if you still need its result.',
 } as const;
@@ -137,12 +143,9 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
   const { config, provider, providerConfig, store, signal } = opts;
   const tools   = opts.tools   ?? new Map<string, Tool>();
   const hookReg = opts.hooks   ?? new HookRegistry();
-  const promptFn: PromptFn = opts.prompt ?? (((p: string | FormField, def?: string): Promise<string> => {
-    const fallback = typeof p === 'string' ? def : p.default;
-    if (fallback !== undefined) return Promise.resolve(fallback);
-    const label = typeof p === 'string' ? p : p.label;
-    return Promise.reject(new Error(`Non-interactive context: cannot prompt for "${label}"`));
-  }) as PromptFn);
+  // The stand-in answers with a field's own default where it has one — which is precisely why the gate
+  // below is handed `opts.prompt` raw instead (see bindGate).
+  const promptFn: PromptFn = opts.prompt ?? defaultingPrompt;
   const vault: Vault = opts.vault ?? {
     async createSecret() { throw new Error('No vault configured'); },
     async writeSecret()  { throw new Error('No vault configured'); },
@@ -408,7 +411,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
             break;
         }
       }
-    } catch (e: any) {
+    } catch (e: unknown) {
       // A provider call cancelled by an in-situ restart (callAc, not the turn signal) is expected — fall
       // through to the restart below rather than surfacing it as a turn abort or an error.
       if (restart || (callAc.signal.aborted && !signal.aborted)) {
@@ -436,7 +439,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         // carries no session (a failure is not a transcript), so this yields the terminal itself rather
         // than the session — but it commits first, exactly like every other exit.
         bookRound();
-        yield* end({ type: 'error', error: String(e) + (('cause' in e && e.cause) ? ' ('+String(e.cause)+')' : '' ), traceId });
+        yield* end({ type: 'error', error: errorText(e), traceId });
         return;
       }
     }