llmist 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -1269,12 +1269,22 @@ declare class HumanInputException extends Error {
     constructor(question: string);
 }
 
+interface ErrorFormatterOptions {
+    /** Custom argument prefix for block format examples. Default: "!!!ARG:" */
+    argPrefix?: string;
+    /** Custom start prefix for block format examples. Default: "!!!GADGET_START:" */
+    startPrefix?: string;
+    /** Custom end prefix for block format examples. Default: "!!!GADGET_END" */
+    endPrefix?: string;
+}
+
 declare class GadgetExecutor {
     private readonly registry;
     private readonly onHumanInputRequired?;
     private readonly defaultGadgetTimeoutMs?;
     private readonly logger;
-    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined);
+    private readonly errorFormatter;
+    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
      */
@@ -1303,10 +1313,11 @@ declare class StreamParser {
      */
     private parseGadgetName;
     /**
-     * Truncate verbose parse errors to avoid context overflow.
-     * Keeps first meaningful line and limits total length.
+     * Extract the error message from a parse error.
+     * Preserves full message since the error formatter adds contextual help
+     * that benefits from precise, detailed error information.
      */
-    private truncateParseError;
+    private extractParseError;
     /**
      * Parse parameter string using block format
      */

package/dist/index.d.ts

@@ -1269,12 +1269,22 @@ declare class HumanInputException extends Error {
     constructor(question: string);
 }
 
+interface ErrorFormatterOptions {
+    /** Custom argument prefix for block format examples. Default: "!!!ARG:" */
+    argPrefix?: string;
+    /** Custom start prefix for block format examples. Default: "!!!GADGET_START:" */
+    startPrefix?: string;
+    /** Custom end prefix for block format examples. Default: "!!!GADGET_END" */
+    endPrefix?: string;
+}
+
 declare class GadgetExecutor {
     private readonly registry;
     private readonly onHumanInputRequired?;
     private readonly defaultGadgetTimeoutMs?;
     private readonly logger;
-    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined);
+    private readonly errorFormatter;
+    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
      */
@@ -1303,10 +1313,11 @@ declare class StreamParser {
      */
     private parseGadgetName;
     /**
-     * Truncate verbose parse errors to avoid context overflow.
-     * Keeps first meaningful line and limits total length.
+     * Extract the error message from a parse error.
+     * Preserves full message since the error formatter adds contextual help
+     * that benefits from precise, detailed error information.
      */
-    private truncateParseError;
+    private extractParseError;
     /**
      * Parse parameter string using block format
      */

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   mockLLM,
   validateAndApplyDefaults,
   validateGadgetParams
-} from "./chunk-53MM55JS.js";
+} from "./chunk-OIPLYP7M.js";
 import {
   AgentBuilder,
   AnthropicMessagesProvider,
@@ -74,7 +74,7 @@ import {
   resolveRulesTemplate,
   runWithHandlers,
   stream
-} from "./chunk-T24KLXY4.js";
+} from "./chunk-VXPZQZF5.js";
 
 // src/index.ts
 init_builder();

package/dist/testing/index.cjs

@@ -1446,6 +1446,89 @@ var init_hook_validators = __esm({
   }
 });
 
+// src/gadgets/error-formatter.ts
+var GadgetErrorFormatter;
+var init_error_formatter = __esm({
+  "src/gadgets/error-formatter.ts"() {
+    "use strict";
+    init_constants();
+    GadgetErrorFormatter = class {
+      argPrefix;
+      startPrefix;
+      endPrefix;
+      constructor(options = {}) {
+        this.argPrefix = options.argPrefix ?? GADGET_ARG_PREFIX;
+        this.startPrefix = options.startPrefix ?? GADGET_START_PREFIX;
+        this.endPrefix = options.endPrefix ?? GADGET_END_PREFIX;
+      }
+      /**
+       * Format a Zod validation error with full gadget instructions.
+       *
+       * @param gadgetName - Name of the gadget that was called
+       * @param zodError - The Zod validation error
+       * @param gadget - The gadget instance (for generating instructions)
+       * @returns Formatted error message with usage instructions
+       */
+      formatValidationError(gadgetName, zodError, gadget) {
+        const parts = [];
+        parts.push(`Error: Invalid parameters for '${gadgetName}':`);
+        for (const issue of zodError.issues) {
+          const path = issue.path.join(".") || "root";
+          parts.push(`  - ${path}: ${issue.message}`);
+        }
+        parts.push("");
+        parts.push("Gadget Usage:");
+        parts.push(gadget.getInstruction(this.argPrefix));
+        return parts.join("\n");
+      }
+      /**
+       * Format a parse error with block format reference.
+       *
+       * @param gadgetName - Name of the gadget that was called
+       * @param parseError - The parse error message
+       * @param gadget - The gadget instance if found (for generating instructions)
+       * @returns Formatted error message with format reference
+       */
+      formatParseError(gadgetName, parseError, gadget) {
+        const parts = [];
+        parts.push(`Error: Failed to parse parameters for '${gadgetName}':`);
+        parts.push(`  ${parseError}`);
+        if (gadget) {
+          parts.push("");
+          parts.push("Gadget Usage:");
+          parts.push(gadget.getInstruction(this.argPrefix));
+        }
+        parts.push("");
+        parts.push("Block Format Reference:");
+        parts.push(`  ${this.startPrefix}${gadgetName}`);
+        parts.push(`  ${this.argPrefix}parameterName`);
+        parts.push("  parameter value here");
+        parts.push(`  ${this.endPrefix}`);
+        return parts.join("\n");
+      }
+      /**
+       * Format a registry error (gadget not found) with available gadgets list.
+       *
+       * @param gadgetName - Name of the gadget that was not found
+       * @param availableGadgets - List of available gadget names
+       * @returns Formatted error message with available gadgets
+       */
+      formatRegistryError(gadgetName, availableGadgets) {
+        const parts = [];
+        parts.push(`Error: Gadget '${gadgetName}' not found.`);
+        if (availableGadgets.length > 0) {
+          parts.push("");
+          parts.push(`Available gadgets: ${availableGadgets.join(", ")}`);
+        } else {
+          parts.push("");
+          parts.push("No gadgets are currently registered.");
+        }
+        return parts.join("\n");
+      }
+    };
+  }
+});
+
 // src/gadgets/exceptions.ts
 var BreakLoopException, HumanInputException, TimeoutException;
 var init_exceptions = __esm({
@@ -1484,15 +1567,18 @@ var init_executor = __esm({
   "src/gadgets/executor.ts"() {
     "use strict";
     init_logger();
+    init_error_formatter();
     init_exceptions();
     GadgetExecutor = class {
-      constructor(registry, onHumanInputRequired, logger, defaultGadgetTimeoutMs) {
+      constructor(registry, onHumanInputRequired, logger, defaultGadgetTimeoutMs, errorFormatterOptions) {
         this.registry = registry;
         this.onHumanInputRequired = onHumanInputRequired;
         this.defaultGadgetTimeoutMs = defaultGadgetTimeoutMs;
         this.logger = logger ?? createLogger({ name: "llmist:executor" });
+        this.errorFormatter = new GadgetErrorFormatter(errorFormatterOptions);
       }
       logger;
+      errorFormatter;
       /**
        * Creates a promise that rejects with a TimeoutException after the specified timeout.
        */
@@ -1517,11 +1603,12 @@ var init_executor = __esm({
           const gadget = this.registry.get(call.gadgetName);
           if (!gadget) {
             this.logger.error("Gadget not found", { gadgetName: call.gadgetName });
+            const availableGadgets = this.registry.getNames();
             return {
               gadgetName: call.gadgetName,
               invocationId: call.invocationId,
               parameters: call.parameters ?? {},
-              error: `Gadget '${call.gadgetName}' not found in registry`,
+              error: this.errorFormatter.formatRegistryError(call.gadgetName, availableGadgets),
               executionTimeMs: Date.now() - startTime
             };
           }
@@ -1531,25 +1618,26 @@ var init_executor = __esm({
               parseError: call.parseError,
               rawParameters: call.parametersRaw
             });
+            const parseErrorMessage = call.parseError ?? "Failed to parse parameters";
             return {
               gadgetName: call.gadgetName,
               invocationId: call.invocationId,
               parameters: {},
-              error: call.parseError ?? "Failed to parse parameters",
+              error: this.errorFormatter.formatParseError(call.gadgetName, parseErrorMessage, gadget),
               executionTimeMs: Date.now() - startTime
             };
           }
           if (gadget.parameterSchema) {
             const validationResult = gadget.parameterSchema.safeParse(rawParameters);
             if (!validationResult.success) {
-              const formattedIssues = validationResult.error.issues.map((issue) => {
-                const path = issue.path.join(".") || "root";
-                return `${path}: ${issue.message}`;
-              }).join("; ");
-              const validationError = `Invalid parameters: ${formattedIssues}`;
+              const validationError = this.errorFormatter.formatValidationError(
+                call.gadgetName,
+                validationResult.error,
+                gadget
+              );
               this.logger.error("Gadget parameter validation failed", {
                 gadgetName: call.gadgetName,
-                error: validationError
+                issueCount: validationResult.error.issues.length
               });
               return {
                 gadgetName: call.gadgetName,
@@ -1838,17 +1926,12 @@ 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.
+       * Extract the error message from a parse error.
+       * Preserves full message since the error formatter adds contextual help
+       * that benefits from precise, detailed error information.
        */
-      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)`;
+      extractParseError(error) {
+        return error instanceof Error ? error.message : String(error);
       }
       /**
        * Parse parameter string using block format
@@ -1858,7 +1941,7 @@ var init_parser = __esm({
         try {
           return { parameters: parseBlockParams(cleaned, { argPrefix: this.argPrefix }) };
         } catch (error) {
-          return { parseError: this.truncateParseError(error, "block") };
+          return { parseError: this.extractParseError(error) };
         }
       }
       // Feed a chunk of text and get parsed events