llmist 0.6.1 → 0.7.0

package/dist/cli.cjs

@@ -31,6 +31,20 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/core/constants.ts
+var GADGET_START_PREFIX, GADGET_END_PREFIX, DEFAULT_GADGET_OUTPUT_LIMIT, DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT, CHARS_PER_TOKEN, FALLBACK_CONTEXT_WINDOW;
+var init_constants = __esm({
+  "src/core/constants.ts"() {
+    "use strict";
+    GADGET_START_PREFIX = "!!!GADGET_START:";
+    GADGET_END_PREFIX = "!!!GADGET_END";
+    DEFAULT_GADGET_OUTPUT_LIMIT = true;
+    DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT = 15;
+    CHARS_PER_TOKEN = 4;
+    FALLBACK_CONTEXT_WINDOW = 128e3;
+  }
+});
+
 // src/core/model-shortcuts.ts
 function isKnownModelPattern(model) {
   const normalized = model.toLowerCase();
@@ -328,20 +342,6 @@ var init_registry = __esm({
   }
 });
 
-// src/core/constants.ts
-var GADGET_START_PREFIX, GADGET_END_PREFIX, DEFAULT_GADGET_OUTPUT_LIMIT, DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT, CHARS_PER_TOKEN, FALLBACK_CONTEXT_WINDOW;
-var init_constants = __esm({
-  "src/core/constants.ts"() {
-    "use strict";
-    GADGET_START_PREFIX = "!!!GADGET_START:";
-    GADGET_END_PREFIX = "!!!GADGET_END";
-    DEFAULT_GADGET_OUTPUT_LIMIT = true;
-    DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT = 15;
-    CHARS_PER_TOKEN = 4;
-    FALLBACK_CONTEXT_WINDOW = 128e3;
-  }
-});
-
 // src/core/prompt-config.ts
 function resolvePromptTemplate(template, defaultValue, context) {
   const resolved = template ?? defaultValue;
@@ -625,7 +625,9 @@ This content can contain:
 - Multiple paragraphs
 EOF
 
-The delimiter (EOF) can be any identifier. The closing delimiter must be on its own line.`);
+The delimiter (EOF) can be any identifier. The closing delimiter must be on its own line.
+IMPORTANT: Content inside heredoc is LITERAL - do NOT escape backticks, dollar signs, or any characters.
+NEVER use TOML triple-quote strings ("""). ALWAYS use heredoc syntax (<<<EOF...EOF) for multiline content.`);
         }
         return parts.join("");
       }
@@ -673,9 +675,9 @@ ${this.endPrefix}`
         if (format === "toml") {
           return Object.entries(parameters).map(([key, value]) => {
             if (typeof value === "string" && value.includes("\n")) {
-              return `${key} = """
+              return `${key} = <<<EOF
 ${value}
-"""`;
+EOF`;
             }
             return `${key} = ${JSON.stringify(value)}`;
           }).join("\n");
@@ -921,6 +923,10 @@ function formatParamsAsYaml(params) {
   }
   return lines.join("\n");
 }
+function formatTomlInlineTable(obj) {
+  const entries = Object.entries(obj).map(([k, v]) => `${k} = ${formatTomlValue(v)}`);
+  return `{ ${entries.join(", ")} }`;
+}
 function formatTomlValue(value) {
   if (typeof value === "string") {
     if (value.includes("\n")) {
@@ -938,10 +944,17 @@ ${delimiter}`;
     return '""';
   }
   if (Array.isArray(value)) {
-    return JSON.stringify(value);
+    if (value.length === 0) return "[]";
+    const items = value.map((item) => {
+      if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+        return formatTomlInlineTable(item);
+      }
+      return formatTomlValue(item);
+    });
+    return `[${items.join(", ")}]`;
   }
   if (typeof value === "object") {
-    return JSON.stringify(value);
+    return formatTomlInlineTable(value);
   }
   return JSON.stringify(value);
 }
@@ -1632,7 +1645,8 @@ var init_executor = __esm({
           if (call.parseError || !call.parameters) {
             this.logger.error("Gadget parameter parse error", {
               gadgetName: call.gadgetName,
-              parseError: call.parseError
+              parseError: call.parseError,
+              rawParameters: call.parametersYaml
             });
             return {
               gadgetName: call.gadgetName,
@@ -1911,6 +1925,9 @@ function preprocessYaml(yamlStr) {
   }
   return result.join("\n");
 }
+function unescapeHeredocContent(content) {
+  return content.replace(/\\`/g, "`").replace(/\\\$/g, "$").replace(/\\{/g, "{").replace(/\\}/g, "}");
+}
 function preprocessTomlHeredoc(tomlStr) {
   const lines = tomlStr.split("\n");
   const result = [];
@@ -1936,13 +1953,13 @@ function preprocessTomlHeredoc(tomlStr) {
         i++;
       }
       if (bodyLines.length === 0) {
-        result.push(`${indent}${key} = """"""`);
+        result.push(`${indent}${key} = ''''''`);
       } else {
-        result.push(`${indent}${key} = """`);
+        result.push(`${indent}${key} = '''`);
         for (let j = 0; j < bodyLines.length - 1; j++) {
-          result.push(bodyLines[j]);
+          result.push(unescapeHeredocContent(bodyLines[j]));
         }
-        result.push(`${bodyLines[bodyLines.length - 1]}"""`);
+        result.push(`${unescapeHeredocContent(bodyLines[bodyLines.length - 1])}'''`);
       }
       if (!foundClosing) {
       }
@@ -1953,6 +1970,14 @@ function preprocessTomlHeredoc(tomlStr) {
   }
   return result.join("\n");
 }
+function stripMarkdownFences(content) {
+  let cleaned = content.trim();
+  const openingFence = /^```(?:toml|yaml|json)?\s*\n/i;
+  const closingFence = /\n?```\s*$/;
+  cleaned = cleaned.replace(openingFence, "");
+  cleaned = cleaned.replace(closingFence, "");
+  return cleaned.trim();
+}
 var yaml2, import_js_toml, globalInvocationCounter, StreamParser;
 var init_parser = __esm({
   "src/gadgets/parser.ts"() {
@@ -1991,43 +2016,55 @@ var init_parser = __esm({
         }
         return { actualName: gadgetName, invocationId: `gadget_${++globalInvocationCounter}` };
       }
+      /**
+       * Truncate verbose parse errors to avoid context overflow.
+       * Keeps first meaningful line and limits total length.
+       */
+      truncateParseError(error, format) {
+        const message = error instanceof Error ? error.message : String(error);
+        const firstLine = message.split("\n")[0];
+        const maxLen = 200;
+        if (firstLine.length <= maxLen) {
+          return firstLine;
+        }
+        return `${firstLine.slice(0, maxLen)}... (${message.length} chars total)`;
+      }
       /**
        * Parse parameter string according to configured format
        */
       parseParameters(raw) {
+        const cleaned = stripMarkdownFences(raw);
         if (this.parameterFormat === "json") {
           try {
-            return { parameters: JSON.parse(raw) };
+            return { parameters: JSON.parse(cleaned) };
           } catch (error) {
-            return { parseError: error instanceof Error ? error.message : "Failed to parse JSON" };
+            return { parseError: this.truncateParseError(error, "JSON") };
           }
         }
         if (this.parameterFormat === "yaml") {
           try {
-            return { parameters: yaml2.load(preprocessYaml(raw)) };
+            return { parameters: yaml2.load(preprocessYaml(cleaned)) };
           } catch (error) {
-            return { parseError: error instanceof Error ? error.message : "Failed to parse YAML" };
+            return { parseError: this.truncateParseError(error, "YAML") };
           }
         }
         if (this.parameterFormat === "toml") {
           try {
-            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(raw)) };
+            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(cleaned)) };
           } catch (error) {
-            return { parseError: error instanceof Error ? error.message : "Failed to parse TOML" };
+            return { parseError: this.truncateParseError(error, "TOML") };
           }
         }
         try {
-          return { parameters: JSON.parse(raw) };
+          return { parameters: JSON.parse(cleaned) };
         } catch {
           try {
-            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(raw)) };
+            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(cleaned)) };
           } catch {
             try {
-              return { parameters: yaml2.load(preprocessYaml(raw)) };
+              return { parameters: yaml2.load(preprocessYaml(cleaned)) };
             } catch (error) {
-              return {
-                parseError: error instanceof Error ? error.message : "Failed to parse as JSON, TOML, or YAML"
-              };
+              return { parseError: this.truncateParseError(error, "auto") };
             }
           }
         }
@@ -2329,7 +2366,8 @@ var init_stream_processor = __esm({
         if (call.parseError) {
           this.logger.warn("Gadget has parse error", {
             gadgetName: call.gadgetName,
-            error: call.parseError
+            error: call.parseError,
+            rawParameters: call.parametersYaml
           });
           const shouldContinue = await this.checkContinueAfterError(
             call.parseError,
@@ -2570,6 +2608,7 @@ var init_agent = __esm({
       gadgetEndPrefix;
       onHumanInputRequired;
       textOnlyHandler;
+      textWithGadgetsHandler;
       stopOnGadgetError;
       shouldContinueAfterError;
       defaultGadgetTimeoutMs;
@@ -2600,6 +2639,7 @@ var init_agent = __esm({
         this.gadgetEndPrefix = options.gadgetEndPrefix;
         this.onHumanInputRequired = options.onHumanInputRequired;
         this.textOnlyHandler = options.textOnlyHandler ?? "terminate";
+        this.textWithGadgetsHandler = options.textWithGadgetsHandler;
         this.stopOnGadgetError = options.stopOnGadgetError ?? true;
         this.shouldContinueAfterError = options.shouldContinueAfterError;
         this.defaultGadgetTimeoutMs = options.defaultGadgetTimeoutMs;
@@ -2787,6 +2827,17 @@ var init_agent = __esm({
               }
             }
             if (result.didExecuteGadgets) {
+              if (this.textWithGadgetsHandler) {
+                const textContent = result.outputs.filter((output) => output.type === "text").map((output) => output.content).join("");
+                if (textContent.trim()) {
+                  const { gadgetName, parameterMapping, resultMapping } = this.textWithGadgetsHandler;
+                  this.conversation.addGadgetCall(
+                    gadgetName,
+                    parameterMapping(textContent),
+                    resultMapping ? resultMapping(textContent) : textContent
+                  );
+                }
+              }
               for (const output of result.outputs) {
                 if (output.type === "gadget_result") {
                   const gadgetResult = output.result;
@@ -2798,7 +2849,13 @@ var init_agent = __esm({
                 }
               }
             } else {
-              this.conversation.addAssistantMessage(finalMessage);
+              if (finalMessage.trim()) {
+                this.conversation.addGadgetCall(
+                  "TellUser",
+                  { message: finalMessage, done: false, type: "info" },
+                  `\u2139\uFE0F  ${finalMessage}`
+                );
+              }
               const shouldBreak = await this.handleTextOnlyResponse(finalMessage);
               if (shouldBreak) {
                 break;
@@ -4672,6 +4729,7 @@ var AgentBuilder;
 var init_builder = __esm({
   "src/agent/builder.ts"() {
     "use strict";
+    init_constants();
     init_model_shortcuts();
     init_registry();
     init_agent();
@@ -4693,6 +4751,7 @@ var init_builder = __esm({
       gadgetStartPrefix;
       gadgetEndPrefix;
       textOnlyHandler;
+      textWithGadgetsHandler;
       stopOnGadgetError;
       shouldContinueAfterError;
       defaultGadgetTimeoutMs;
@@ -4955,6 +5014,30 @@ var init_builder = __esm({
         this.textOnlyHandler = handler;
         return this;
       }
+      /**
+       * Set the handler for text content that appears alongside gadget calls.
+       *
+       * When set, text accompanying gadget responses will be wrapped as a
+       * synthetic gadget call before the actual gadget results in the
+       * conversation history.
+       *
+       * @param handler - Configuration for wrapping text
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * // Wrap text as TellUser gadget
+       * .withTextWithGadgetsHandler({
+       *   gadgetName: "TellUser",
+       *   parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
+       *   resultMapping: (text) => `ℹ️  ${text}`,
+       * })
+       * ```
+       */
+      withTextWithGadgetsHandler(handler) {
+        this.textWithGadgetsHandler = handler;
+        return this;
+      }
       /**
        * Set whether to stop gadget execution on first error.
        *
@@ -5069,6 +5152,69 @@ var init_builder = __esm({
         this.gadgetOutputLimitPercent = percent;
         return this;
       }
+      /**
+       * Add a synthetic gadget call to the conversation history.
+       *
+       * This is useful for in-context learning - showing the LLM what "past self"
+       * did correctly so it mimics the pattern. The call is formatted with proper
+       * markers and parameter format.
+       *
+       * @param gadgetName - Name of the gadget
+       * @param parameters - Parameters passed to the gadget
+       * @param result - Result returned by the gadget
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * .withSyntheticGadgetCall(
+       *   'TellUser',
+       *   {
+       *     message: '👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
+       *     done: false,
+       *     type: 'info'
+       *   },
+       *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands'
+       * )
+       * ```
+       */
+      withSyntheticGadgetCall(gadgetName, parameters, result) {
+        const startPrefix = this.gadgetStartPrefix ?? GADGET_START_PREFIX;
+        const endPrefix = this.gadgetEndPrefix ?? GADGET_END_PREFIX;
+        const format = this.parameterFormat ?? "yaml";
+        const paramStr = this.formatSyntheticParameters(parameters, format);
+        this.initialMessages.push({
+          role: "assistant",
+          content: `${startPrefix}${gadgetName}
+${paramStr}
+${endPrefix}`
+        });
+        this.initialMessages.push({
+          role: "user",
+          content: `Result: ${result}`
+        });
+        return this;
+      }
+      /**
+       * Format parameters for synthetic gadget calls.
+       * Uses heredoc for multiline string values.
+       */
+      formatSyntheticParameters(parameters, format) {
+        if (format === "json" || format === "auto") {
+          return JSON.stringify(parameters);
+        }
+        return Object.entries(parameters).map(([key, value]) => {
+          if (typeof value === "string" && value.includes("\n")) {
+            const separator = format === "yaml" ? ":" : " =";
+            return `${key}${separator} <<<EOF
+${value}
+EOF`;
+          }
+          if (format === "yaml") {
+            return typeof value === "string" ? `${key}: ${value}` : `${key}: ${JSON.stringify(value)}`;
+          }
+          return `${key} = ${JSON.stringify(value)}`;
+        }).join("\n");
+      }
       /**
        * Build and create the agent with the given user prompt.
        * Returns the Agent instance ready to run.
@@ -5111,6 +5257,7 @@ var init_builder = __esm({
           gadgetStartPrefix: this.gadgetStartPrefix,
           gadgetEndPrefix: this.gadgetEndPrefix,
           textOnlyHandler: this.textOnlyHandler,
+          textWithGadgetsHandler: this.textWithGadgetsHandler,
           stopOnGadgetError: this.stopOnGadgetError,
           shouldContinueAfterError: this.shouldContinueAfterError,
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
@@ -5212,6 +5359,7 @@ var init_builder = __esm({
           gadgetStartPrefix: this.gadgetStartPrefix,
           gadgetEndPrefix: this.gadgetEndPrefix,
           textOnlyHandler: this.textOnlyHandler,
+          textWithGadgetsHandler: this.textWithGadgetsHandler,
           stopOnGadgetError: this.stopOnGadgetError,
           shouldContinueAfterError: this.shouldContinueAfterError,
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
@@ -5271,7 +5419,7 @@ var import_commander3 = require("commander");
 // package.json
 var package_default = {
   name: "llmist",
-  version: "0.6.0",
+  version: "0.6.2",
   description: "Universal TypeScript LLM client with streaming-first agent framework. Works with any model - no structured outputs or native tool calling required. Implements its own flexible grammar for function calling.",
   type: "module",
   main: "dist/index.cjs",
@@ -5419,7 +5567,7 @@ var tellUser = createGadget({
   name: "TellUser",
   description: "Tell the user something important. Set done=true when your work is complete and you want to end the conversation.",
   schema: import_zod2.z.object({
-    message: import_zod2.z.string().describe("The message to display to the user in Markdown"),
+    message: import_zod2.z.string().optional().describe("The message to display to the user in Markdown"),
     done: import_zod2.z.boolean().default(false).describe("Set to true to end the conversation, false to continue"),
     type: import_zod2.z.enum(["info", "success", "warning", "error"]).default("info").describe("Message type: info, success, warning, or error")
   }),
@@ -5439,9 +5587,20 @@ var tellUser = createGadget({
         done: false,
         type: "warning"
       }
+    },
+    {
+      comment: "Share detailed analysis with bullet points (use heredoc for multiline)",
+      params: {
+        message: "Here's what I found in the codebase:\n\n1. **Main entry point**: `src/index.ts` exports all public APIs\n2. **Core logic**: Located in `src/core/` with 5 modules\n3. **Tests**: Good coverage in `src/__tests__/`\n\nI'll continue exploring the core modules.",
+        done: false,
+        type: "info"
+      }
     }
   ],
   execute: ({ message, done, type }) => {
+    if (!message || message.trim() === "") {
+      return "\u26A0\uFE0F  TellUser was called without a message. Please provide content in the 'message' field.";
+    }
     const prefixes = {
       info: "\u2139\uFE0F  ",
       success: "\u2705 ",
@@ -5723,53 +5882,6 @@ ${rendered}`;
 }
 
 // src/cli/utils.ts
-var RARE_EMOJI = [
-  "\u{1F531}",
-  "\u2697\uFE0F",
-  "\u{1F9FF}",
-  "\u{1F530}",
-  "\u269B\uFE0F",
-  "\u{1F3FA}",
-  "\u{1F9EB}",
-  "\u{1F52C}",
-  "\u2695\uFE0F",
-  "\u{1F5DD}\uFE0F",
-  "\u2696\uFE0F",
-  "\u{1F52E}",
-  "\u{1FAAC}",
-  "\u{1F9EC}",
-  "\u2699\uFE0F",
-  "\u{1F529}",
-  "\u{1FA9B}",
-  "\u26CF\uFE0F",
-  "\u{1FA83}",
-  "\u{1F3F9}",
-  "\u{1F6E1}\uFE0F",
-  "\u2694\uFE0F",
-  "\u{1F5E1}\uFE0F",
-  "\u{1FA93}",
-  "\u{1F5C3}\uFE0F",
-  "\u{1F4DC}",
-  "\u{1F4EF}",
-  "\u{1F3B4}",
-  "\u{1F004}",
-  "\u{1F3B2}"
-];
-function generateMarkers() {
-  const pick = (count) => {
-    const result = [];
-    const pool = [...RARE_EMOJI];
-    for (let i = 0; i < count && pool.length > 0; i++) {
-      const idx = Math.floor(Math.random() * pool.length);
-      result.push(pool.splice(idx, 1)[0]);
-    }
-    return result.join("");
-  };
-  return {
-    startPrefix: pick(5),
-    endPrefix: pick(5)
-  };
-}
 function createNumericParser({
   label,
   integer = false,
@@ -6195,6 +6307,10 @@ function configToAgentOptions(config) {
   if (config.builtins !== void 0) result.builtins = config.builtins;
   if (config["builtin-interaction"] !== void 0)
     result.builtinInteraction = config["builtin-interaction"];
+  if (config["gadget-start-prefix"] !== void 0)
+    result.gadgetStartPrefix = config["gadget-start-prefix"];
+  if (config["gadget-end-prefix"] !== void 0)
+    result.gadgetEndPrefix = config["gadget-end-prefix"];
   return result;
 }
 
@@ -6409,9 +6525,27 @@ Command rejected by user with message: "${response}"`
     builder.withGadgets(...gadgets);
   }
   builder.withParameterFormat(options.parameterFormat);
-  const markers = generateMarkers();
-  builder.withGadgetStartPrefix(markers.startPrefix);
-  builder.withGadgetEndPrefix(markers.endPrefix);
+  if (options.gadgetStartPrefix) {
+    builder.withGadgetStartPrefix(options.gadgetStartPrefix);
+  }
+  if (options.gadgetEndPrefix) {
+    builder.withGadgetEndPrefix(options.gadgetEndPrefix);
+  }
+  builder.withSyntheticGadgetCall(
+    "TellUser",
+    {
+      message: "\u{1F44B} Hello! I'm ready to help.\n\nHere's what I can do:\n- Analyze your codebase\n- Execute commands\n- Answer questions\n\nWhat would you like me to work on?",
+      done: false,
+      type: "info"
+    },
+    "\u2139\uFE0F  \u{1F44B} Hello! I'm ready to help.\n\nHere's what I can do:\n- Analyze your codebase\n- Execute commands\n- Answer questions\n\nWhat would you like me to work on?"
+  );
+  builder.withTextOnlyHandler("acknowledge");
+  builder.withTextWithGadgetsHandler({
+    gadgetName: "TellUser",
+    parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
+    resultMapping: (text) => `\u2139\uFE0F  ${text}`
+  });
   const agent = builder.ask(prompt);
   for await (const event of agent.run()) {
     if (event.type === "text") {
@@ -6533,7 +6667,9 @@ var AGENT_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "gadget",
   "parameter-format",
   "builtins",
-  "builtin-interaction"
+  "builtin-interaction",
+  "gadget-start-prefix",
+  "gadget-end-prefix"
 ]);
 var CUSTOM_CONFIG_KEYS = /* @__PURE__ */ new Set([
   ...COMPLETE_CONFIG_KEYS,
@@ -6695,6 +6831,20 @@ function validateAgentConfig(raw, section) {
       section
     );
   }
+  if ("gadget-start-prefix" in rawObj) {
+    result["gadget-start-prefix"] = validateString(
+      rawObj["gadget-start-prefix"],
+      "gadget-start-prefix",
+      section
+    );
+  }
+  if ("gadget-end-prefix" in rawObj) {
+    result["gadget-end-prefix"] = validateString(
+      rawObj["gadget-end-prefix"],
+      "gadget-end-prefix",
+      section
+    );
+  }
   return result;
 }
 function validateCustomConfig(raw, section) {
@@ -6750,6 +6900,20 @@ function validateCustomConfig(raw, section) {
       section
     );
   }
+  if ("gadget-start-prefix" in rawObj) {
+    result["gadget-start-prefix"] = validateString(
+      rawObj["gadget-start-prefix"],
+      "gadget-start-prefix",
+      section
+    );
+  }
+  if ("gadget-end-prefix" in rawObj) {
+    result["gadget-end-prefix"] = validateString(
+      rawObj["gadget-end-prefix"],
+      "gadget-end-prefix",
+      section
+    );
+  }
   if ("max-tokens" in rawObj) {
     result["max-tokens"] = validateNumber(rawObj["max-tokens"], "max-tokens", section, {
       integer: true,