mindcache 3.5.3 → 3.7.0

package/dist/server.d.mts

@@ -1,5 +1,5 @@
-import { M as MindCache } from './CloudAdapter-DK4YecbV.mjs';
-export { A as AccessLevel, a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, n as DEFAULT_KEY_ATTRIBUTES, G as GlobalListener, H as HistoryEntry, k as HistoryOptions, K as KeyAttributes, j as KeyEntry, f as KeyType, L as Listener, l as MindCacheCloudOptions, m as MindCacheIndexedDBOptions, e as MindCacheOptions, i as STM, j as STMEntry, g as SystemTag, o as SystemTagHelpers } from './CloudAdapter-DK4YecbV.mjs';
+import { M as MindCache } from './CloudAdapter-PLGvGjoA.mjs';
+export { A as AccessLevel, a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, p as DEFAULT_KEY_ATTRIBUTES, G as GlobalListener, H as HistoryEntry, l as HistoryOptions, K as KeyAttributes, k as KeyEntry, g as KeyType, L as Listener, m as MindCacheCloudOptions, n as MindCacheIndexedDBOptions, f as MindCacheOptions, j as STM, k as STMEntry, h as SystemTag, q as SystemTagHelpers } from './CloudAdapter-PLGvGjoA.mjs';
 import 'yjs';
 
 interface IndexedDBConfig {

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { M as MindCache } from './CloudAdapter-DK4YecbV.js';
-export { A as AccessLevel, a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, n as DEFAULT_KEY_ATTRIBUTES, G as GlobalListener, H as HistoryEntry, k as HistoryOptions, K as KeyAttributes, j as KeyEntry, f as KeyType, L as Listener, l as MindCacheCloudOptions, m as MindCacheIndexedDBOptions, e as MindCacheOptions, i as STM, j as STMEntry, g as SystemTag, o as SystemTagHelpers } from './CloudAdapter-DK4YecbV.js';
+import { M as MindCache } from './CloudAdapter-PLGvGjoA.js';
+export { A as AccessLevel, a as CloudAdapter, c as CloudAdapterEvents, C as CloudConfig, b as ConnectionState, p as DEFAULT_KEY_ATTRIBUTES, G as GlobalListener, H as HistoryEntry, l as HistoryOptions, K as KeyAttributes, k as KeyEntry, g as KeyType, L as Listener, m as MindCacheCloudOptions, n as MindCacheIndexedDBOptions, f as MindCacheOptions, j as STM, k as STMEntry, h as SystemTag, q as SystemTagHelpers } from './CloudAdapter-PLGvGjoA.js';
 import 'yjs';
 
 interface IndexedDBConfig {

package/dist/server.js

@@ -6,6 +6,8 @@ var decoding = require('lib0/decoding');
 var Y = require('yjs');
 var yIndexeddb = require('y-indexeddb');
 var diff = require('fast-diff');
+var ai = require('ai');
+var zod = require('zod');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -211,7 +213,6 @@ var init_CloudAdapter = __esm({
         if (!config.baseUrl) {
           throw new Error("MindCache Cloud: baseUrl is required. Please provide the cloud API URL in your configuration.");
         }
-        this.validateConfig(config);
         this.setupNetworkDetection();
       }
       ws = null;
@@ -227,43 +228,6 @@ var init_CloudAdapter = __esm({
       handleOnline = null;
       handleOffline = null;
       _synced = false;
-      /**
-       * Validate configuration and warn about common mistakes
-       */
-      validateConfig(config) {
-        const baseUrl = config.baseUrl;
-        if (!baseUrl) {
-          return;
-        }
-        console.log("\u2601\uFE0F MindCache Cloud Config:", {
-          baseUrl,
-          instanceId: config.instanceId,
-          hasTokenProvider: !!config.tokenProvider,
-          hasApiKey: !!config.apiKey
-        });
-        try {
-          const url = new URL(baseUrl);
-          if (url.hostname === "mindcache.dev") {
-            console.error(
-              '\u26A0\uFE0F MindCache Cloud WARNING: baseUrl is set to "mindcache.dev" but the API is at "api.mindcache.dev".\n   Current: ' + baseUrl + "\n   Expected: https://api.mindcache.dev\n   This will cause WebSocket connection failures (404 errors)."
-            );
-          }
-          if (url.protocol === "ws:" || url.protocol === "wss:") {
-            console.warn(
-              "\u26A0\uFE0F MindCache Cloud: baseUrl uses WebSocket protocol (" + url.protocol + "). Consider using http:// or https:// - CloudAdapter will handle the WebSocket upgrade automatically."
-            );
-          }
-          if (url.hostname === "localhost" && url.port !== "8787" && url.port !== "3000") {
-            console.warn(
-              "\u26A0\uFE0F MindCache Cloud: localhost URL detected with non-standard port " + url.port + ". Default MindCache dev server runs on port 8787."
-            );
-          }
-          const wsUrl = baseUrl.replace("https://", "wss://").replace("http://", "ws://");
-          console.log("\u2601\uFE0F WebSocket will connect to:", wsUrl + "/sync/" + config.instanceId);
-        } catch (e) {
-          console.error("\u26A0\uFE0F MindCache Cloud: Invalid baseUrl format:", baseUrl);
-        }
-      }
       /** Browser network status - instantly updated via navigator.onLine */
       get isOnline() {
         return this._isOnline;
@@ -516,6 +480,76 @@ var SystemTagHelpers = {
   hasTemplateInjection: (attrs) => attrs.systemTags.includes("ApplyTemplate")
 };
 
+// src/core/SchemaParser.ts
+var SchemaParser = class {
+  /**
+   * Parse a markdown schema string into a CustomTypeDefinition
+   * @param schema - Markdown schema string
+   * @returns Parsed type definition
+   * @throws Error if schema format is invalid
+   */
+  static parse(schema) {
+    const lines = schema.trim().split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+    if (lines.length === 0) {
+      throw new Error("Schema cannot be empty");
+    }
+    const typeNameMatch = lines[0].match(/^#\s*(\w+)$/);
+    if (!typeNameMatch) {
+      throw new Error(`Invalid schema: first line must be "#TypeName", got "${lines[0]}"`);
+    }
+    const typeName = typeNameMatch[1];
+    const fields = [];
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i];
+      const fieldMatch = line.match(/^\*\s*([^:]+):\s*(.+)$/);
+      if (fieldMatch) {
+        fields.push({
+          name: fieldMatch[1].trim(),
+          description: fieldMatch[2].trim()
+        });
+      }
+    }
+    if (fields.length === 0) {
+      throw new Error(`Schema "${typeName}" must have at least one field`);
+    }
+    return {
+      name: typeName,
+      fields,
+      rawSchema: schema
+    };
+  }
+  /**
+   * Generate a markdown representation of a type definition
+   * Useful for including in LLM prompts
+   */
+  static toMarkdown(typeDef) {
+    const lines = [`#${typeDef.name}`];
+    for (const field of typeDef.fields) {
+      lines.push(`* ${field.name}: ${field.description}`);
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Generate a prompt-friendly description of the type
+   * More verbose than toMarkdown, better for LLM guidance
+   */
+  static toPromptDescription(typeDef) {
+    const fieldDescs = typeDef.fields.map((f) => `  - ${f.name}: ${f.description}`).join("\n");
+    return `Type "${typeDef.name}" with fields:
+${fieldDescs}`;
+  }
+  /**
+   * Generate an example value structure based on the type definition
+   */
+  static generateExample(typeDef) {
+    const lines = [`#${typeDef.name.toLowerCase()}`];
+    for (const field of typeDef.fields) {
+      lines.push(`* ${field.name}: [${field.description}]`);
+    }
+    return lines.join("\n");
+  }
+};
+
 // src/core/MarkdownSerializer.ts
 var MarkdownSerializer = class {
   /**
@@ -862,18 +896,16 @@ var MarkdownSerializer = class {
     return result;
   }
 };
-
-// src/core/AIToolBuilder.ts
 var AIToolBuilder = class _AIToolBuilder {
   /**
-     * Sanitize key name for use in tool names
-     */
+   * Sanitize key name for use in tool names
+   */
   static sanitizeKeyForTool(key) {
     return key.replace(/[^a-zA-Z0-9_-]/g, "_");
   }
   /**
-     * Find original key from sanitized tool name
-     */
+   * Find original key from sanitized tool name
+   */
   static findKeyFromSanitizedTool(mc, sanitizedKey) {
     for (const key of mc.keys()) {
       if (_AIToolBuilder.sanitizeKeyForTool(key) === sanitizedKey) {
@@ -883,15 +915,174 @@ var AIToolBuilder = class _AIToolBuilder {
     return void 0;
   }
   /**
-     * Generate Vercel AI SDK compatible tools for writable keys.
-     * For document type keys, generates additional tools: append_, insert_, edit_
-     *
-     * Security: All tools use llm_set_key internally which:
-     * - Only modifies VALUES, never attributes/systemTags
-     * - Prevents LLMs from escalating privileges
-     */
+   * Generate framework-agnostic tools with raw JSON Schema.
+   * Works with: OpenAI SDK, Anthropic SDK, LangChain, etc.
+   *
+   * Tool format:
+   * {
+   *   description: string,
+   *   parameters: { type: 'object', properties: {...}, required: [...] },
+   *   execute: async (args) => result
+   * }
+   */
+  static createTools(mc) {
+    return _AIToolBuilder._buildTools(mc);
+  }
+  /**
+   * Generate Vercel AI SDK v5 compatible tools using Zod schemas.
+   * Uses tool() helper with Zod for full AI SDK v5 compatibility.
+   *
+   * Use this with: generateText(), streamText() from 'ai' package
+   */
   static createVercelAITools(mc) {
     const tools = {};
+    const registeredTypes = mc.getRegisteredTypes();
+    const typeDesc = registeredTypes.length > 0 ? `Optional type: ${registeredTypes.join(" | ")}` : "No types registered";
+    tools["create_key"] = ai.tool({
+      description: `Create a new key in MindCache. ${registeredTypes.length > 0 ? `Available types: ${registeredTypes.join(", ")}` : ""}`,
+      inputSchema: zod.z.object({
+        key: zod.z.string().describe('The key name (e.g., "contact_john_doe")'),
+        value: zod.z.string().describe("The value (JSON string for structured data)"),
+        type: zod.z.string().optional().describe(typeDesc)
+      }),
+      execute: async ({ key, value, type }) => {
+        if (mc.has(key)) {
+          return { result: `Key "${key}" exists. Use write_${_AIToolBuilder.sanitizeKeyForTool(key)}`, error: true };
+        }
+        if (type && !mc.getTypeSchema(type)) {
+          return { result: `Type "${type}" not registered`, error: true };
+        }
+        mc.set_value(key, value, { systemTags: ["SystemPrompt", "LLMRead", "LLMWrite"] });
+        if (type) {
+          mc.setType(key, type);
+        }
+        return { result: `Created "${key}"${type ? ` (${type})` : ""}`, key, value };
+      }
+    });
+    for (const key of mc.keys()) {
+      if (key.startsWith("$") || !mc.keyMatchesContext(key)) {
+        continue;
+      }
+      const attrs = mc.get_attributes(key);
+      if (!attrs?.systemTags?.includes("LLMWrite")) {
+        continue;
+      }
+      const sanitized = _AIToolBuilder.sanitizeKeyForTool(key);
+      const customTypeName = mc.getKeyType(key);
+      const customType = customTypeName ? mc.getTypeSchema(customTypeName) : void 0;
+      let desc = `Write to "${key}"`;
+      if (customType) {
+        desc = `Write to "${key}" (${customTypeName}). ${SchemaParser.toPromptDescription(customType)}`;
+      }
+      tools[`write_${sanitized}`] = ai.tool({
+        description: desc,
+        inputSchema: zod.z.object({
+          value: zod.z.string().describe(customType ? `JSON following ${customTypeName} schema` : "Value to write")
+        }),
+        execute: async ({ value }) => {
+          const success = mc.llm_set_key(key, value);
+          return success ? { result: `Wrote to ${key}`, key, value } : { result: `Failed to write to ${key}`, error: true };
+        }
+      });
+      if (attrs?.type === "document") {
+        tools[`append_${sanitized}`] = ai.tool({
+          description: `Append to "${key}" document`,
+          inputSchema: zod.z.object({ text: zod.z.string().describe("Text to append") }),
+          execute: async ({ text }) => {
+            const yText = mc.get_document(key);
+            if (yText) {
+              yText.insert(yText.length, text);
+              return { result: "Appended", key };
+            }
+            return { result: "Not found", error: true };
+          }
+        });
+        tools[`insert_${sanitized}`] = ai.tool({
+          description: `Insert text at position in "${key}" document`,
+          inputSchema: zod.z.object({
+            index: zod.z.number().describe("Position (0 = start)"),
+            text: zod.z.string().describe("Text to insert")
+          }),
+          execute: async ({ index, text }) => {
+            mc.insert_text(key, index, text);
+            return { result: `Inserted at ${index}`, key };
+          }
+        });
+        tools[`edit_${sanitized}`] = ai.tool({
+          description: `Find and replace in "${key}" document`,
+          inputSchema: zod.z.object({
+            find: zod.z.string().describe("Text to find"),
+            replace: zod.z.string().describe("Replacement")
+          }),
+          execute: async ({ find, replace }) => {
+            const yText = mc.get_document(key);
+            if (yText) {
+              const text = yText.toString();
+              const idx = text.indexOf(find);
+              if (idx !== -1) {
+                yText.delete(idx, find.length);
+                yText.insert(idx, replace);
+                return { result: `Replaced "${find}"`, key };
+              }
+              return { result: `"${find}" not found`, error: true };
+            }
+            return { result: "Document not found", error: true };
+          }
+        });
+      }
+    }
+    return tools;
+  }
+  /**
+   * Internal: Build tools with raw JSON Schema (framework-agnostic).
+   */
+  static _buildTools(mc) {
+    const tools = {};
+    const registeredTypes = mc.getRegisteredTypes();
+    const typeInfo = registeredTypes.length > 0 ? `Available types: ${registeredTypes.join(", ")}` : "No custom types registered";
+    tools["create_key"] = {
+      description: `Create a new key in MindCache. ${typeInfo}. The new key will be readable and writable by the LLM.`,
+      parameters: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: 'The key name to create (e.g., "contact_john_doe")' },
+          value: { type: "string", description: "The value to store (use JSON string for structured data)" },
+          type: {
+            type: "string",
+            description: registeredTypes.length > 0 ? `Optional: custom type name (${registeredTypes.join(" | ")})` : "Optional: custom type name (none registered)"
+          }
+        },
+        required: ["key", "value"]
+      },
+      execute: async ({ key, value, type }) => {
+        if (mc.has(key)) {
+          return {
+            result: `Key "${key}" already exists. Use write_${_AIToolBuilder.sanitizeKeyForTool(key)} to update it.`,
+            key,
+            error: true
+          };
+        }
+        if (type && !mc.getTypeSchema(type)) {
+          return {
+            result: `Type "${type}" is not registered. Available types: ${registeredTypes.join(", ") || "none"}`,
+            key,
+            error: true
+          };
+        }
+        mc.set_value(key, value, {
+          systemTags: ["SystemPrompt", "LLMRead", "LLMWrite"]
+        });
+        if (type) {
+          mc.setType(key, type);
+        }
+        return {
+          result: `Successfully created key "${key}"${type ? ` with type "${type}"` : ""}`,
+          key,
+          value,
+          type
+        };
+      }
+    };
     for (const key of mc.keys()) {
       if (key.startsWith("$")) {
         continue;
@@ -906,12 +1097,28 @@ var AIToolBuilder = class _AIToolBuilder {
       }
       const sanitizedKey = _AIToolBuilder.sanitizeKeyForTool(key);
       const isDocument = attributes?.type === "document";
+      const customTypeName = mc.getKeyType(key);
+      const customType = customTypeName ? mc.getTypeSchema(customTypeName) : void 0;
+      let writeDescription;
+      if (customType) {
+        const schemaGuidance = SchemaParser.toPromptDescription(customType);
+        const example = SchemaParser.generateExample(customType);
+        writeDescription = `Write a value to "${key}" that must follow this schema:
+${schemaGuidance}
+
+Example format:
+${example}`;
+      } else if (isDocument) {
+        writeDescription = `Rewrite the entire "${key}" document`;
+      } else {
+        writeDescription = `Write a value to the STM key: ${key}`;
+      }
       tools[`write_${sanitizedKey}`] = {
-        description: isDocument ? `Rewrite the entire "${key}" document` : `Write a value to the STM key: ${key}`,
-        inputSchema: {
+        description: writeDescription,
+        parameters: {
           type: "object",
           properties: {
-            value: { type: "string", description: isDocument ? "New document content" : "The value to write" }
+            value: { type: "string", description: customType ? `Value following ${customTypeName} schema` : isDocument ? "New document content" : "The value to write" }
           },
           required: ["value"]
         },
@@ -934,7 +1141,7 @@ var AIToolBuilder = class _AIToolBuilder {
       if (isDocument) {
         tools[`append_${sanitizedKey}`] = {
           description: `Append text to the end of "${key}" document`,
-          inputSchema: {
+          parameters: {
             type: "object",
             properties: {
               text: { type: "string", description: "Text to append" }
@@ -959,7 +1166,7 @@ var AIToolBuilder = class _AIToolBuilder {
         };
         tools[`insert_${sanitizedKey}`] = {
           description: `Insert text at a position in "${key}" document`,
-          inputSchema: {
+          parameters: {
             type: "object",
             properties: {
               index: { type: "number", description: "Position to insert at (0 = start)" },
@@ -982,7 +1189,7 @@ var AIToolBuilder = class _AIToolBuilder {
         };
         tools[`edit_${sanitizedKey}`] = {
           description: `Find and replace text in "${key}" document`,
-          inputSchema: {
+          parameters: {
             type: "object",
             properties: {
               find: { type: "string", description: "Text to find" },
@@ -1019,11 +1226,16 @@ var AIToolBuilder = class _AIToolBuilder {
     return tools;
   }
   /**
-     * Generate a system prompt containing all visible STM keys and their values.
-     * Indicates which tools can be used to modify writable keys.
-     */
+   * Generate a system prompt containing all visible STM keys and their values.
+   * Indicates which tools can be used to modify writable keys.
+   */
   static getSystemPrompt(mc) {
     const lines = [];
+    const registeredTypes = mc.getRegisteredTypes();
+    if (registeredTypes.length > 0) {
+      lines.push(`[create_key tool available - registered types: ${registeredTypes.join(", ")}]`);
+      lines.push("");
+    }
     for (const key of mc.keys()) {
       if (key.startsWith("$")) {
         continue;
@@ -1041,8 +1253,18 @@ var AIToolBuilder = class _AIToolBuilder {
       const isWritable = attributes?.systemTags?.includes("LLMWrite");
       const isDocument = attributes?.type === "document";
       const sanitizedKey = _AIToolBuilder.sanitizeKeyForTool(key);
+      const customTypeName = mc.getKeyType(key);
+      const customType = customTypeName ? mc.getTypeSchema(customTypeName) : void 0;
       if (isWritable) {
-        if (isDocument) {
+        if (customType) {
+          const schemaInfo = SchemaParser.toMarkdown(customType);
+          lines.push(
+            `${key} (type: ${customTypeName}): ${displayValue}
+Schema:
+${schemaInfo}
+Tool: write_${sanitizedKey}`
+          );
+        } else if (isDocument) {
           lines.push(
             `${key}: ${displayValue}. Document tools: write_${sanitizedKey}, append_${sanitizedKey}, edit_${sanitizedKey}`
           );
@@ -1053,15 +1275,19 @@ var AIToolBuilder = class _AIToolBuilder {
           );
         }
       } else {
-        lines.push(`${key}: ${displayValue}`);
+        if (customTypeName) {
+          lines.push(`${key} (type: ${customTypeName}): ${displayValue}`);
+        } else {
+          lines.push(`${key}: ${displayValue}`);
+        }
       }
     }
     return lines.join("\n");
   }
   /**
-     * Execute a tool call by name with the given value.
-     * Returns the result or null if tool not found.
-     */
+   * Execute a tool call by name with the given value.
+   * Returns the result or null if tool not found.
+   */
   static executeToolCall(mc, toolName, value) {
     const match = toolName.match(/^(write|append|insert|edit)_(.+)$/);
     if (!match) {
@@ -1388,7 +1614,7 @@ var MindCache = class {
   listeners = {};
   globalListeners = [];
   // Metadata
-  version = "3.3.2";
+  version = "3.6.0";
   // Internal flag to prevent sync loops when receiving remote updates
   // (Less critical with Yjs but kept for API compat)
   normalizeSystemTags(tags) {
@@ -1425,6 +1651,8 @@ var MindCache = class {
   _history = [];
   _historyOptions = { maxEntries: 100, snapshotInterval: 10 };
   _historyEnabled = false;
+  // Custom type registry
+  _typeRegistry = /* @__PURE__ */ new Map();
   constructor(options) {
     this.doc = options?.doc || new Y__namespace.Doc();
     this.rootMap = this.doc.getMap("mindcache");
@@ -2381,6 +2609,71 @@ var MindCache = class {
   systemGetKeysByTag(tag) {
     return TagManager.systemGetKeysByTag(this, tag);
   }
+  // ============================================
+  // Custom Type Methods
+  // ============================================
+  /**
+   * Register a custom type with a markdown schema definition.
+   *
+   * Schema format:
+   * ```
+   * #TypeName
+   * * fieldName: description of the field
+   * * anotherField: description
+   * ```
+   *
+   * @param name - Type name (e.g., 'Contact')
+   * @param schema - Markdown schema definition
+   * @throws Error if schema format is invalid
+   */
+  registerType(name, schema) {
+    const typeDef = SchemaParser.parse(schema);
+    typeDef.name = name;
+    this._typeRegistry.set(name, typeDef);
+  }
+  /**
+   * Assign a custom type to a key.
+   * The key must exist and the type must be registered.
+   * Also sets the underlying type to 'json' since custom types are structured JSON data.
+   *
+   * @param key - Key to assign type to
+   * @param typeName - Registered type name
+   * @throws Error if key doesn't exist or type is not registered
+   */
+  setType(key, typeName) {
+    if (!this.rootMap.has(key)) {
+      throw new Error(`Key "${key}" does not exist`);
+    }
+    if (!this._typeRegistry.has(typeName)) {
+      throw new Error(`Type "${typeName}" is not registered. Use registerType() first.`);
+    }
+    this.set_attributes(key, { type: "json", customType: typeName });
+  }
+  /**
+   * Get a registered type schema definition.
+   *
+   * @param typeName - Type name to look up
+   * @returns The type definition or undefined if not registered
+   */
+  getTypeSchema(typeName) {
+    return this._typeRegistry.get(typeName);
+  }
+  /**
+   * Get all registered type names.
+   */
+  getRegisteredTypes() {
+    return Array.from(this._typeRegistry.keys());
+  }
+  /**
+   * Get the custom type assigned to a key.
+   *
+   * @param key - Key to check
+   * @returns Type name or undefined if no custom type assigned
+   */
+  getKeyType(key) {
+    const attrs = this.get_attributes(key);
+    return attrs?.customType;
+  }
   /**
    * Helper to get sorted keys (by zIndex).
    * Respects context filtering when set.
@@ -2642,9 +2935,28 @@ var MindCache = class {
   findKeyFromSanitizedTool(sanitizedKey) {
     return AIToolBuilder.findKeyFromSanitizedTool(this, sanitizedKey);
   }
+  /**
+   * Generate framework-agnostic tools with raw JSON Schema.
+   * Works with: OpenAI SDK, Anthropic SDK, LangChain, and other frameworks.
+   *
+   * Tool format:
+   * {
+   *   description: string,
+   *   parameters: { type: 'object', properties: {...}, required: [...] },
+   *   execute: async (args) => result
+   * }
+   *
+   * Security: All tools use llm_set_key internally which:
+   * - Only modifies VALUES, never attributes/systemTags
+   * - Prevents LLMs from escalating privileges
+   */
+  create_tools() {
+    return AIToolBuilder.createTools(this);
+  }
   /**
    * Generate Vercel AI SDK compatible tools for writable keys.
-   * For document type keys, generates additional tools: append_, insert_, edit_
+   * Wraps parameters with jsonSchema() for AI SDK v5 compatibility.
+   * Use this with: generateText(), streamText() from 'ai' package.
    *
    * Security: All tools use llm_set_key internally which:
    * - Only modifies VALUES, never attributes/systemTags