@matatbread/matbot-core 0.4.20 → 0.4.21

package/package.json

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

package/src/assemble.ts

@@ -194,12 +194,19 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
     }),
   };
   const serviceRegistry = new Map<string, unknown>(Object.entries(seed));
-  // The validator lookup is late-bound and read per call: one is registered by a plugin long after the
-  // builtins are seeded, and may be unloaded again. It wraps the executor, so every door — the runner,
-  // `POST /tools/:name`, `invokeTool` — is covered by one wrapper rather than a hook on the model's path.
-  const tools = new ToolRegistryImpl(opts.builtinTools, notifier,
-    () => serviceRegistry.get('ToolCallValidator') as ToolInputValidator | undefined);
+  // Validation wraps the executor, so every door — the runner, `POST /tools/:name`, `invokeTool` — is
+  // covered by one wrapper. It asks the `validate` hooks per call: validators arrive long after the
+  // builtins are seeded, and may be unloaded again.
   const hooks = new HookRegistry();
+  // The `ToolCallValidator` service is its predecessor, still honoured: consulted as one more hook, so a
+  // validator registered there is combined with the rest by the same rule. Host-owned (no `pluginName`),
+  // so no plugin's unload removes it; the key is read per call.
+  hooks.register({
+    on: 'validate',
+    handler: ctx => (serviceRegistry.get('ToolCallValidator') as ToolInputValidator | undefined)?.validateToolCall(ctx.tool, ctx.parameters),
+  });
+  const tools = new ToolRegistryImpl(opts.builtinTools, notifier,
+    (tool, parameters, signal) => hooks.runValidate({ tool, parameters, signal }));
   const systemContext = new SystemContextRegistryImpl();
 
   // The installation's permission policy. Deliberately NOT behind a forwardingProxy: the documented way

package/src/index.ts

@@ -22,7 +22,7 @@ export { applyResolve, applyCreateSecret, assertStorableKey, unreferenceableKey,
 // The `provider update` patch policy, alongside the vault's: written once in plugin-api so the hosts
 // that apply one cannot differ on what a patch MEANS, and re-exported here so an app needs no direct
 // plugin-api dependency to get it.
-export { applyProviderPatch, patchedFields } from '@matatbread/matbot-plugin-api';
+export { applyProviderPatch, movedCredentialKeys, patchedFields, checkProviderModel, modelListed, closestIds } from '@matatbread/matbot-plugin-api';
 export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind, SessionAppendKind, FUNCTION_TIMEOUT, permitted, refused, refusalMessage } from '@matatbread/matbot-plugin-api';
 // The canonical `type: 'confirm'` answers. Same reason as the patch policy above: an app implementing a
 // PromptFn (or a test standing one in) has to speak them, and must not hard-code the rendered label.

package/src/registry.ts

@@ -20,7 +20,8 @@ const state = {
   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
-  hookPlugins:        new Set<string>(),         // plugins that registered at least one hook
+  serviceLayers:   new Map<string, { owner: string; value: unknown }[]>(),  // key → plugin registrations, oldest first
+  hookPlugins:       new Set<string>(),         // plugins that registered at least one hook
   systemContextPlugins: new Set<string>(),       // plugins that registered a system-context contributor
   lifecycles:      new Map<string, AbortController>(),  // pluginName → "this plugin is loaded" signal, aborted on unload
   failedPlugins:   [] as FailedPlugin[],         // plugins the loader skipped, keyed by specifier (last failure wins)
@@ -122,6 +123,8 @@ export function registerPlugin(plugin: MatbotPlugin): void {
 
 // ── Resolution ────────────────────────────────────────────────────────────────
 
+const adapterLoads = new Map<string, Promise<MatbotPlugin>>();
+
 export function tryResolveProviderFactory(module: string): ProviderAdapterFactory | undefined {
   return state.providers.get(module);
 }
@@ -156,9 +159,18 @@ export async function instantiateProvider(services: MatbotRuntime, config: Provi
 
   // Not loaded yet — force-load the adapter module on demand (a runtime-contributed profile, or a disabled
   // pre-scan). Warn and return null rather than throw, so one unusable profile can't abort a turn. The next
-  // resolution hits the fast path above via specifier→name, so this loads at most once per adapter module.
+  // resolution hits the fast path above via specifier→name, so this loads at most once per adapter module —
+  // once SETTLED. Calls that arrive while the load is in flight share it: each starting its own lost to
+  // the first on "already registered", and boot is exactly when they arrive together (a skills reindex
+  // analyses every skill at once, all through one provider whose module `plugins:` does not list).
+  const loadKey = name ?? config.module;
+  let loading = adapterLoads.get(loadKey);
+  if (loading === undefined) {
+    loading = services.loadPlugin(config.module).finally(() => adapterLoads.delete(loadKey));
+    adapterLoads.set(loadKey, loading);
+  }
   try {
-    const plugin = await services.loadPlugin(config.module);
+    const plugin = await loading;
     if (plugin.provider === undefined) {
       console.warn(`[matbot] provider "${config.name}": module "${config.module}" loaded but registered no adapter.`);
       return null;
@@ -215,10 +227,46 @@ export function getRegisteredServiceKeys(pluginName: string): readonly string[]
  * register() that would normally record the key. Recording it makes the boot-opened backend unload-equal
  * to a runtime register(): unloadPlugin() then calls unregister() for it, reverting to the host base.
  */
-export function recordServiceKey(pluginName: string, key: string): void {
+export function recordServiceKey(pluginName: string, key: string, value?: unknown): void {
   const keys = state.serviceKeys.get(pluginName) ?? [];
   if (!keys.includes(key)) keys.push(key);
   state.serviceKeys.set(pluginName, keys);
+  // Out of band means it was in place before anything the loader registered, so it goes underneath.
+  const layers = state.serviceLayers.get(key) ?? [];
+  if (value !== undefined && !layers.some(l => l.owner === pluginName)) state.serviceLayers.set(key, [{ owner: pluginName, value }, ...layers]);
+}
+
+// A displaced StorageBackend is closed by the swap, so there is nothing beneath to reinstate.
+const CLOSED_WHEN_DISPLACED = new Set(['StorageBackend']);
+
+function pushServiceLayer(owner: string, key: string, value: unknown): void {
+  const layers = (state.serviceLayers.get(key) ?? []).filter(l => l.owner !== owner);
+  layers.push({ owner, value });
+  state.serviceLayers.set(key, layers);
+}
+
+/**
+ * Withdraw one plugin's registration of `key`. The registry holds one value per key, so this used to
+ * be a plain `unregister`, which removed whatever was CURRENT — not necessarily this plugin's. Where
+ * plugins stack on a key (a validator or gate that captures the one it displaces and delegates to it),
+ * unloading the one underneath took the one on top with it, and unloading the one on top reverted past
+ * the one it had displaced. Now: withdrawing the current registration reinstates the one it displaced,
+ * withdrawing a displaced one changes nothing visible, and only the last one out reverts to the host.
+ */
+function releaseServiceLayer(services: MatbotMachine, owner: string, key: string): void {
+  const layers = state.serviceLayers.get(key) ?? [];
+  const idx    = layers.findIndex(l => l.owner === owner);
+  if (idx === -1) { services.unregister(key); return; }
+  const wasCurrent = idx === layers.length - 1;
+  layers.splice(idx, 1);
+  if (wasCurrent && CLOSED_WHEN_DISPLACED.has(key)) layers.length = 0;
+  if (layers.length === 0) state.serviceLayers.delete(key);
+  if (!wasCurrent) return;
+  const beneath = layers[layers.length - 1];
+  if (beneath === undefined) { services.unregister(key); return; }
+  // The base register applies its value synchronously, before its returned promise settles.
+  void services.register(key as never, beneath.value as never).catch((e: unknown) =>
+    console.error(`[matbot] Could not reinstate "${key}" from "${beneath.owner}":`, e instanceof Error ? e.message : e));
 }
 
 /** Plugins that registered at least one hook in setup(). */
@@ -353,6 +401,7 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
       resolve:       (name: string) => services.tools.resolve(name),
       list:          ()             => services.tools.list(),
       removeByPlugin:(name: string) => services.tools.removeByPlugin(name),
+      validate:      async (name: string, parameters: unknown) => services.tools.validate?.(name, parameters),
     },
     hooks: {
       register(hook: Hook) {
@@ -376,6 +425,12 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
     async register(key, svc) {
       await services.register(key, svc);
       recordServiceKey(plugin.name, key as string);
+      pushServiceLayer(plugin.name, key as string, svc);
+    },
+    unregister(key: string) {
+      releaseServiceLayer(services, plugin.name, key);
+      const keys = state.serviceKeys.get(plugin.name);
+      if (keys !== undefined) state.serviceKeys.set(plugin.name, keys.filter(k => k !== key));
     },
     registerFrontend(info) {
       state.frontendPlugins.set(plugin.name, info);
@@ -405,7 +460,7 @@ export async function unloadPlugin(pluginName: string, services: MatbotMachine):
   state.lifecycles.delete(pluginName);
 
   for (const key of state.serviceKeys.get(pluginName) ?? []) {
-    services.unregister(key);
+    releaseServiceLayer(services, pluginName, key);
   }
   state.serviceKeys.delete(pluginName);
   state.hookPlugins.delete(pluginName);

package/src/tool-registry.ts

@@ -1,32 +1,19 @@
 import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
-import type { Tool, ToolRegistry, Notifier, ToolContext, ToolEvent } from './types.js';
+import type { Tool, ToolRegistry, Notifier, ToolContext, ToolEvent, ToolInputError } from './types.js';
 
 /**
- * Structural contract for a registered input validator — duck-typed, never imported, exactly as
- * `ProfileDirectory` is: core must not depend on whichever plugin implements it (today
- * `@matatbread/matbot-tool-types`, from a tool's `ToolContract` params type), and the shape is the
- * whole agreement. `undefined` means NO OPINION — no contract for this tool, or one that cannot be
- * honestly validated — and is never read as "valid".
+ * The shape of the `ToolCallValidator` service — the single-valued predecessor of the `validate` hook,
+ * still consulted as one more opinion beside the hooks so a validator written against it keeps working.
+ * `undefined` means NO OPINION and is never read as "valid".
+ *
+ * @deprecated Register a `validate` hook instead. Removed in 0.5.0, with `ToolCallValidator`.
  */
 export interface ToolInputValidator {
   validateToolCall(tool: string, parameters: unknown): Promise<ToolInputError[] | undefined>;
 }
 
-/**
- * One rejected field. `path` is dotted, as a caller would WRITE the access (`.items[0].name`) rather
- * than as JSON Pointer — the reader is either a model repairing its own call or a developer looking at
- * a 422, and both write dots. `.` alone is the whole value.
- *
- * `value` is what was actually supplied there, and is what makes the difference between a message a
- * model can act on and one it has to guess at. Optional because a validator may not have it, and
- * `undefined` specifically means ABSENT: JSON carries no undefined, so there is nothing to show for a
- * missing property beyond saying it is missing.
- */
-export interface ToolInputError {
-  path:   string;
-  message: string;
-  value?: unknown;
-}
+/** Judges one call: every `validate` hook, and the `ToolCallValidator` service if one is registered. */
+export type ToolCallJudge = (tool: string, parameters: unknown, signal: AbortSignal) => Promise<ToolInputError[] | undefined>;
 
 /** Cap on the rendered value. Long enough to identify what was sent, short enough that a base64
  *  attachment or a large document cannot turn one rejected field into the bulk of a turn's context. */
@@ -56,17 +43,18 @@ function formatError(e: ToolInputError): string {
 }
 
 /**
- * Declared HERE, by the consumer, rather than by any of the plugins that implement it — `json-validation`
- * (against `inputSchema`) and `ts-validation` (against the `ToolContract` type) both register this key,
- * and two plugins declaring one key must declare it identically or the merge is a TS2717 in a file
- * neither owns. Core reads it, so core names it.
+ * Declared HERE, by the consumer, rather than by a plugin that implements it: two plugins declaring one
+ * key must declare it identically or the merge is a TS2717 in a file neither owns. Core reads it, so core
+ * names it.
  *
- * Exactly one is active, since the registry holds one value per key. A validator that loads over another
- * should capture the one it displaces and delegate to it when it has no opinion of its own — which is
- * how the typed and schema validators compose rather than shadow each other.
+ * Superseded by the `validate` hook, which matbot's own validators now use. A service key holds one value,
+ * so a second validator had to capture the first and delegate to it, which made the pair depend on load
+ * order and on each other. Still consulted, as one more opinion, so a validator registered here works.
  */
 declare module '@matatbread/matbot-plugin-api' {
   interface MatbotServices {
+    /** @deprecated Register a `validate` hook instead: several co-exist, where this key holds one. Still
+     *  consulted, as one more opinion beside the hooks; removed in 0.5.0. */
     ToolCallValidator?: ToolInputValidator;
   }
 }
@@ -80,32 +68,32 @@ declare module '@matatbread/matbot-plugin-api' {
 export const TOOL_INPUT_INVALID = 422;
 
 /**
- * Validation belongs at the executor, not in a `toolcall` hook, because the hook is a RUNNER channel:
+ * Validation belongs at the executor, not in a `toolcall` hook, because that hook is a RUNNER channel:
  * it guards the model's path and nothing else. `POST /tools/:name` and `invokeTool` both call
- * `tool.executor.execute` directly and fire no hooks, so a hook leaves two doors open and invites the
- * per-door duplication that then drifts. Wrapping here is the one place every door already passes
- * through.
+ * `tool.executor.execute` directly and fire no runner hooks, so a runner hook leaves two doors open and
+ * invites the per-door duplication that then drifts. Wrapping here is the one place every door already
+ * passes through — which is why the `validate` hook channel is dispatched from here, not by the runner.
  *
  * Wrapped at REGISTRATION rather than at `resolve`, so there is exactly one wrapper per tool and
  * `resolve(x) === resolve(x)` still holds.
  *
- * The validator is looked up per CALL, not captured: it may be registered long after the tools are
- * (plugin order), and it may be unloaded. No validator ⇒ the call passes straight through, so core
- * mandates no validation — it only honours one that is registered. The cost when a validator IS
+ * Validators are consulted per CALL, not captured: they are registered long after the tools are, and
+ * may be unloaded. None with an opinion ⇒ the call passes straight through, so core mandates no
+ * validation — it only honours what is registered. The cost when a validator IS
  * present is one generator frame plus a structural check (measured in the tens of nanoseconds against
  * tool work measured in milliseconds); the deliberate trade is that an INTERNAL call is validated too,
  * though a statically-typed call site should already be sound. That is not pure waste: `invokeTool`
  * with a dynamic name, a trigger's `invoke.params` (typed `object`) and a compiled skill's payload are
  * all internal callers whose input no compiler has checked.
  */
-function validatingTool(tool: Tool, lookup: () => ToolInputValidator | undefined): Tool {
+function validatingTool(tool: Tool, judge: ToolCallJudge): Tool {
   const inner = tool.executor;
   return {
     ...tool,
     executor: {
       execute(input: unknown, ctx: ToolContext): AsyncIterable<ToolEvent> {
         return (async function* () {
-          const errs = await lookup()?.validateToolCall(tool.name, input);
+          const errs = await judge(tool.name, input, ctx.signal);
           if (errs !== undefined && errs.length > 0) {
             const detail = errs.map(formatError).join('; ');
             yield { type: 'error', message: `Invalid input for tool "${tool.name}": ${detail}`, code: TOOL_INPUT_INVALID };
@@ -125,18 +113,22 @@ export class ToolRegistryImpl implements ToolRegistry {
   // proxy, not a resolved impl, so a later register('Notifier', …) takes effect here too. Optional: a
   // registry built without one (tests) simply announces nothing.
   private readonly notifier: Notifier | undefined;
-  // Host-injected, late-bound: a validator is typically registered by a plugin long after the builtin
-  // tools are seeded, so this is read per call rather than resolved here.
-  private readonly validator: (() => ToolInputValidator | undefined) | undefined;
+  // Host-injected, and consulted per call: validators are registered by plugins long after the builtin
+  // tools are seeded, and may be unloaded again.
+  private readonly judge: ToolCallJudge | undefined;
 
-  constructor(initial?: Iterable<Tool>, notifier?: Notifier, validator?: () => ToolInputValidator | undefined) {
-    this.validator = validator;
+  constructor(initial?: Iterable<Tool>, notifier?: Notifier, judge?: ToolCallJudge) {
+    this.judge = judge;
     if (initial !== undefined) for (const tool of initial) this.tools.set(tool.name, this.guard(tool));
     this.notifier = notifier;
   }
 
   private guard(tool: Tool): Tool {
-    return this.validator === undefined ? tool : validatingTool(tool, this.validator);
+    return this.judge === undefined ? tool : validatingTool(tool, this.judge);
+  }
+
+  async validate(name: string, parameters: unknown): Promise<ToolInputError[] | undefined> {
+    return this.judge?.(name, parameters, new AbortController().signal);
   }
 
   private announce(name: string, operation: 'added' | 'removed', pluginName?: string): void {