@matatbread/matbot-core 0.2.7 → 0.2.9

package/package.json

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

package/src/about.ts

@@ -0,0 +1,38 @@
+import type { Tool, ToolExecutor, ToolResultOf, ToolContext } from '@matatbread/matbot-plugin-api';
+
+declare module '@matatbread/matbot-plugin-api' {
+  interface ToolResults {
+    about_matbot: { version: string; about: string };
+  }
+}
+
+const ABOUT = 'Matbot composable LLM harness';
+
+/**
+ * Reports what the model is running: the harness `version` and a one-line description. The harness is
+ * not a plugin (so it has no row in `plugin list`), and its version is a singleton fact rather than a
+ * per-plugin one — hence a dedicated tool. The factory lives in core (like `single_turn`) because it is
+ * the one cross-runtime home both the node app and the browser bundle register it from, each passing its
+ * own app package version.
+ */
+export function createAboutMatbotTool(version: string): Tool<ToolResultOf<'about_matbot'>> {
+  const executor: ToolExecutor<ToolResultOf<'about_matbot'>> = {
+    async *execute(_input: unknown, _ctx: ToolContext) {
+      yield { type: 'result', value: { version, about: ABOUT } };
+    },
+  };
+
+  return {
+    name: 'about_matbot',
+    description:
+      'Report what you are running: the matbot harness version and a one-line description. Use it when ' +
+      'asked what version of matbot this is, or for an "about" of the harness itself (distinct from the ' +
+      'plugin tool, which lists loaded plugins).\n\n' +
+      'Parameters (TypeScript):\n' +
+      '```ts\n' +
+      '{}  // -> { version, about }\n' +
+      '```',
+    inputSchema: { type: 'object', properties: {} },
+    executor,
+  };
+}

package/src/index.ts

@@ -38,8 +38,10 @@ export * from './registry.js';
 export * from './settings.js';
 export * from './loader.js';
 export * from './tool-registry.js';
+export * from './provider-registry.js';
 export * from './system-context.js';
 export * from './single-turn.js';
+export * from './about.js';
 export * from './config/index.js';
 export * from './security/index.js';
 export * from './knowledge/index.js';

package/src/loader.ts

@@ -212,6 +212,7 @@ 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;
     const plugin: MatbotPlugin = {
       ...spec_obj,
       name,
@@ -219,6 +220,7 @@ export async function loadPlugins(
       resolvedUrl: toLoad[i]!.resolvedUrl,
       ...(source   !== undefined ? { source }                 : {}),
       ...(runtimes !== undefined ? { matbotRuntime: runtimes } : {}),
+      ...(version  !== undefined ? { version }                 : {}),
     };
 
     // registered gates the rollback: only an attempt that *itself* registered the

package/src/provider-registry.ts

@@ -0,0 +1,29 @@
+import type { ProviderConfig, ProviderRegistry } from '@matatbread/matbot-plugin-api';
+
+/**
+ * A `Map` of provider profiles that also satisfies the sanctioned {@link ProviderRegistry} write API.
+ * Extending `Map` gives every read-surface consumer (`get`/`has`/`keys`/`values`/iteration) the exact
+ * standard-library types, while `register`/`remove`/`revert` are the names plugins and the `provider`
+ * tool use to contribute profiles — mirroring `ToolRegistry.register`/`remove`.
+ *
+ * The entries present at construction are snapshotted as the *boot baseline*: `revert(name)` restores
+ * that value (or deletes if there was none), so a plugin that contributed — possibly shadowing — a
+ * profile can undo it on unload, returning the set to the host's boot condition.
+ */
+export class ProviderRegistryImpl extends Map<string, ProviderConfig> implements ProviderRegistry {
+  private readonly bootBaseline: Map<string, ProviderConfig>;
+
+  constructor(initial?: Iterable<readonly [string, ProviderConfig]>) {
+    super(initial);
+    this.bootBaseline = new Map(this);
+  }
+
+  register(config: ProviderConfig): void { this.set(config.name, config); }
+  remove(name: string): boolean { return this.delete(name); }
+
+  revert(name: string): void {
+    const boot = this.bootBaseline.get(name);
+    if (boot !== undefined) this.set(name, boot);
+    else this.delete(name);
+  }
+}

package/src/registry.ts

@@ -1,7 +1,7 @@
-import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, PluginRegistryEvent } from './types.js';
+import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, PluginRegistryEvent, ProviderAdapter, ProviderConfig } from './types.js';
 import { createBroadcaster } from '@matatbread/matbot-plugin-api';
 import type {
-  MatbotPlugin, MatbotMachine, Mounted,
+  MatbotPlugin, MatbotMachine, MatbotRuntime, Mounted,
   ProviderAdapterFactory, StoreFactory,
 } from './plugin.js';
 import { PLUGIN_API_VERSION, unifyServices } from './plugin.js';
@@ -145,17 +145,47 @@ export function registerPlugin(plugin: MatbotPlugin): void {
 
 // ── Resolution ────────────────────────────────────────────────────────────────
 
-export function resolveProviderFactory(module: string): ProviderAdapterFactory {
-  const factory = state.providers.get(module);
-  if (factory === undefined) {
-    const available = [...state.providers.keys()].join(', ') || 'none';
-    throw new Error(
-      `No provider registered for module "${module}". ` +
-      `Available: ${available}. ` +
-      `Install and load the provider plugin.`,
-    );
+export function tryResolveProviderFactory(module: string): ProviderAdapterFactory | undefined {
+  return state.providers.get(module);
+}
+
+/**
+ * Config → live adapter, loading the adapter module on demand. The fast path resolves an already
+ * registered factory. When the factory is absent (the common case now the boot pre-scan is disabled, or
+ * a provider profile a storage backend replayed from its medium ahead of its adapter module) the module
+ * is force-loaded and the loaded plugin's own factory is used — sidestepping the canonical-name keying the
+ * factory registry uses. Returns `null` (and warns, never throws) if the module can't be loaded or carries
+ * no adapter, so one unusable profile can't abort a turn.
+ */
+export async function instantiateProvider(services: MatbotRuntime, config: ProviderConfig): Promise<ProviderAdapter | null> {
+  // Resolve the factory tolerantly. `config.module` may be the canonical plugin name or any specifier that
+  // identifies the plugin — the factory registry is keyed by plugin name, so when a raw specifier misses we
+  // map it to the loaded plugin's name (a sibling profile sharing this adapter module may have loaded it
+  // already). The stored profile is NEVER rewritten: it stays exactly as the source wrote it (yaml path,
+  // npm name, or a storage-backend manifest entry), so `provider list` reports the source truth rather than
+  // a mix of specifiers and package names that depends on which profiles happen to have been used.
+  const name = tryResolveProviderFactory(config.module) !== undefined
+    ? config.module
+    : getPluginNameForSpecifier(config.module);
+  if (name !== undefined) {
+    const factory = tryResolveProviderFactory(name);
+    if (factory !== undefined) return factory(config);
+  }
+
+  // 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.
+  try {
+    const plugin = await services.loadPlugin(config.module);
+    if (plugin.provider === undefined) {
+      console.warn(`[matbot] provider "${config.name}": module "${config.module}" loaded but registered no adapter.`);
+      return null;
+    }
+    return plugin.provider(config);
+  } catch (err) {
+    console.warn(`[matbot] provider "${config.name}": could not load adapter module "${config.module}":`, err);
+    return null;
   }
-  return factory;
 }
 
 export function getRegisteredTools(): readonly Tool[] {