@t2000/engine 0.46.6 → 0.46.7

package/dist/index.d.ts

@@ -922,6 +922,32 @@ declare class QueryEngine {
     reset(): void;
     getGuardEvents(): readonly GuardEvent[];
     loadMessages(messages: Message[]): void;
+    /**
+     * [v0.46.7] Run a read-only tool out-of-band, using the engine's tool
+     * registry and ToolContext. Used by hosts to deterministically pre-dispatch
+     * tools based on user-message intent (e.g. always call `balance_check` when
+     * the user says "what's my net worth?", regardless of whether the LLM would
+     * have otherwise re-called it).
+     *
+     * The host is responsible for:
+     *  - Streaming the synthetic `tool_start` + `tool_result` events to the UI
+     *    (so cards render as if the LLM had called the tool).
+     *  - Appending matching `tool_use` + `tool_result` ContentBlocks to the
+     *    engine's message history via `loadMessages([...getMessages(), ...synth])`
+     *    BEFORE calling `submitMessage`, so the LLM sees the fresh data and
+     *    doesn't re-call.
+     *
+     * Throws if the tool isn't registered, isn't read-only, or fails input
+     * validation. Tool execution errors are returned as `{ data, isError: true }`
+     * for the caller to handle (typically: skip the injection so the LLM falls
+     * back to its normal flow).
+     */
+    invokeReadTool(toolName: string, input: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        data: unknown;
+        isError: boolean;
+    }>;
     setServerPositions(data: EngineConfig['serverPositions']): void;
     getUsage(): CostSnapshot;
     /**

package/dist/index.js

@@ -1710,17 +1710,31 @@ async function fetchCatalog() {
   catalogCache = { data, ts: Date.now() };
   return data;
 }
+function renderServices(catalog) {
+  return catalog.map((s) => ({
+    id: s.id,
+    name: s.name,
+    description: s.description,
+    categories: s.categories,
+    endpoints: s.endpoints.map((e) => ({
+      url: `${MPP_GATEWAY2}/${s.id}${e.path}`,
+      method: e.method,
+      description: e.description,
+      price: `$${e.price}`
+    }))
+  }));
+}
 function matchesQuery(service, q) {
   const lower = q.toLowerCase();
   return service.id.toLowerCase().includes(lower) || service.name.toLowerCase().includes(lower) || service.description.toLowerCase().includes(lower) || service.categories.some((c) => c.toLowerCase().includes(lower)) || service.endpoints.some((e) => e.description.toLowerCase().includes(lower));
 }
 var mppServicesTool = buildTool({
   name: "mpp_services",
-  description: 'Discover available MPP gateway services. Returns service names, descriptions, endpoints with required parameters, and pricing. Use BEFORE calling pay_api. Modes: pass `query` for keyword search, `category` to filter by category, or `mode: "full"` to fetch the ENTIRE catalog in one card (for "show me all MPP services" / "full catalog" requests \u2014 never enumerate per category in a loop). Calling with no args returns a category summary so you can narrow.',
+  description: 'Discover available MPP gateway services. Returns service names, descriptions, endpoints with required parameters, and pricing. Use BEFORE calling pay_api. With no args, returns the FULL catalog as a single card (default behavior \u2014 covers "show me available MPP services", "what services exist", "show me all MPP services"). Use `query` to keyword-search a specific need ("translate", "weather", "postcard"). Use `category` to filter to one category. Use `mode: "summary"` only if you explicitly want a category-counts overview without the full list.',
   inputSchema: z.object({
-    query: z.string().optional().describe('Filter by keyword (e.g. "postcard", "translate", "weather").'),
-    category: z.string().optional().describe('Filter by category exactly (e.g. "weather", "image"). See category summary returned when called without filters.'),
-    mode: z.enum(["summary", "full"]).optional().describe('"full" returns the entire catalog in a single card \u2014 use this for "show me all MPP services" / "full catalog" requests instead of looping per category. Default is "summary" (category counts only when no filter is supplied).')
+    query: z.string().optional().describe('Filter by keyword (e.g. "postcard", "translate", "weather"). Returns matching services in one card.'),
+    category: z.string().optional().describe('Filter by category exactly (e.g. "weather", "image"). Use mode:"summary" first if you need to see the category list.'),
+    mode: z.enum(["summary", "full"]).optional().describe('"full" (default) returns the entire catalog in one card. "summary" returns category counts only \u2014 use this only when the user explicitly asks for a category overview.')
   }),
   jsonSchema: {
     type: "object",
@@ -1736,7 +1750,7 @@ var mppServicesTool = buildTool({
       mode: {
         type: "string",
         enum: ["summary", "full"],
-        description: '"full" returns the entire catalog in one card. Use for "show me all" requests.'
+        description: '"full" (default) returns the entire catalog in one card. "summary" returns category counts only.'
       }
     },
     required: []
@@ -1748,25 +1762,14 @@ var mppServicesTool = buildTool({
   maxResultSizeChars: 12e3,
   async call(input) {
     const catalog = await fetchCatalog();
-    if (input.mode === "full") {
-      const services2 = catalog.map((s) => ({
-        id: s.id,
-        name: s.name,
-        description: s.description,
-        categories: s.categories,
-        endpoints: s.endpoints.map((e) => ({
-          url: `${MPP_GATEWAY2}/${s.id}${e.path}`,
-          method: e.method,
-          description: e.description,
-          price: `$${e.price}`
-        }))
-      }));
+    if (input.mode !== "summary" && !input.query && !input.category) {
+      const services2 = renderServices(catalog);
       return {
         data: { services: services2, total: services2.length, mode: "full" },
         displayText: `Full MPP catalog: ${services2.length} services.`
       };
     }
-    if (!input.query && !input.category) {
+    if (input.mode === "summary" && !input.query && !input.category) {
       const counts = /* @__PURE__ */ new Map();
       for (const svc of catalog) {
         for (const cat of svc.categories) {
@@ -1777,14 +1780,14 @@ var mppServicesTool = buildTool({
       return {
         data: {
           _refine: {
-            reason: 'MPP catalog has many services \u2014 pick a category, supply a query, or pass mode:"full" to fetch everything.',
+            reason: 'Category summary (mode:"summary"). Re-call with a category or omit mode for the full catalog.',
             suggestedParams: { category: categories[0]?.category ?? "weather" },
             allModes: ["summary", "full"]
           },
           categories,
           totalServices: catalog.length
         },
-        displayText: `${catalog.length} services across ${categories.length} categories. Re-call with a category, query, or mode:"full".`
+        displayText: `${catalog.length} services across ${categories.length} categories.`
       };
     }
     let filtered = catalog;
@@ -1795,18 +1798,7 @@ var mppServicesTool = buildTool({
     if (input.query) {
       filtered = filtered.filter((s) => matchesQuery(s, input.query));
     }
-    const services = filtered.map((s) => ({
-      id: s.id,
-      name: s.name,
-      description: s.description,
-      categories: s.categories,
-      endpoints: s.endpoints.map((e) => ({
-        url: `${MPP_GATEWAY2}/${s.id}${e.path}`,
-        method: e.method,
-        description: e.description,
-        price: `$${e.price}`
-      }))
-    }));
+    const services = renderServices(filtered);
     const filterDesc = [
       input.query ? `query "${input.query}"` : null,
       input.category ? `category "${input.category}"` : null
@@ -4595,6 +4587,62 @@ var QueryEngine = class {
   loadMessages(messages) {
     this.messages = [...messages];
   }
+  /**
+   * [v0.46.7] Run a read-only tool out-of-band, using the engine's tool
+   * registry and ToolContext. Used by hosts to deterministically pre-dispatch
+   * tools based on user-message intent (e.g. always call `balance_check` when
+   * the user says "what's my net worth?", regardless of whether the LLM would
+   * have otherwise re-called it).
+   *
+   * The host is responsible for:
+   *  - Streaming the synthetic `tool_start` + `tool_result` events to the UI
+   *    (so cards render as if the LLM had called the tool).
+   *  - Appending matching `tool_use` + `tool_result` ContentBlocks to the
+   *    engine's message history via `loadMessages([...getMessages(), ...synth])`
+   *    BEFORE calling `submitMessage`, so the LLM sees the fresh data and
+   *    doesn't re-call.
+   *
+   * Throws if the tool isn't registered, isn't read-only, or fails input
+   * validation. Tool execution errors are returned as `{ data, isError: true }`
+   * for the caller to handle (typically: skip the injection so the LLM falls
+   * back to its normal flow).
+   */
+  async invokeReadTool(toolName, input, options = {}) {
+    const tool = findTool(this.tools, toolName);
+    if (!tool) throw new Error(`invokeReadTool: tool not found: ${toolName}`);
+    if (!tool.isReadOnly) {
+      throw new Error(`invokeReadTool: tool is not read-only: ${toolName} (write tools must go through the permission gate)`);
+    }
+    const parsed = tool.inputSchema.safeParse(input);
+    if (!parsed.success) {
+      throw new Error(
+        `invokeReadTool: invalid input for ${toolName}: ${parsed.error.issues.map((i) => i.message).join(", ")}`
+      );
+    }
+    const signal = options.signal ?? new AbortController().signal;
+    const context = {
+      agent: this.agent,
+      mcpManager: this.mcpManager,
+      walletAddress: this.walletAddress,
+      suiRpcUrl: this.suiRpcUrl,
+      serverPositions: this.serverPositions,
+      positionFetcher: this.positionFetcher,
+      env: this.env,
+      signal,
+      priceCache: this.priceCache,
+      permissionConfig: this.permissionConfig,
+      sessionSpendUsd: this.sessionSpendUsd
+    };
+    try {
+      const result = await tool.call(parsed.data, context);
+      return { data: result.data, isError: false };
+    } catch (err) {
+      return {
+        data: { error: err instanceof Error ? err.message : "Tool execution failed" },
+        isError: true
+      };
+    }
+  }
   setServerPositions(data) {
     this.serverPositions = data;
   }