@matatbread/matbot-core 0.2.9 → 0.3.1

package/package.json

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

package/src/about.ts

@@ -1,8 +1,8 @@
-import type { Tool, ToolExecutor, ToolResultOf, ToolContext } from '@matatbread/matbot-plugin-api';
+import type { Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext } from '@matatbread/matbot-plugin-api';
 
 declare module '@matatbread/matbot-plugin-api' {
-  interface ToolResults {
-    about_matbot: { version: string; about: string };
+  interface ToolContracts {
+    about_matbot: ToolContract<{ version: string; about: string, currentProvider: string | undefined }, Record<string, never>>;
   }
 }
 
@@ -17,21 +17,19 @@ const ABOUT = 'Matbot composable LLM harness';
  */
 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 } };
+    async *execute(_input: unknown, ctx: ToolContext) {
+      yield { type: 'result', value: { version, about: ABOUT, currentProvider: ctx.provider } };
     },
   };
 
   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' +
-      '```',
+      'Report what you are running right now: the current model / LLM and provider profile powering THIS ' +
+      'conversation, plus the matbot harness version and a one-line description. Use it whenever asked ' +
+      '"what model / LLM are you using?", "which provider is this?", what version of matbot this is, or for ' +
+      'an "about" of the harness itself — distinct from the `provider` tool (which lists all configured ' +
+      'provider profiles) and the `plugin` tool (which lists loaded plugins).',
     inputSchema: { type: 'object', properties: {} },
     executor,
   };

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 } from './registry.js';
+import { registerPlugin, setupPlugin, unloadPlugin, recordFailedPlugin, clearFailedPlugin } from './registry.js';
 
 /**
  * The runtime this process is executing in. Detected the same way the rejected-import branch below
@@ -126,7 +126,9 @@ export async function loadPlugins(
       if (onLoadError === 'throw') {
         throw incompatibleRuntimeError(spec, runtimes, CURRENT_RUNTIME);
       }
-      console.warn(`[matbot] Skipping plugin "${spec}": declares matbotRuntime [${runtimes.join(', ')}], host runtime is "${CURRENT_RUNTIME}".`);
+      const reason = `declares matbotRuntime [${runtimes.join(', ')}], host runtime is "${CURRENT_RUNTIME}".`;
+      console.warn(`[matbot] Skipping plugin "${spec}": ${reason}`);
+      recordFailedPlugin({ specifier: spec, error: reason, ...(name !== undefined ? { name } : {}) });
       continue;
     }
     toLoad.push({
@@ -158,6 +160,7 @@ export async function loadPlugins(
   const failLoad = (spec: string, reason: string, kind: 'load' | 'shape' = 'load'): void => {
     if (onLoadError === 'throw') throw kind === 'shape' ? notAPluginError(spec, reason) : new Error(reason);
     console.warn(`[matbot] Skipping plugin "${spec}": ${reason}`);
+    recordFailedPlugin({ specifier: spec, error: reason });
   };
 
   for (let i = 0; i < toLoad.length; i++) {
@@ -169,6 +172,7 @@ export async function loadPlugins(
       if (typeof window !== 'undefined') {
         // Browser: warn and skip — browser environments have no node_modules fallback.
         console.warn(`[matbot] Could not load plugin "${spec}" (browser: use a URL path or configure an import map): ${reason}`);
+        recordFailedPlugin({ specifier: spec, error: reason });
         continue;
       }
       console.error(`[matbot] Failed to load plugin "${spec}":`, result.reason);
@@ -233,8 +237,15 @@ export async function loadPlugins(
       registered = true;
       await setupPlugin(plugin, services, prompt);
       loaded.push(plugin);
+      // Successful (re)load: a fixed plugin drops off the failed list (reload runs this same path).
+      clearFailedPlugin(spec);
     } catch (err) {
-      console.error(`[matbot] Ignoring plugin "${plugin.name}" from "${spec}" due to an error:`, err instanceof Error ? err.message : err);
+      const reason = err instanceof Error ? err.message : String(err);
+      console.error(`[matbot] Ignoring plugin "${plugin.name}" from "${spec}" due to an error:`, reason);
+      // Graceful but not silent: record the setup failure (skip mode — the boot batch) so the `plugin`
+      // tool and web UI can show it. Explicit single loads (`onLoadError: 'throw'`) surface the error to
+      // the caller directly, so they are not added to the persistent failed list.
+      if (onLoadError === 'skip') recordFailedPlugin({ specifier: spec, name: plugin.name, error: reason });
       // Roll back partial registration so a failed load leaves no ghost state. setupPlugin
       // can throw after the plugin is already in the registry with some of its tools / hooks /
       // services / provider / storage wired (a wrong-platform plugin touching a missing

package/src/registry.ts

@@ -11,6 +11,15 @@ import type { SettingsDoc } from './settings.js';
 
 // ── Internal state ────────────────────────────────────────────────────────────
 
+/**
+ * A plugin the loader could not bring up — an incompatible runtime, an import that rejected, a
+ * module that is not plugin-shaped, or a setup() throw. Recorded (not discarded) so the failure is
+ * *graceful but not silent*: the `plugin` tool and web UI can show which configured plugins failed
+ * and why, instead of the failure vanishing into a boot-time console line. `error` is pre-stringified
+ * (sidesteps the `unknown` catch-var); `name` is present only when known before the failure.
+ */
+export type FailedPlugin = { specifier: string; name?: string; error: string };
+
 // Mutable arrays/maps held in a single object to make _resetRegistry() simple.
 const state = {
   plugins:         [] as MatbotPlugin[],
@@ -21,6 +30,7 @@ const state = {
   serviceKeys:     new Map<string, string[]>(),  // pluginName → MatbotMachine keys it registered
   hookPlugins:        new Set<string>(),         // plugins that registered at least one hook
   systemContextPlugins: new Set<string>(),       // plugins that registered a system-context contributor
+  failedPlugins:   [] as FailedPlugin[],         // plugins the loader skipped, keyed by specifier (last failure wins)
   overwriteAllTools: undefined as boolean | undefined,  // persisted "overwrite on collision, this install" choice, loaded lazily
 };
 
@@ -196,6 +206,28 @@ export function getRegisteredPlugins(): readonly MatbotPlugin[] {
   return state.plugins;
 }
 
+/**
+ * Plugins the loader skipped rather than loaded — the graceful-but-not-silent record. One entry per
+ * specifier (a repeated failure overwrites the prior one; a subsequent successful load clears it via
+ * clearFailedPlugin). Surfaced by the `plugin` tool's `list` and the web plugins panel.
+ */
+export function getFailedPlugins(): readonly FailedPlugin[] {
+  return state.failedPlugins;
+}
+
+/** Record (or replace, by specifier) a plugin the loader skipped. Called from loader.ts skip points. */
+export function recordFailedPlugin(entry: FailedPlugin): void {
+  const idx = state.failedPlugins.findIndex(f => f.specifier === entry.specifier);
+  if (idx === -1) state.failedPlugins.push(entry);
+  else            state.failedPlugins[idx] = entry;
+}
+
+/** Drop any recorded failure for a specifier — a fixed + reloaded plugin drops off the failed list. */
+export function clearFailedPlugin(specifier: string): void {
+  const idx = state.failedPlugins.findIndex(f => f.specifier === specifier);
+  if (idx !== -1) state.failedPlugins.splice(idx, 1);
+}
+
 export function getRegisteredFrontendPlugins(): ReadonlyMap<string, FrontendInfo> {
   return state.frontendPlugins;
 }

package/src/runner.ts

@@ -4,6 +4,7 @@ import type {
   Tool, ToolRegistry, ToolContext, Store, FileStore, SystemContextRegistry, Vault, PromptFn, FormField,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
+import type { ToolPresenter } from '@matatbread/matbot-plugin-api';
 import { currentUsageSink } from '@matatbread/matbot-plugin-api';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
@@ -25,6 +26,14 @@ export interface RunSessionOpts {
    * `tools`).
    */
   toolRegistry?:  ToolRegistry;
+  /**
+   * Optional presenter that picks which tools are advertised to the model on each provider call — a
+   * read-only view over the `tools` snapshot (e.g. deferring a large library behind a search tool and
+   * revealing matches mid-turn). Consulted *per provider call* so a reveal takes effect on the next
+   * loop iteration; absent ⇒ the whole snapshot is advertised (unchanged behaviour). Presentation never
+   * affects execution — a withheld tool still resolves by name through `toolRegistry`.
+   */
+  toolPresenter?: ToolPresenter;
   store:          Store<Session>;
   hooks?:         HookRegistry;
   systemContext?: SystemContextRegistry;
@@ -149,8 +158,14 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
       outgoing: [...systemMsg, ...history],
       session, config, signal,
     });
+    // Tools advertised for THIS call. A presenter (optional) may present a subset of the snapshot and
+    // grow it across iterations as the model discovers tools; absent ⇒ the whole snapshot. Withheld
+    // tools stay callable — execution resolves against the live registry (opts.toolRegistry), not this.
+    const advertised = opts.toolPresenter
+      ? await opts.toolPresenter.present([...tools.values()], { session, provider: config.provider })
+      : [...tools.values()];
     try {
-      for await (const ev of provider.complete(outgoing, providerConfig, [...tools.values()], signal)) {
+      for await (const ev of provider.complete(outgoing, providerConfig, advertised, signal)) {
         switch (ev.type) {
           case 'text-delta':
             textAcc += ev.delta;

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, ToolPresenter } 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,14 @@ 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;
+  // Resolved live (registers after boot): picks which tools are advertised to the model per provider
+  // call. Absent ⇒ the whole turn snapshot is advertised. Threaded into runSession per turn.
+  toolPresenter?:  () => ToolPresenter | undefined;
   hooks?:          HookRegistry;
   systemContext?:  SystemContextRegistry;
   vault?:          Vault;
@@ -113,6 +122,12 @@ function createSink(dispose: () => void): Sink {
   };
 }
 
+export function wireDescription(description: string, wc: { params: string; result: string } | undefined) {
+  return wc
+    ? `${description}\n\nTypeScript params:\n\`\`\`\n${wc.params}\n\`\`\`\n\nTypeScript result:\`\`\`${wc.result}\n\`\`\``
+    : description;
+}
+
 export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
   const states = new Map<string, SessionState>();
 
@@ -207,8 +222,20 @@ 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 toolPresenter = deps.toolPresenter?.();
         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: wireDescription(t.description, wc) }
+                : t];
+            }))
           : undefined;
 
         try {
@@ -231,6 +258,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               unloadPlugin:   deps.unloadPlugin,
               ...(toolMap            !== undefined ? { tools:         toolMap            } : {}),
               ...(deps.tools         !== undefined ? { toolRegistry:  deps.tools         } : {}),
+              ...(toolPresenter      !== undefined ? { toolPresenter                     } : {}),
               ...(deps.hooks         !== undefined ? { hooks:         deps.hooks         } : {}),
               ...(deps.systemContext !== undefined ? { systemContext: deps.systemContext } : {}),
               ...(deps.workdir       !== undefined ? { workdir:       deps.workdir       } : {}),

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'],

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

@@ -22,6 +22,11 @@ function toQuery(p: PageState): StoreQuery {
 // disjoint cover (page N re-applies the same sort as page 1, so the total order never shifts). A
 // cursor is untrusted input, so its decoded query is validated exactly like a fresh one.
 export function executeQuery<T extends { id: string; version: string }>(docs: T[], q: StoreQuery): QueryResult<T> {
+  // Validate the caller's RAW query first. The projection below keeps only where/sort/limit, so an
+  // unknown top-level key (e.g. `filter` instead of `where`) would otherwise be silently discarded
+  // and the query would degrade to match-everything with no feedback to the author.
+  validateQuery(q);
+
   const page: PageState = q.cursor !== undefined
     ? decodeCursor(q.cursor)
     : {
@@ -31,7 +36,8 @@ export function executeQuery<T extends { id: string; version: string }>(docs: T[
         ...(q.limit !== undefined ? { limit: q.limit } : {}),
       };
 
-  validateQuery(toQuery(page));
+  // A cursor is untrusted input, so its decoded query is validated exactly like a fresh one.
+  if (q.cursor !== undefined) validateQuery(toQuery(page));
 
   const predicate = page.where !== undefined ? compileFilter(page.where) : () => true;
   const ordered   = applySort(docs.filter(predicate), page.sort);

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

@@ -93,7 +93,21 @@ function validateFilter(f: Filter, ptr: string): void {
   }
 }
 
+const QUERY_KEYS = new Set(['where', 'sort', 'limit', 'cursor']);
+
 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');
+
+  // 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
+  // query degrades to match-everything, and the author gets a plausible result with no signal it was
+  // malformed. Naming the bad key and the valid set turns a silent miss into a fixable error.
+  for (const key of Object.keys(q)) {
+    if (!QUERY_KEYS.has(key))
+      throw new StoreQueryError(`unknown query key '${key}' — valid keys are: where, sort, limit, cursor`, `/${key}`, 'MALFORMED');
+  }
+
   if (q.where !== undefined) validateFilter(q.where, '/where');
 
   if (q.sort !== undefined) {