@matatbread/matbot-core 0.2.7 → 0.3.0

package/package.json

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

package/src/about.ts

@@ -0,0 +1,34 @@
+import type { Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext } from '@matatbread/matbot-plugin-api';
+
+declare module '@matatbread/matbot-plugin-api' {
+  interface ToolContracts {
+    about_matbot: ToolContract<{ version: string; about: string }, Record<string, never>>;
+  }
+}
+
+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).',
+    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[] {

package/src/session-runner.ts

@@ -5,6 +5,7 @@ import type {
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
 import type { HookRegistry } from './hooks.js';
+import type { ToolTypeIndex } from '@matatbread/matbot-plugin-api';
 import { appendMessage, createMessage } from './session.js';
 import { contextSwitch, withUsageScope } from '@matatbread/matbot-plugin-api';
 import { runSession } from './runner.js';
@@ -13,6 +14,11 @@ export interface SessionRunnerDeps {
   store:           Store<Session>;
   resolveProvider: (name: string) => Promise<{ adapter: ProviderAdapter; config: ProviderConfig } | null>;
   tools?:          ToolRegistry;
+  // Resolved live (the service registers after boot): supplies the per-tool wire contract derived from each
+  // tool's single contract source (the `ToolContracts` arms, or a source-less tool's `toolContract`), folded
+  // into the turn-start tool snapshot's description so the wire carries params/result text. Absent (e.g.
+  // browser) ⇒ tools keep their plain description.
+  toolTypeIndex?:  () => ToolTypeIndex | undefined;
   hooks?:          HookRegistry;
   systemContext?:  SystemContextRegistry;
   vault?:          Vault;
@@ -207,8 +213,19 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
 
         const ac = new AbortController();
         s.ac = ac;
+        // Fold each tool's wire contract — the `params`/`result` text flattened from its single contract
+        // (a source tool's ToolContracts arms, or a source-less tool's `toolContract`) — into its description
+        // for this turn, so the model reasons about the real TS shapes, not just the loose inputSchema.
+        // Derived here because `services`/ToolTypeIndex are live at dispatch. Tools with only a loose
+        // inputSchema (no contract) are left as-is; absent ToolTypeIndex (browser) ⇒ plain descriptions.
+        const wire = await deps.toolTypeIndex?.()?.wireContracts();
         const toolMap = deps.tools !== undefined
-          ? new Map<string, Tool>(deps.tools.list().map(t => [t.name, t]))
+          ? new Map<string, Tool>(deps.tools.list().map(t => {
+              const wc = wire?.[t.name];
+              return [t.name, wc !== undefined
+                ? { ...t, description: `${t.description}\n\nTypeScript:\n  params: ${wc.params}\n  result: ${wc.result}` }
+                : t];
+            }))
           : undefined;
 
         try {

package/src/single-turn.ts

@@ -1,8 +1,8 @@
-import type { Tool, ToolExecutor, ToolResultOf, ToolContext, MatbotMachine } from '@matatbread/matbot-plugin-api';
+import type { Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext, MatbotMachine } from '@matatbread/matbot-plugin-api';
 
 declare module '@matatbread/matbot-plugin-api' {
-  interface ToolResults {
-    single_turn: { text: string };  // the consulted provider's reply text
+  interface ToolContracts {
+    single_turn: ToolContract<{ text: string }, { provider?: string; prompt: string; system?: string }>;  // the consulted provider's reply text
   }
 }
 
@@ -53,11 +53,7 @@ export function createSingleTurnTool(services: MatbotMachine): Tool<ToolResultOf
       'back its text. Use it to consult a different model — e.g. a second, ' +
       'different-lineage model critiquing your draft, or any generation that should run on a specific ' +
       'provider. `provider` is OPTIONAL: omit it to run on the current conversation\'s model, or name ' +
-      'a configured provider to switch models (list or add providers with the provider tool).\n\n' +
-      'Parameters (TypeScript):\n' +
-      '```ts\n' +
-      '{ provider?: string; prompt: string; system?: string }  // -> { text }\n' +
-      '```',
+      'a configured provider to switch models (list or add providers with the provider tool).',
     inputSchema: {
       type:       'object',
       required:   ['prompt'],