@matatbread/matbot-core 0.2.9 → 0.3.0

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.2.9",
+  "version": "0.3.0",
   "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.0"
   },
   "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 }, Record<string, never>>;
   }
 }
 
@@ -27,11 +27,7 @@ export function createAboutMatbotTool(version: string): Tool<ToolResultOf<'about
     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' +
-      '```',
+      'plugin tool, which lists loaded plugins).',
     inputSchema: { type: 'object', properties: {} },
     executor,
   };

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