@matatbread/matbot-core 0.3.7 → 0.3.8

package/package.json

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

package/src/index.ts

@@ -19,6 +19,7 @@ export { unifyServices }      from '@matatbread/matbot-plugin-api';
 export { forwardingProxy, makeSwappable, singleTurnRequest, createMountTable } from '@matatbread/matbot-plugin-api';
 // Observation-stream primitives (broadcaster + the bare-subscribe wrapper); the host wires `mounted`.
 export { createBroadcaster, subscribable } from '@matatbread/matbot-plugin-api';
+export { createNotifier, scopedNotifier, notifyingStore, ItemChangeKind, RegistryChangeKind } from '@matatbread/matbot-plugin-api';
 export type { Subscribable, Broadcaster } from '@matatbread/matbot-plugin-api';
 // Ambient security principal: interface is a type (carried by `export type *`); these are the values.
 export {

package/src/loader.ts

@@ -1,7 +1,7 @@
 import type { MatbotPlugin, MatbotPluginSpec, MatbotMachine, PluginSource, Runtime } from './plugin.js';
 import type { PromptFn } from './types.js';
 import { incompatibleRuntimeError, notAPluginError } from '@matatbread/matbot-plugin-api';
-import { registerPlugin, setupPlugin, unloadPlugin, recordFailedPlugin, clearFailedPlugin } from './registry.js';
+import { registerPlugin, setupPlugin, unloadPlugin, recordFailedPlugin, clearFailedPlugin, announcePluginLoaded } from './registry.js';
 
 /**
  * The runtime this process is executing in. Detected the same way the rejected-import branch below
@@ -235,6 +235,9 @@ export async function loadPlugins(
     try {
       registerPlugin(plugin);
       registered = true;
+      // Announced at registration, not after setup: a setup throw rolls back through unloadPlugin, which
+      // announces the removal — so an observer sees a matched add/remove pair rather than a bare removal.
+      announcePluginLoaded(services, plugin.name);
       await setupPlugin(plugin, services, prompt);
       loaded.push(plugin);
       // Successful (re)load: a fixed plugin drops off the failed list (reload runs this same path).

package/src/registry.ts

@@ -1,5 +1,5 @@
-import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, PluginRegistryEvent, ProviderAdapter, ProviderConfig } from './types.js';
-import { createBroadcaster } from '@matatbread/matbot-plugin-api';
+import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, ProviderAdapter, ProviderConfig } from './types.js';
+import { scopedNotifier, RegistryChangeKind } from '@matatbread/matbot-plugin-api';
 import type {
   MatbotPlugin, MatbotMachine, MatbotRuntime, Mounted,
   ProviderAdapterFactory, StoreFactory,
@@ -34,14 +34,13 @@ const state = {
   overwriteAllTools: undefined as boolean | undefined,  // persisted "overwrite on collision, this install" choice, loaded lazily
 };
 
-// Read-only observation of plugin load/unload, for consumers that key off plugin presence (e.g. the
-// web plugins panel refreshing live when a backend restores a plugin set out of band). Module-level,
-// not in `state` — it owns subscribers across the registry's lifetime, not per-plugin data.
-const pluginEvents = createBroadcaster<PluginRegistryEvent>();
-
-export async function* watchPlugins(signal?: AbortSignal): AsyncIterable<PluginRegistryEvent> {
-  // Plugin CRUD is global — no origin — so unwrap the envelope to the bare event the panel expects.
-  for await (const { value } of pluginEvents.subscribe(signal)) yield value;
+// Plugin load/unload is announced on the Notifier as a `RegistryChange` with `registry: 'plugins'`, for
+// consumers that key off plugin presence (e.g. the web plugins panel refreshing live when a backend
+// restores a plugin set out of band). It was a module-level broadcaster of its own, which is the same
+// primitive the bus already is. `loaded` is announced by the loader — the only caller of
+// registerPlugin, and the one place holding the machine this registry deliberately doesn't.
+export function announcePluginLoaded(services: MatbotMachine, name: string): void {
+  services.Notifier.notify({ kind: RegistryChangeKind, source: 'plugins', registry: 'plugins', name, operation: 'added' });
 }
 
 // Settings namespace + key under which the user's "overwrite all colliding tools" choice
@@ -150,8 +149,6 @@ export function registerPlugin(plugin: MatbotPlugin): void {
   for (const [type, factory] of Object.entries(plugin.storage ?? {})) {
     state.storage.set(type, factory);
   }
-
-  pluginEvents.emit({ type: 'loaded', name: plugin.name });
 }
 
 // ── Resolution ────────────────────────────────────────────────────────────────
@@ -331,13 +328,16 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
       specifier: plugin.specifier,
       ...(plugin.source !== undefined ? { source: plugin.source } : {}),
     },
+    // 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); },
     tools: {
       register:      registerTool,
       remove:        (name: string) => services.tools.remove(name),
       resolve:       (name: string) => services.tools.resolve(name),
       list:          ()             => services.tools.list(),
       removeByPlugin:(name: string) => services.tools.removeByPlugin(name),
-      watch:         (signal?: AbortSignal) => services.tools.watch(signal),
     },
     hooks: {
       register(hook: Hook) {
@@ -396,7 +396,7 @@ export async function unloadPlugin(pluginName: string, services: MatbotMachine):
   state.frontendPlugins.delete(pluginName);
 
   state.plugins.splice(idx, 1);
-  pluginEvents.emit({ type: 'unloaded', name: pluginName });
+  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))

package/src/storage-base/query/validate.ts

@@ -93,11 +93,11 @@ function validateFilter(f: Filter, ptr: string): void {
   }
 }
 
-const QUERY_KEYS = new Set(['where', 'sort', 'limit', 'cursor']);
+const QUERY_KEYS = new Set(['where', 'sort', 'limit', 'cursor', 'immutable']);
 
 export function validateQuery(q: StoreQuery): void {
   if (q === null || typeof q !== 'object' || Array.isArray(q))
-    throw new StoreQueryError('query must be an object with optional keys: where, sort, limit, cursor', '/', 'MALFORMED');
+    throw new StoreQueryError('query must be an object with optional keys: where, sort, limit, cursor, immutable', '/', 'MALFORMED');
 
   // Reject unknown top-level keys. Without this the envelope is silently permissive: a clause placed
   // under a wrong key (e.g. `filter` instead of `where`, an SQL-ism LLMs reach for) is dropped, the

package/src/tool-registry.ts

@@ -1,26 +1,37 @@
-import type { Tool, ToolRegistry, ToolRegistryEvent } from './types.js';
-import { createBroadcaster } from '@matatbread/matbot-plugin-api';
+import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
+import type { Tool, ToolRegistry, Notifier } from './types.js';
 
 export class ToolRegistryImpl implements ToolRegistry {
   private readonly tools = new Map<string, Tool>();
-  private readonly events = createBroadcaster<ToolRegistryEvent>();
+  // The host's notifier proxy, injected at boot (both hosts build it before this registry). Held as the
+  // 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;
 
-  constructor(initial?: Iterable<Tool>) {
+  constructor(initial?: Iterable<Tool>, notifier?: Notifier) {
     if (initial !== undefined) for (const tool of initial) this.tools.set(tool.name, tool);
+    this.notifier = notifier;
+  }
+
+  private announce(name: string, operation: 'added' | 'removed', pluginName?: string): void {
+    this.notifier?.notify({
+      kind: RegistryChangeKind, source: 'tools', registry: 'tools', name, operation,
+      ...(pluginName !== undefined ? { detail: { pluginName } } : {}),
+    });
   }
 
   register(tool: Tool): void {
     this.tools.set(tool.name, tool);
-    this.events.emit({ type: 'registered', name: tool.name, ...(tool.pluginName !== undefined ? { pluginName: tool.pluginName } : {}) });
+    this.announce(tool.name, 'added', tool.pluginName);
   }
 
   remove(name: string): void {
-    if (this.tools.delete(name)) this.events.emit({ type: 'removed', name });
+    if (this.tools.delete(name)) this.announce(name, 'removed');
   }
 
   removeByPlugin(pluginName: string): void {
     for (const [name, tool] of this.tools) {
-      if (tool.pluginName === pluginName && this.tools.delete(name)) this.events.emit({ type: 'removed', name });
+      if (tool.pluginName === pluginName && this.tools.delete(name)) this.announce(name, 'removed');
     }
   }
 
@@ -31,9 +42,4 @@ export class ToolRegistryImpl implements ToolRegistry {
   list(): Tool[] {
     return [...this.tools.values()];
   }
-
-  async *watch(signal?: AbortSignal): AsyncIterable<ToolRegistryEvent> {
-    // Tool CRUD is global — no origin — so unwrap the envelope to the bare event.
-    for await (const { value } of this.events.subscribe(signal)) yield value;
-  }
 }