llmist 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -384,6 +384,7 @@ var init_prompt_config = __esm({
       criticalUsage: "INVOKE gadgets using the markers - do not describe what you want to do.",
       formatDescriptionYaml: "Parameters in YAML format (one per line)",
       formatDescriptionJson: "Parameters in JSON format (valid JSON object)",
+      formatDescriptionToml: "Parameters in TOML format (key = value pairs, use triple-quotes for multiline)",
       rules: () => [
         "Output ONLY plain text with the exact markers - never use function/tool calling",
         "You can invoke multiple gadgets in a single response",
@@ -391,6 +392,7 @@ var init_prompt_config = __esm({
       ],
       schemaLabelJson: "\n\nInput Schema (JSON):",
       schemaLabelYaml: "\n\nInput Schema (YAML):",
+      schemaLabelToml: "\n\nInput Schema (TOML):",
       customExamples: null
     };
   }
@@ -411,6 +413,15 @@ var init_messages = __esm({
       constructor(promptConfig) {
         this.promptConfig = promptConfig ?? {};
       }
+      /**
+       * Set custom prefixes for gadget markers.
+       * Used to configure history builder to match system prompt markers.
+       */
+      withPrefixes(startPrefix, endPrefix) {
+        this.startPrefix = startPrefix;
+        this.endPrefix = endPrefix;
+        return this;
+      }
       addSystem(content, metadata) {
         this.messages.push({ role: "system", content, metadata });
         return this;
@@ -448,7 +459,14 @@ var init_messages = __esm({
         for (const gadget of gadgets) {
           const gadgetName = gadget.name ?? gadget.constructor.name;
           const instruction = gadget.getInstruction(parameterFormat);
-          const schemaMarker = parameterFormat === "yaml" ? "\n\nInput Schema (YAML):" : "\n\nInput Schema (JSON):";
+          const schemaMarkers = {
+            yaml: "\n\nInput Schema (YAML):",
+            json: "\n\nInput Schema (JSON):",
+            toml: "\n\nInput Schema (TOML):",
+            auto: "\n\nInput Schema (JSON):"
+            // auto defaults to JSON schema display
+          };
+          const schemaMarker = schemaMarkers[parameterFormat];
           const schemaIndex = instruction.indexOf(schemaMarker);
           const description = (schemaIndex !== -1 ? instruction.substring(0, schemaIndex) : instruction).trim();
           const schema = schemaIndex !== -1 ? instruction.substring(schemaIndex + schemaMarker.length).trim() : "";
@@ -468,15 +486,26 @@ ${schema}`);
       }
       buildUsageSection(parameterFormat, context) {
         const parts = [];
-        const formatDescription = parameterFormat === "yaml" ? resolvePromptTemplate(
-          this.promptConfig.formatDescriptionYaml,
-          DEFAULT_PROMPTS.formatDescriptionYaml,
-          context
-        ) : resolvePromptTemplate(
-          this.promptConfig.formatDescriptionJson,
-          DEFAULT_PROMPTS.formatDescriptionJson,
-          context
-        );
+        const formatDescriptionMap = {
+          yaml: {
+            config: this.promptConfig.formatDescriptionYaml,
+            defaultValue: DEFAULT_PROMPTS.formatDescriptionYaml
+          },
+          json: {
+            config: this.promptConfig.formatDescriptionJson,
+            defaultValue: DEFAULT_PROMPTS.formatDescriptionJson
+          },
+          toml: {
+            config: this.promptConfig.formatDescriptionToml,
+            defaultValue: DEFAULT_PROMPTS.formatDescriptionToml
+          },
+          auto: {
+            config: this.promptConfig.formatDescriptionJson,
+            defaultValue: DEFAULT_PROMPTS.formatDescriptionJson
+          }
+        };
+        const { config, defaultValue } = formatDescriptionMap[parameterFormat];
+        const formatDescription = resolvePromptTemplate(config, defaultValue, context);
         parts.push("\n\nHOW TO INVOKE GADGETS");
         parts.push("\n=====================\n");
         const criticalUsage = resolvePromptTemplate(
@@ -504,38 +533,110 @@ CRITICAL: ${criticalUsage}
           return this.promptConfig.customExamples(context);
         }
         const parts = [];
-        const singleExample = parameterFormat === "yaml" ? `${this.startPrefix}translate
+        const singleExamples = {
+          yaml: `${this.startPrefix}translate
 from: English
 to: Polish
-content: Paris is the capital of France.
-${this.endPrefix}` : `${this.startPrefix}translate
-{"from": "English", "to": "Polish", "content": "Paris is the capital of France."}
-${this.endPrefix}`;
+content: "Paris is the capital of France: a beautiful city."
+${this.endPrefix}`,
+          json: `${this.startPrefix}translate
+{"from": "English", "to": "Polish", "content": "Paris is the capital of France: a beautiful city."}
+${this.endPrefix}`,
+          toml: `${this.startPrefix}translate
+from = "English"
+to = "Polish"
+content = "Paris is the capital of France: a beautiful city."
+${this.endPrefix}`,
+          auto: `${this.startPrefix}translate
+{"from": "English", "to": "Polish", "content": "Paris is the capital of France: a beautiful city."}
+${this.endPrefix}`
+        };
         parts.push(`
 
 EXAMPLE (Single Gadget):
 
-${singleExample}`);
-        const multipleExample = parameterFormat === "yaml" ? `${this.startPrefix}translate
+${singleExamples[parameterFormat]}`);
+        const multipleExamples = {
+          yaml: `${this.startPrefix}translate
 from: English
 to: Polish
-content: Paris is the capital of France.
+content: "Paris is the capital of France: a beautiful city."
 ${this.endPrefix}
 ${this.startPrefix}analyze
 type: economic_analysis
 matter: "Polish Economy"
-question: Polish arms exports 2025.
-${this.endPrefix}` : `${this.startPrefix}translate
-{"from": "English", "to": "Polish", "content": "Paris is the capital of France."}
+question: |
+  Analyze the following:
+  - Polish arms exports 2025
+  - Economic implications
+${this.endPrefix}`,
+          json: `${this.startPrefix}translate
+{"from": "English", "to": "Polish", "content": "Paris is the capital of France: a beautiful city."}
+${this.endPrefix}
+${this.startPrefix}analyze
+{"type": "economic_analysis", "matter": "Polish Economy", "question": "Analyze the following: Polish arms exports 2025, economic implications"}
+${this.endPrefix}`,
+          toml: `${this.startPrefix}translate
+from = "English"
+to = "Polish"
+content = "Paris is the capital of France: a beautiful city."
+${this.endPrefix}
+${this.startPrefix}analyze
+type = "economic_analysis"
+matter = "Polish Economy"
+question = """
+Analyze the following:
+- Polish arms exports 2025
+- Economic implications
+"""
+${this.endPrefix}`,
+          auto: `${this.startPrefix}translate
+{"from": "English", "to": "Polish", "content": "Paris is the capital of France: a beautiful city."}
 ${this.endPrefix}
 ${this.startPrefix}analyze
-{"type": "economic_analysis", "matter": "Polish Economy", "question": "Polish arms exports 2025."}
-${this.endPrefix}`;
+{"type": "economic_analysis", "matter": "Polish Economy", "question": "Analyze the following: Polish arms exports 2025, economic implications"}
+${this.endPrefix}`
+        };
         parts.push(`
 
 EXAMPLE (Multiple Gadgets):
 
-${multipleExample}`);
+${multipleExamples[parameterFormat]}`);
+        if (parameterFormat === "yaml") {
+          parts.push(`
+
+YAML MULTILINE SYNTAX:
+For string values with special characters (colons, dashes, quotes) or multiple lines,
+use the pipe (|) syntax. ALL content lines MUST be indented with 2 spaces:
+
+CORRECT - all lines indented:
+question: |
+  Which option do you prefer?
+  - Option A: fast processing
+  - Option B: thorough analysis
+  Please choose one.
+
+WRONG - inconsistent indentation breaks YAML:
+question: |
+  Which option do you prefer?
+  - Option A: fast
+Please choose one.    <-- ERROR: not indented, breaks out of the block`);
+        } else if (parameterFormat === "toml") {
+          parts.push(`
+
+TOML MULTILINE SYNTAX:
+For string values with multiple lines or special characters, use triple-quotes ("""):
+
+filePath = "README.md"
+content = """
+# Project Title
+
+This content can contain:
+- Markdown lists
+- Special characters: # : -
+- Multiple paragraphs
+"""`);
+        }
         return parts.join("");
       }
       buildRulesSection(context) {
@@ -579,6 +680,16 @@ ${this.endPrefix}`
             return `${key}: ${JSON.stringify(value)}`;
           }).join("\n");
         }
+        if (format === "toml") {
+          return Object.entries(parameters).map(([key, value]) => {
+            if (typeof value === "string" && value.includes("\n")) {
+              return `${key} = """
+${value}
+"""`;
+            }
+            return `${key} = ${JSON.stringify(value)}`;
+          }).join("\n");
+        }
         return JSON.stringify(parameters);
       }
       build() {
@@ -680,11 +791,14 @@ var init_conversation_manager = __esm({
       initialMessages;
       historyBuilder;
       parameterFormat;
-      constructor(baseMessages, initialMessages, parameterFormat = "json") {
+      constructor(baseMessages, initialMessages, options = {}) {
         this.baseMessages = baseMessages;
         this.initialMessages = initialMessages;
-        this.parameterFormat = parameterFormat;
+        this.parameterFormat = options.parameterFormat ?? "json";
         this.historyBuilder = new LLMMessageBuilder();
+        if (options.startPrefix && options.endPrefix) {
+          this.historyBuilder.withPrefixes(options.startPrefix, options.endPrefix);
+        }
       }
       addUserMessage(content) {
         this.historyBuilder.addUser(content);
@@ -1185,11 +1299,109 @@ var init_executor = __esm({
 });
 
 // src/gadgets/parser.ts
-var yaml, globalInvocationCounter, StreamParser;
+function preprocessYaml(yamlStr) {
+  const lines = yamlStr.split("\n");
+  const result = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const match = line.match(/^(\s*)([\w-]+):\s+(.+)$/);
+    if (match) {
+      const [, indent, key, value] = match;
+      if (value === "|" || value === ">" || value === "|-" || value === ">-") {
+        result.push(line);
+        i++;
+        const keyIndentLen2 = indent.length;
+        const blockLines = [];
+        let minContentIndent = Infinity;
+        while (i < lines.length) {
+          const blockLine = lines[i];
+          const blockIndentMatch = blockLine.match(/^(\s*)/);
+          const blockIndentLen = blockIndentMatch ? blockIndentMatch[1].length : 0;
+          if (blockLine.trim() === "") {
+            blockLines.push({ content: "", originalIndent: 0 });
+            i++;
+            continue;
+          }
+          if (blockIndentLen > keyIndentLen2) {
+            const content = blockLine.substring(blockIndentLen);
+            blockLines.push({ content, originalIndent: blockIndentLen });
+            if (content.trim().length > 0) {
+              minContentIndent = Math.min(minContentIndent, blockIndentLen);
+            }
+            i++;
+          } else {
+            break;
+          }
+        }
+        const targetIndent = keyIndentLen2 + 2;
+        for (const blockLine of blockLines) {
+          if (blockLine.content === "") {
+            result.push("");
+          } else {
+            result.push(" ".repeat(targetIndent) + blockLine.content);
+          }
+        }
+        continue;
+      }
+      if (value.startsWith('"') || value.startsWith("'") || value === "true" || value === "false" || /^-?\d+(\.\d+)?$/.test(value)) {
+        result.push(line);
+        i++;
+        continue;
+      }
+      const keyIndentLen = indent.length;
+      const continuationLines = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const nextLine = lines[j];
+        if (nextLine.trim() === "") {
+          continuationLines.push(nextLine);
+          j++;
+          continue;
+        }
+        const nextIndentMatch = nextLine.match(/^(\s*)/);
+        const nextIndentLen = nextIndentMatch ? nextIndentMatch[1].length : 0;
+        if (nextIndentLen > keyIndentLen) {
+          continuationLines.push(nextLine);
+          j++;
+        } else {
+          break;
+        }
+      }
+      if (continuationLines.length > 0 && continuationLines.some((l) => l.trim().length > 0)) {
+        result.push(`${indent}${key}: |`);
+        result.push(`${indent}  ${value}`);
+        for (const contLine of continuationLines) {
+          if (contLine.trim() === "") {
+            result.push("");
+          } else {
+            const contIndentMatch = contLine.match(/^(\s*)/);
+            const contIndent = contIndentMatch ? contIndentMatch[1] : "";
+            const contContent = contLine.substring(contIndent.length);
+            result.push(`${indent}  ${contContent}`);
+          }
+        }
+        i = j;
+        continue;
+      }
+      if (value.includes(": ") || value.endsWith(":")) {
+        const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        result.push(`${indent}${key}: "${escaped}"`);
+        i++;
+        continue;
+      }
+    }
+    result.push(line);
+    i++;
+  }
+  return result.join("\n");
+}
+var yaml, import_js_toml, globalInvocationCounter, StreamParser;
 var init_parser = __esm({
   "src/gadgets/parser.ts"() {
     "use strict";
     yaml = __toESM(require("js-yaml"), 1);
+    import_js_toml = require("js-toml");
     init_constants();
     globalInvocationCounter = 0;
     StreamParser = class {
@@ -1211,6 +1423,17 @@ var init_parser = __esm({
         this.lastReportedTextLength = index;
         return segment.trim().length > 0 ? segment : void 0;
       }
+      /**
+       * Parse gadget name, handling both old format (name:invocationId) and new format (just name).
+       * For new format, generates a unique invocation ID.
+       */
+      parseGadgetName(gadgetName) {
+        if (gadgetName.includes(":")) {
+          const parts = gadgetName.split(":");
+          return { actualName: parts[0], invocationId: parts[1] };
+        }
+        return { actualName: gadgetName, invocationId: `gadget_${++globalInvocationCounter}` };
+      }
       /**
        * Parse parameter string according to configured format
        */
@@ -1224,20 +1447,31 @@ var init_parser = __esm({
         }
         if (this.parameterFormat === "yaml") {
           try {
-            return { parameters: yaml.load(raw) };
+            return { parameters: yaml.load(preprocessYaml(raw)) };
           } catch (error) {
             return { parseError: error instanceof Error ? error.message : "Failed to parse YAML" };
           }
         }
+        if (this.parameterFormat === "toml") {
+          try {
+            return { parameters: (0, import_js_toml.load)(raw) };
+          } catch (error) {
+            return { parseError: error instanceof Error ? error.message : "Failed to parse TOML" };
+          }
+        }
         try {
           return { parameters: JSON.parse(raw) };
         } catch {
           try {
-            return { parameters: yaml.load(raw) };
-          } catch (error) {
-            return {
-              parseError: error instanceof Error ? error.message : "Failed to parse as JSON or YAML"
-            };
+            return { parameters: (0, import_js_toml.load)(raw) };
+          } catch {
+            try {
+              return { parameters: yaml.load(preprocessYaml(raw)) };
+            } catch (error) {
+              return {
+                parseError: error instanceof Error ? error.message : "Failed to parse as JSON, TOML, or YAML"
+              };
+            }
           }
         }
       }
@@ -1256,16 +1490,7 @@ var init_parser = __esm({
           const metadataEndIndex = this.buffer.indexOf("\n", metadataStartIndex);
           if (metadataEndIndex === -1) break;
           const gadgetName = this.buffer.substring(metadataStartIndex, metadataEndIndex).trim();
-          let invocationId;
-          let actualGadgetName;
-          if (gadgetName.includes(":")) {
-            const parts = gadgetName.split(":");
-            actualGadgetName = parts[0];
-            invocationId = parts[1];
-          } else {
-            actualGadgetName = gadgetName;
-            invocationId = `gadget_${++globalInvocationCounter}`;
-          }
+          const { actualName: actualGadgetName, invocationId } = this.parseGadgetName(gadgetName);
           const contentStartIndex = metadataEndIndex + 1;
           let partEndIndex;
           let endMarkerLength = 0;
@@ -1275,23 +1500,29 @@ var init_parser = __esm({
             if (partEndIndex === -1) break;
             endMarkerLength = oldEndMarker.length;
           } else {
-            partEndIndex = contentStartIndex;
+            const nextStartPos = this.buffer.indexOf(this.startPrefix, contentStartIndex);
+            let validEndPos = -1;
+            let searchPos = contentStartIndex;
             while (true) {
-              const endPos = this.buffer.indexOf(this.endPrefix, partEndIndex);
-              if (endPos === -1) {
-                partEndIndex = -1;
-                break;
-              }
+              const endPos = this.buffer.indexOf(this.endPrefix, searchPos);
+              if (endPos === -1) break;
               const afterEnd = this.buffer.substring(endPos + this.endPrefix.length);
               if (afterEnd.startsWith("\n") || afterEnd.startsWith("\r") || afterEnd.startsWith(this.startPrefix) || afterEnd.length === 0) {
-                partEndIndex = endPos;
-                endMarkerLength = this.endPrefix.length;
+                validEndPos = endPos;
                 break;
               } else {
-                partEndIndex = endPos + this.endPrefix.length;
+                searchPos = endPos + this.endPrefix.length;
               }
             }
-            if (partEndIndex === -1) break;
+            if (nextStartPos !== -1 && (validEndPos === -1 || nextStartPos < validEndPos)) {
+              partEndIndex = nextStartPos;
+              endMarkerLength = 0;
+            } else if (validEndPos !== -1) {
+              partEndIndex = validEndPos;
+              endMarkerLength = this.endPrefix.length;
+            } else {
+              break;
+            }
           }
           const parametersRaw = this.buffer.substring(contentStartIndex, partEndIndex).trim();
           const { parameters, parseError } = this.parseParameters(parametersRaw);
@@ -1314,8 +1545,35 @@ var init_parser = __esm({
           this.lastReportedTextLength = 0;
         }
       }
-      // Finalize parsing and return remaining text
+      // Finalize parsing and return remaining text or incomplete gadgets
       *finalize() {
+        const startIndex = this.buffer.indexOf(this.startPrefix, this.lastReportedTextLength);
+        if (startIndex !== -1) {
+          const textBefore = this.takeTextUntil(startIndex);
+          if (textBefore !== void 0) {
+            yield { type: "text", content: textBefore };
+          }
+          const metadataStartIndex = startIndex + this.startPrefix.length;
+          const metadataEndIndex = this.buffer.indexOf("\n", metadataStartIndex);
+          if (metadataEndIndex !== -1) {
+            const gadgetName = this.buffer.substring(metadataStartIndex, metadataEndIndex).trim();
+            const { actualName: actualGadgetName, invocationId } = this.parseGadgetName(gadgetName);
+            const contentStartIndex = metadataEndIndex + 1;
+            const parametersRaw = this.buffer.substring(contentStartIndex).trim();
+            const { parameters, parseError } = this.parseParameters(parametersRaw);
+            yield {
+              type: "gadget_call",
+              call: {
+                gadgetName: actualGadgetName,
+                invocationId,
+                parametersYaml: parametersRaw,
+                parameters,
+                parseError
+              }
+            };
+            return;
+          }
+        }
         const remainingText = this.takeTextUntil(this.buffer.length);
         if (remainingText !== void 0) {
           yield { type: "text", content: remainingText };
@@ -1796,11 +2054,11 @@ var init_agent = __esm({
           role: message.role,
           content: message.content
         }));
-        this.conversation = new ConversationManager(
-          baseMessages,
-          initialMessages,
-          this.parameterFormat
-        );
+        this.conversation = new ConversationManager(baseMessages, initialMessages, {
+          parameterFormat: this.parameterFormat,
+          startPrefix: options.gadgetStartPrefix,
+          endPrefix: options.gadgetEndPrefix
+        });
         this.userPromptProvided = !!options.userPrompt;
         if (options.userPrompt) {
           this.conversation.addUserMessage(options.userPrompt);
@@ -2791,10 +3049,11 @@ var init_gemini = __esm({
         return GEMINI_MODELS;
       }
       buildRequestPayload(options, descriptor, _spec, messages) {
-        const { systemInstruction, contents } = this.extractSystemAndContents(messages);
+        const contents = this.convertMessagesToContents(messages);
         const generationConfig = this.buildGenerationConfig(options);
         const config = {
-          ...systemInstruction ? { systemInstruction: systemInstruction.parts.map((p) => p.text).join("\n") } : {},
+          // Note: systemInstruction removed - it doesn't work with countTokens()
+          // System messages are now included in contents as user+model exchanges
           ...generationConfig ? { ...generationConfig } : {},
           // Explicitly disable function calling to prevent UNEXPECTED_TOOL_CALL errors
           toolConfig: {
@@ -2815,31 +3074,37 @@ var init_gemini = __esm({
         const streamResponse = await client.models.generateContentStream(payload);
         return streamResponse;
       }
-      extractSystemAndContents(messages) {
-        const firstSystemIndex = messages.findIndex((message) => message.role === "system");
-        if (firstSystemIndex === -1) {
-          return {
-            systemInstruction: null,
-            contents: this.mergeConsecutiveMessages(messages)
-          };
+      /**
+       * Convert LLM messages to Gemini contents format.
+       *
+       * For Gemini, we convert system messages to user+model exchanges instead of
+       * using systemInstruction, because:
+       * 1. systemInstruction doesn't work with countTokens() API
+       * 2. This approach gives perfect token counting accuracy (0% error)
+       * 3. The model receives and follows system instructions identically
+       *
+       * System message: "You are a helpful assistant"
+       * Becomes:
+       * - User: "You are a helpful assistant"
+       * - Model: "Understood."
+       */
+      convertMessagesToContents(messages) {
+        const expandedMessages = [];
+        for (const message of messages) {
+          if (message.role === "system") {
+            expandedMessages.push({
+              role: "user",
+              content: message.content
+            });
+            expandedMessages.push({
+              role: "assistant",
+              content: "Understood."
+            });
+          } else {
+            expandedMessages.push(message);
+          }
         }
-        let systemBlockEnd = firstSystemIndex;
-        while (systemBlockEnd < messages.length && messages[systemBlockEnd].role === "system") {
-          systemBlockEnd++;
-        }
-        const systemMessages = messages.slice(firstSystemIndex, systemBlockEnd);
-        const nonSystemMessages = [
-          ...messages.slice(0, firstSystemIndex),
-          ...messages.slice(systemBlockEnd)
-        ];
-        const systemInstruction = {
-          role: "system",
-          parts: systemMessages.map((message) => ({ text: message.content }))
-        };
-        return {
-          systemInstruction,
-          contents: this.mergeConsecutiveMessages(nonSystemMessages)
-        };
+        return this.mergeConsecutiveMessages(expandedMessages);
       }
       mergeConsecutiveMessages(messages) {
         if (messages.length === 0) {
@@ -2928,8 +3193,8 @@ var init_gemini = __esm({
        *
        * This method provides accurate token estimation for Gemini models by:
        * - Using the SDK's countTokens() method
-       * - Properly extracting and handling system instructions
-       * - Transforming messages to Gemini's expected format
+       * - Converting system messages to user+model exchanges (same as in generation)
+       * - This gives perfect token counting accuracy (0% error vs actual usage)
        *
        * @param messages - The messages to count tokens for
        * @param descriptor - Model descriptor containing the model name
@@ -2948,16 +3213,14 @@ var init_gemini = __esm({
        */
       async countTokens(messages, descriptor, _spec) {
         const client = this.client;
-        const { systemInstruction, contents } = this.extractSystemAndContents(messages);
-        const request = {
-          model: descriptor.name,
-          contents: this.convertContentsForNewSDK(contents)
-        };
-        if (systemInstruction) {
-          request.systemInstruction = systemInstruction.parts.map((p) => p.text).join("\n");
-        }
+        const contents = this.convertMessagesToContents(messages);
         try {
-          const response = await client.models.countTokens(request);
+          const response = await client.models.countTokens({
+            model: descriptor.name,
+            contents: this.convertContentsForNewSDK(contents)
+            // Note: systemInstruction not used - it's not supported by countTokens()
+            // and would cause a 2100% token counting error
+          });
           return response.totalTokens ?? 0;
         } catch (error) {
           console.warn(
@@ -5185,6 +5448,83 @@ function mergeDescriptions(schema, jsonSchema) {
 
 // src/gadgets/gadget.ts
 init_schema_validator();
+function formatYamlValue(value, indent = "") {
+  if (typeof value === "string") {
+    const lines = value.split("\n");
+    if (lines.length === 1 && !value.includes(":") && !value.startsWith("-")) {
+      return value;
+    }
+    const indentedLines = lines.map((line) => `${indent}  ${line}`).join("\n");
+    return `|
+${indentedLines}`;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const items = value.map((item) => `${indent}- ${formatYamlValue(item, indent + "  ")}`);
+    return "\n" + items.join("\n");
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    const lines = entries.map(([k, v]) => {
+      const formattedValue = formatYamlValue(v, indent + "  ");
+      if (formattedValue.startsWith("\n") || formattedValue.startsWith("|")) {
+        return `${indent}${k}: ${formattedValue}`;
+      }
+      return `${indent}${k}: ${formattedValue}`;
+    });
+    return "\n" + lines.join("\n");
+  }
+  return yaml2.dump(value).trimEnd();
+}
+function formatParamsAsYaml(params) {
+  const lines = [];
+  for (const [key, value] of Object.entries(params)) {
+    const formattedValue = formatYamlValue(value, "");
+    if (formattedValue.startsWith("\n")) {
+      lines.push(`${key}:${formattedValue}`);
+    } else {
+      lines.push(`${key}: ${formattedValue}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatTomlValue(value) {
+  if (typeof value === "string") {
+    if (value.includes("\n")) {
+      return `"""
+${value}
+"""`;
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value === null || value === void 0) {
+    return '""';
+  }
+  if (Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return JSON.stringify(value);
+}
+function formatParamsAsToml(params) {
+  const lines = [];
+  for (const [key, value] of Object.entries(params)) {
+    lines.push(`${key} = ${formatTomlValue(value)}`);
+  }
+  return lines.join("\n");
+}
 var BaseGadget = class {
   /**
    * The name of the gadget. Used for identification when LLM calls it.
@@ -5204,6 +5544,14 @@ var BaseGadget = class {
    * Set to 0 or undefined to disable timeout for this gadget.
    */
   timeoutMs;
+  /**
+   * Optional usage examples to help LLMs understand proper invocation.
+   * Examples are rendered in getInstruction() alongside the schema.
+   *
+   * Note: Uses broader `unknown` type to allow typed examples from subclasses
+   * while maintaining runtime compatibility.
+   */
+  examples;
   /**
    * Auto-generated instruction text for the LLM.
    * Combines name, description, and parameter schema into a formatted instruction.
@@ -5216,7 +5564,7 @@ var BaseGadget = class {
    * Generate instruction text for the LLM with format-specific schema.
    * Combines name, description, and parameter schema into a formatted instruction.
    *
-   * @param format - Format for the schema representation ('json' | 'yaml' | 'auto')
+   * @param format - Format for the schema representation ('json' | 'yaml' | 'toml' | 'auto')
    * @returns Formatted instruction string
    */
   getInstruction(format = "json") {
@@ -5231,12 +5579,38 @@ var BaseGadget = class {
       if (format === "json" || format === "auto") {
         parts.push("\n\nInput Schema (JSON):");
         parts.push(JSON.stringify(jsonSchema, null, 2));
+      } else if (format === "toml") {
+        parts.push("\n\nInput Schema (TOML):");
+        parts.push(JSON.stringify(jsonSchema, null, 2));
       } else {
         const yamlSchema = yaml2.dump(jsonSchema).trimEnd();
         parts.push("\n\nInput Schema (YAML):");
         parts.push(yamlSchema);
       }
     }
+    if (this.examples && this.examples.length > 0) {
+      parts.push("\n\nExamples:");
+      this.examples.forEach((example, index) => {
+        if (index > 0) {
+          parts.push("");
+        }
+        if (example.comment) {
+          parts.push(`# ${example.comment}`);
+        }
+        parts.push("Input:");
+        if (format === "json" || format === "auto") {
+          parts.push(JSON.stringify(example.params, null, 2));
+        } else if (format === "toml") {
+          parts.push(formatParamsAsToml(example.params));
+        } else {
+          parts.push(formatParamsAsYaml(example.params));
+        }
+        if (example.output !== void 0) {
+          parts.push("Output:");
+          parts.push(example.output);
+        }
+      });
+    }
     return parts.join("\n");
   }
 };
@@ -5248,6 +5622,7 @@ function createGadget(config) {
     description = config.description;
     parameterSchema = config.schema;
     timeoutMs = config.timeoutMs;
+    examples = config.examples;
     execute(params) {
       return config.execute(params);
     }
@@ -5268,6 +5643,7 @@ function Gadget(config) {
     parameterSchema = config.schema;
     name = config.name;
     timeoutMs = config.timeoutMs;
+    examples = config.examples;
     /**
      * Type helper property for accessing inferred parameter type.
      * This is used in the execute method signature: `execute(params: this['params'])`