llmist 1.0.0 → 1.2.0

package/dist/cli.cjs

@@ -1447,6 +1447,447 @@ var init_hook_validators = __esm({
   }
 });
 
+// src/gadgets/schema-introspector.ts
+function getDef(schema) {
+  return schema._def;
+}
+function getTypeName(schema) {
+  const def = getDef(schema);
+  return def?.type ?? def?.typeName;
+}
+function getShape(schema) {
+  const def = getDef(schema);
+  if (typeof def?.shape === "function") {
+    return def.shape();
+  }
+  return def?.shape;
+}
+var SchemaIntrospector;
+var init_schema_introspector = __esm({
+  "src/gadgets/schema-introspector.ts"() {
+    "use strict";
+    SchemaIntrospector = class {
+      schema;
+      cache = /* @__PURE__ */ new Map();
+      constructor(schema) {
+        this.schema = schema;
+      }
+      /**
+       * Get the expected type at a JSON pointer path.
+       *
+       * @param pointer - JSON pointer path without leading / (e.g., "config/timeout", "items/0")
+       * @returns Type hint for coercion decision
+       */
+      getTypeAtPath(pointer) {
+        const cached = this.cache.get(pointer);
+        if (cached !== void 0) {
+          return cached;
+        }
+        const result = this.resolveTypeAtPath(pointer);
+        this.cache.set(pointer, result);
+        return result;
+      }
+      /**
+       * Internal method to resolve type at path without caching.
+       */
+      resolveTypeAtPath(pointer) {
+        if (!pointer) {
+          return this.getBaseType(this.schema);
+        }
+        const segments = pointer.split("/");
+        let current = this.schema;
+        for (const segment of segments) {
+          current = this.unwrapSchema(current);
+          const typeName = getTypeName(current);
+          if (typeName === "object" || typeName === "ZodObject") {
+            const shape = getShape(current);
+            if (!shape || !(segment in shape)) {
+              return "unknown";
+            }
+            current = shape[segment];
+          } else if (typeName === "array" || typeName === "ZodArray") {
+            if (!/^\d+$/.test(segment)) {
+              return "unknown";
+            }
+            const def = getDef(current);
+            const elementType = def?.element ?? def?.type;
+            if (!elementType) {
+              return "unknown";
+            }
+            current = elementType;
+          } else if (typeName === "tuple" || typeName === "ZodTuple") {
+            if (!/^\d+$/.test(segment)) {
+              return "unknown";
+            }
+            const index = parseInt(segment, 10);
+            const def = getDef(current);
+            const items = def?.items;
+            if (!items || index >= items.length) {
+              return "unknown";
+            }
+            current = items[index];
+          } else if (typeName === "record" || typeName === "ZodRecord") {
+            const def = getDef(current);
+            const valueType = def?.valueType;
+            if (!valueType) {
+              return "unknown";
+            }
+            current = valueType;
+          } else {
+            return "unknown";
+          }
+        }
+        return this.getBaseType(current);
+      }
+      /**
+       * Unwrap schema modifiers (optional, default, nullable, branded, etc.)
+       * to get to the underlying type.
+       */
+      unwrapSchema(schema) {
+        let current = schema;
+        let iterations = 0;
+        const maxIterations = 20;
+        while (iterations < maxIterations) {
+          const typeName = getTypeName(current);
+          const wrapperTypes = [
+            "optional",
+            "nullable",
+            "default",
+            "catch",
+            "branded",
+            "readonly",
+            "pipeline",
+            "ZodOptional",
+            "ZodNullable",
+            "ZodDefault",
+            "ZodCatch",
+            "ZodBranded",
+            "ZodReadonly",
+            "ZodPipeline"
+          ];
+          if (typeName && wrapperTypes.includes(typeName)) {
+            const def = getDef(current);
+            const inner = def?.innerType ?? def?.in ?? def?.type;
+            if (!inner || inner === current) break;
+            current = inner;
+            iterations++;
+            continue;
+          }
+          break;
+        }
+        return current;
+      }
+      /**
+       * Get the primitive type hint from an unwrapped schema.
+       */
+      getBaseType(schema) {
+        const unwrapped = this.unwrapSchema(schema);
+        const typeName = getTypeName(unwrapped);
+        switch (typeName) {
+          // Primitive types
+          case "string":
+          case "ZodString":
+            return "string";
+          case "number":
+          case "ZodNumber":
+          case "bigint":
+          case "ZodBigInt":
+            return "number";
+          case "boolean":
+          case "ZodBoolean":
+            return "boolean";
+          // Literal types - check the literal value type
+          case "literal":
+          case "ZodLiteral": {
+            const def = getDef(unwrapped);
+            const values = def?.values;
+            const value = values?.[0] ?? def?.value;
+            if (typeof value === "string") return "string";
+            if (typeof value === "number" || typeof value === "bigint")
+              return "number";
+            if (typeof value === "boolean") return "boolean";
+            return "unknown";
+          }
+          // Enum - always string keys
+          case "enum":
+          case "ZodEnum":
+          case "nativeEnum":
+          case "ZodNativeEnum":
+            return "string";
+          // Union - return 'unknown' to let auto-coercion decide
+          // Since multiple types are valid, we can't definitively say what the LLM intended
+          // Auto-coercion will handle common cases (numbers, booleans) appropriately
+          case "union":
+          case "ZodUnion":
+            return "unknown";
+          // Discriminated union - complex, return unknown
+          case "discriminatedUnion":
+          case "ZodDiscriminatedUnion":
+            return "unknown";
+          // Intersection - check both sides
+          case "intersection":
+          case "ZodIntersection": {
+            const def = getDef(unwrapped);
+            const left = def?.left;
+            const right = def?.right;
+            if (!left || !right) return "unknown";
+            const leftType = this.getBaseType(left);
+            const rightType = this.getBaseType(right);
+            if (leftType === rightType) return leftType;
+            if (leftType === "string" || rightType === "string") return "string";
+            return "unknown";
+          }
+          // Effects/transforms - return unknown to let Zod handle it
+          case "effects":
+          case "ZodEffects":
+            return "unknown";
+          // Lazy - can't resolve without evaluating
+          case "lazy":
+          case "ZodLazy":
+            return "unknown";
+          // Complex types - return unknown
+          case "object":
+          case "ZodObject":
+          case "array":
+          case "ZodArray":
+          case "tuple":
+          case "ZodTuple":
+          case "record":
+          case "ZodRecord":
+          case "map":
+          case "ZodMap":
+          case "set":
+          case "ZodSet":
+          case "function":
+          case "ZodFunction":
+          case "promise":
+          case "ZodPromise":
+          case "date":
+          case "ZodDate":
+            return "unknown";
+          // Unknown/any/never/void/undefined/null
+          case "unknown":
+          case "ZodUnknown":
+          case "any":
+          case "ZodAny":
+          case "never":
+          case "ZodNever":
+          case "void":
+          case "ZodVoid":
+          case "undefined":
+          case "ZodUndefined":
+          case "null":
+          case "ZodNull":
+            return "unknown";
+          default:
+            return "unknown";
+        }
+      }
+    };
+  }
+});
+
+// src/gadgets/block-params.ts
+function parseBlockParams(content, options) {
+  const argPrefix = options?.argPrefix ?? GADGET_ARG_PREFIX;
+  const result = {};
+  const seenPointers = /* @__PURE__ */ new Set();
+  const introspector = options?.schema ? new SchemaIntrospector(options.schema) : void 0;
+  const parts = content.split(argPrefix);
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+    const newlineIndex = part.indexOf("\n");
+    if (newlineIndex === -1) {
+      const pointer2 = part.trim();
+      if (pointer2) {
+        if (seenPointers.has(pointer2)) {
+          throw new Error(`Duplicate pointer: ${pointer2}`);
+        }
+        seenPointers.add(pointer2);
+        setByPointer(result, pointer2, "", introspector);
+      }
+      continue;
+    }
+    const pointer = part.substring(0, newlineIndex).trim();
+    let value = part.substring(newlineIndex + 1);
+    if (value.endsWith("\n")) {
+      value = value.slice(0, -1);
+    }
+    if (!pointer) {
+      continue;
+    }
+    if (seenPointers.has(pointer)) {
+      throw new Error(`Duplicate pointer: ${pointer}`);
+    }
+    seenPointers.add(pointer);
+    setByPointer(result, pointer, value, introspector);
+  }
+  return result;
+}
+function coerceValue(value, expectedType) {
+  if (value.includes("\n")) {
+    return value;
+  }
+  const trimmed = value.trim();
+  if (expectedType === "string") {
+    return value;
+  }
+  if (expectedType === "boolean") {
+    if (trimmed === "true") return true;
+    if (trimmed === "false") return false;
+    return value;
+  }
+  if (expectedType === "number") {
+    const num = Number(trimmed);
+    if (!isNaN(num) && isFinite(num) && trimmed !== "") {
+      return num;
+    }
+    return value;
+  }
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed !== "" && /^-?\d+(\.\d+)?$/.test(trimmed)) {
+    const num = Number(trimmed);
+    if (!isNaN(num) && isFinite(num)) {
+      return num;
+    }
+  }
+  return value;
+}
+function setByPointer(obj, pointer, value, introspector) {
+  const segments = pointer.split("/");
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    const nextSegment = segments[i + 1];
+    const nextIsArrayIndex = /^\d+$/.test(nextSegment);
+    if (Array.isArray(current)) {
+      const index = parseInt(segment, 10);
+      if (isNaN(index) || index < 0) {
+        throw new Error(`Invalid array index: ${segment}`);
+      }
+      if (index > current.length) {
+        throw new Error(`Array index gap: expected ${current.length}, got ${index}`);
+      }
+      if (current[index] === void 0) {
+        current[index] = nextIsArrayIndex ? [] : {};
+      }
+      current = current[index];
+    } else {
+      const rec = current;
+      if (rec[segment] === void 0) {
+        rec[segment] = nextIsArrayIndex ? [] : {};
+      }
+      current = rec[segment];
+    }
+  }
+  const lastSegment = segments[segments.length - 1];
+  const expectedType = introspector?.getTypeAtPath(pointer);
+  const coercedValue = coerceValue(value, expectedType);
+  if (Array.isArray(current)) {
+    const index = parseInt(lastSegment, 10);
+    if (isNaN(index) || index < 0) {
+      throw new Error(`Invalid array index: ${lastSegment}`);
+    }
+    if (index > current.length) {
+      throw new Error(`Array index gap: expected ${current.length}, got ${index}`);
+    }
+    current[index] = coercedValue;
+  } else {
+    current[lastSegment] = coercedValue;
+  }
+}
+var init_block_params = __esm({
+  "src/gadgets/block-params.ts"() {
+    "use strict";
+    init_constants();
+    init_schema_introspector();
+  }
+});
+
+// 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 path2 = issue.path.join(".") || "root";
+          parts.push(`  - ${path2}: ${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({
@@ -1479,21 +1920,206 @@ var init_exceptions = __esm({
   }
 });
 
+// src/gadgets/parser.ts
+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 globalInvocationCounter, StreamParser;
+var init_parser = __esm({
+  "src/gadgets/parser.ts"() {
+    "use strict";
+    init_constants();
+    init_block_params();
+    globalInvocationCounter = 0;
+    StreamParser = class {
+      buffer = "";
+      lastReportedTextLength = 0;
+      startPrefix;
+      endPrefix;
+      argPrefix;
+      constructor(options = {}) {
+        this.startPrefix = options.startPrefix ?? GADGET_START_PREFIX;
+        this.endPrefix = options.endPrefix ?? GADGET_END_PREFIX;
+        this.argPrefix = options.argPrefix ?? GADGET_ARG_PREFIX;
+      }
+      takeTextUntil(index) {
+        if (index <= this.lastReportedTextLength) {
+          return void 0;
+        }
+        const segment = this.buffer.slice(this.lastReportedTextLength, index);
+        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}` };
+      }
+      /**
+       * 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.
+       */
+      extractParseError(error) {
+        return error instanceof Error ? error.message : String(error);
+      }
+      /**
+       * Parse parameter string using block format
+       */
+      parseParameters(raw) {
+        const cleaned = stripMarkdownFences(raw);
+        try {
+          return { parameters: parseBlockParams(cleaned, { argPrefix: this.argPrefix }) };
+        } catch (error) {
+          return { parseError: this.extractParseError(error) };
+        }
+      }
+      // Feed a chunk of text and get parsed events
+      *feed(chunk) {
+        this.buffer += chunk;
+        let startIndex = 0;
+        while (true) {
+          const partStartIndex = this.buffer.indexOf(this.startPrefix, startIndex);
+          if (partStartIndex === -1) break;
+          const textBefore = this.takeTextUntil(partStartIndex);
+          if (textBefore !== void 0) {
+            yield { type: "text", content: textBefore };
+          }
+          const metadataStartIndex = partStartIndex + this.startPrefix.length;
+          const metadataEndIndex = this.buffer.indexOf("\n", metadataStartIndex);
+          if (metadataEndIndex === -1) break;
+          const gadgetName = this.buffer.substring(metadataStartIndex, metadataEndIndex).trim();
+          const { actualName: actualGadgetName, invocationId } = this.parseGadgetName(gadgetName);
+          const contentStartIndex = metadataEndIndex + 1;
+          let partEndIndex;
+          let endMarkerLength = 0;
+          if (gadgetName.includes(":")) {
+            const oldEndMarker = `${this.endPrefix + actualGadgetName}:${invocationId}`;
+            partEndIndex = this.buffer.indexOf(oldEndMarker, contentStartIndex);
+            if (partEndIndex === -1) break;
+            endMarkerLength = oldEndMarker.length;
+          } else {
+            const nextStartPos = this.buffer.indexOf(this.startPrefix, contentStartIndex);
+            let validEndPos = -1;
+            let searchPos = contentStartIndex;
+            while (true) {
+              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) {
+                validEndPos = endPos;
+                break;
+              } else {
+                searchPos = endPos + this.endPrefix.length;
+              }
+            }
+            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);
+          yield {
+            type: "gadget_call",
+            call: {
+              gadgetName: actualGadgetName,
+              invocationId,
+              parametersRaw,
+              parameters,
+              parseError
+            }
+          };
+          startIndex = partEndIndex + endMarkerLength;
+          this.lastReportedTextLength = startIndex;
+        }
+        if (startIndex > 0) {
+          this.buffer = this.buffer.substring(startIndex);
+          this.lastReportedTextLength = 0;
+        }
+      }
+      // 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,
+                parametersRaw,
+                parameters,
+                parseError
+              }
+            };
+            return;
+          }
+        }
+        const remainingText = this.takeTextUntil(this.buffer.length);
+        if (remainingText !== void 0) {
+          yield { type: "text", content: remainingText };
+        }
+      }
+      // Reset parser state (note: global invocation counter is NOT reset to ensure unique IDs)
+      reset() {
+        this.buffer = "";
+        this.lastReportedTextLength = 0;
+      }
+    };
+  }
+});
+
 // src/gadgets/executor.ts
 var GadgetExecutor;
 var init_executor = __esm({
   "src/gadgets/executor.ts"() {
     "use strict";
+    init_constants();
     init_logger();
+    init_block_params();
+    init_error_formatter();
     init_exceptions();
+    init_parser();
     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);
+        this.argPrefix = errorFormatterOptions?.argPrefix ?? GADGET_ARG_PREFIX;
       }
       logger;
+      errorFormatter;
+      argPrefix;
       /**
        * Creates a promise that rejects with a TimeoutException after the specified timeout.
        */
@@ -1518,11 +2144,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
             };
           }
@@ -1532,35 +2159,69 @@ 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
             };
           }
+          let schemaAwareParameters = rawParameters;
+          const hasBlockFormat = call.parametersRaw?.includes(this.argPrefix);
+          if (gadget.parameterSchema && hasBlockFormat) {
+            try {
+              const cleanedRaw = stripMarkdownFences(call.parametersRaw);
+              const initialParse = parseBlockParams(cleanedRaw, { argPrefix: this.argPrefix });
+              const parametersWereModified = !this.deepEquals(rawParameters, initialParse);
+              if (parametersWereModified) {
+                this.logger.debug("Parameters modified by interceptor, skipping re-parse", {
+                  gadgetName: call.gadgetName
+                });
+                schemaAwareParameters = rawParameters;
+              } else {
+                schemaAwareParameters = parseBlockParams(cleanedRaw, {
+                  argPrefix: this.argPrefix,
+                  schema: gadget.parameterSchema
+                });
+                this.logger.debug("Re-parsed parameters with schema", {
+                  gadgetName: call.gadgetName,
+                  original: rawParameters,
+                  schemaAware: schemaAwareParameters
+                });
+              }
+            } catch (error) {
+              this.logger.warn("Schema-aware re-parsing failed, using original parameters", {
+                gadgetName: call.gadgetName,
+                error: error instanceof Error ? error.message : String(error)
+              });
+              schemaAwareParameters = rawParameters;
+            }
+          }
           if (gadget.parameterSchema) {
-            const validationResult = gadget.parameterSchema.safeParse(rawParameters);
+            const validationResult = gadget.parameterSchema.safeParse(schemaAwareParameters);
             if (!validationResult.success) {
-              const formattedIssues = validationResult.error.issues.map((issue) => {
-                const path2 = issue.path.join(".") || "root";
-                return `${path2}: ${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,
                 invocationId: call.invocationId,
-                parameters: rawParameters,
+                parameters: schemaAwareParameters,
                 error: validationError,
                 executionTimeMs: Date.now() - startTime
               };
             }
             validatedParameters = validationResult.data;
+          } else {
+            validatedParameters = schemaAwareParameters;
           }
           const timeoutMs = gadget.timeoutMs ?? this.defaultGadgetTimeoutMs;
           let result;
@@ -1653,322 +2314,61 @@ var init_executor = __esm({
                   gadgetName: call.gadgetName,
                   invocationId: call.invocationId,
                   parameters: validatedParameters,
-                  error: inputError instanceof Error ? inputError.message : String(inputError),
-                  executionTimeMs: Date.now() - startTime
-                };
-              }
-            }
-            this.logger.warn("Human input required but no callback provided", {
-              gadgetName: call.gadgetName
-            });
-            return {
-              gadgetName: call.gadgetName,
-              invocationId: call.invocationId,
-              parameters: validatedParameters,
-              error: "Human input required but not available (stdin is not interactive)",
-              executionTimeMs: Date.now() - startTime
-            };
-          }
-          const executionTimeMs = Date.now() - startTime;
-          this.logger.error("Gadget execution failed", {
-            gadgetName: call.gadgetName,
-            error: error instanceof Error ? error.message : String(error),
-            executionTimeMs
-          });
-          return {
-            gadgetName: call.gadgetName,
-            invocationId: call.invocationId,
-            parameters: validatedParameters,
-            error: error instanceof Error ? error.message : String(error),
-            executionTimeMs
-          };
-        }
-      }
-      // Execute multiple gadget calls in parallel
-      async executeAll(calls) {
-        return Promise.all(calls.map((call) => this.execute(call)));
-      }
-    };
-  }
-});
-
-// src/gadgets/block-params.ts
-function parseBlockParams(content, options) {
-  const argPrefix = options?.argPrefix ?? GADGET_ARG_PREFIX;
-  const result = {};
-  const seenPointers = /* @__PURE__ */ new Set();
-  const parts = content.split(argPrefix);
-  for (let i = 1; i < parts.length; i++) {
-    const part = parts[i];
-    const newlineIndex = part.indexOf("\n");
-    if (newlineIndex === -1) {
-      const pointer2 = part.trim();
-      if (pointer2) {
-        if (seenPointers.has(pointer2)) {
-          throw new Error(`Duplicate pointer: ${pointer2}`);
-        }
-        seenPointers.add(pointer2);
-        setByPointer(result, pointer2, "");
-      }
-      continue;
-    }
-    const pointer = part.substring(0, newlineIndex).trim();
-    let value = part.substring(newlineIndex + 1);
-    if (value.endsWith("\n")) {
-      value = value.slice(0, -1);
-    }
-    if (!pointer) {
-      continue;
-    }
-    if (seenPointers.has(pointer)) {
-      throw new Error(`Duplicate pointer: ${pointer}`);
-    }
-    seenPointers.add(pointer);
-    setByPointer(result, pointer, value);
-  }
-  return result;
-}
-function coerceValue(value) {
-  if (value.includes("\n")) {
-    return value;
-  }
-  const trimmed = value.trim();
-  if (trimmed === "true") return true;
-  if (trimmed === "false") return false;
-  if (trimmed !== "" && /^-?\d+(\.\d+)?$/.test(trimmed)) {
-    const num = Number(trimmed);
-    if (!isNaN(num) && isFinite(num)) {
-      return num;
-    }
-  }
-  return value;
-}
-function setByPointer(obj, pointer, value) {
-  const segments = pointer.split("/");
-  let current = obj;
-  for (let i = 0; i < segments.length - 1; i++) {
-    const segment = segments[i];
-    const nextSegment = segments[i + 1];
-    const nextIsArrayIndex = /^\d+$/.test(nextSegment);
-    if (Array.isArray(current)) {
-      const index = parseInt(segment, 10);
-      if (isNaN(index) || index < 0) {
-        throw new Error(`Invalid array index: ${segment}`);
-      }
-      if (index > current.length) {
-        throw new Error(`Array index gap: expected ${current.length}, got ${index}`);
-      }
-      if (current[index] === void 0) {
-        current[index] = nextIsArrayIndex ? [] : {};
-      }
-      current = current[index];
-    } else {
-      const rec = current;
-      if (rec[segment] === void 0) {
-        rec[segment] = nextIsArrayIndex ? [] : {};
-      }
-      current = rec[segment];
-    }
-  }
-  const lastSegment = segments[segments.length - 1];
-  const coercedValue = coerceValue(value);
-  if (Array.isArray(current)) {
-    const index = parseInt(lastSegment, 10);
-    if (isNaN(index) || index < 0) {
-      throw new Error(`Invalid array index: ${lastSegment}`);
-    }
-    if (index > current.length) {
-      throw new Error(`Array index gap: expected ${current.length}, got ${index}`);
-    }
-    current[index] = coercedValue;
-  } else {
-    current[lastSegment] = coercedValue;
-  }
-}
-var init_block_params = __esm({
-  "src/gadgets/block-params.ts"() {
-    "use strict";
-    init_constants();
-  }
-});
-
-// src/gadgets/parser.ts
-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 globalInvocationCounter, StreamParser;
-var init_parser = __esm({
-  "src/gadgets/parser.ts"() {
-    "use strict";
-    init_constants();
-    init_block_params();
-    globalInvocationCounter = 0;
-    StreamParser = class {
-      buffer = "";
-      lastReportedTextLength = 0;
-      startPrefix;
-      endPrefix;
-      argPrefix;
-      constructor(options = {}) {
-        this.startPrefix = options.startPrefix ?? GADGET_START_PREFIX;
-        this.endPrefix = options.endPrefix ?? GADGET_END_PREFIX;
-        this.argPrefix = options.argPrefix ?? GADGET_ARG_PREFIX;
-      }
-      takeTextUntil(index) {
-        if (index <= this.lastReportedTextLength) {
-          return void 0;
-        }
-        const segment = this.buffer.slice(this.lastReportedTextLength, index);
-        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}` };
-      }
-      /**
-       * 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 using block format
-       */
-      parseParameters(raw) {
-        const cleaned = stripMarkdownFences(raw);
-        try {
-          return { parameters: parseBlockParams(cleaned, { argPrefix: this.argPrefix }) };
-        } catch (error) {
-          return { parseError: this.truncateParseError(error, "block") };
-        }
-      }
-      // Feed a chunk of text and get parsed events
-      *feed(chunk) {
-        this.buffer += chunk;
-        let startIndex = 0;
-        while (true) {
-          const partStartIndex = this.buffer.indexOf(this.startPrefix, startIndex);
-          if (partStartIndex === -1) break;
-          const textBefore = this.takeTextUntil(partStartIndex);
-          if (textBefore !== void 0) {
-            yield { type: "text", content: textBefore };
-          }
-          const metadataStartIndex = partStartIndex + this.startPrefix.length;
-          const metadataEndIndex = this.buffer.indexOf("\n", metadataStartIndex);
-          if (metadataEndIndex === -1) break;
-          const gadgetName = this.buffer.substring(metadataStartIndex, metadataEndIndex).trim();
-          const { actualName: actualGadgetName, invocationId } = this.parseGadgetName(gadgetName);
-          const contentStartIndex = metadataEndIndex + 1;
-          let partEndIndex;
-          let endMarkerLength = 0;
-          if (gadgetName.includes(":")) {
-            const oldEndMarker = `${this.endPrefix + actualGadgetName}:${invocationId}`;
-            partEndIndex = this.buffer.indexOf(oldEndMarker, contentStartIndex);
-            if (partEndIndex === -1) break;
-            endMarkerLength = oldEndMarker.length;
-          } else {
-            const nextStartPos = this.buffer.indexOf(this.startPrefix, contentStartIndex);
-            let validEndPos = -1;
-            let searchPos = contentStartIndex;
-            while (true) {
-              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) {
-                validEndPos = endPos;
-                break;
-              } else {
-                searchPos = endPos + this.endPrefix.length;
+                  error: inputError instanceof Error ? inputError.message : String(inputError),
+                  executionTimeMs: Date.now() - startTime
+                };
               }
             }
-            if (nextStartPos !== -1 && (validEndPos === -1 || nextStartPos < validEndPos)) {
-              partEndIndex = nextStartPos;
-              endMarkerLength = 0;
-            } else if (validEndPos !== -1) {
-              partEndIndex = validEndPos;
-              endMarkerLength = this.endPrefix.length;
-            } else {
-              break;
-            }
+            this.logger.warn("Human input required but no callback provided", {
+              gadgetName: call.gadgetName
+            });
+            return {
+              gadgetName: call.gadgetName,
+              invocationId: call.invocationId,
+              parameters: validatedParameters,
+              error: "Human input required but not available (stdin is not interactive)",
+              executionTimeMs: Date.now() - startTime
+            };
           }
-          const parametersRaw = this.buffer.substring(contentStartIndex, partEndIndex).trim();
-          const { parameters, parseError } = this.parseParameters(parametersRaw);
-          yield {
-            type: "gadget_call",
-            call: {
-              gadgetName: actualGadgetName,
-              invocationId,
-              parametersRaw,
-              parameters,
-              parseError
-            }
+          const executionTimeMs = Date.now() - startTime;
+          this.logger.error("Gadget execution failed", {
+            gadgetName: call.gadgetName,
+            error: error instanceof Error ? error.message : String(error),
+            executionTimeMs
+          });
+          return {
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            parameters: validatedParameters,
+            error: error instanceof Error ? error.message : String(error),
+            executionTimeMs
           };
-          startIndex = partEndIndex + endMarkerLength;
-          this.lastReportedTextLength = startIndex;
-        }
-        if (startIndex > 0) {
-          this.buffer = this.buffer.substring(startIndex);
-          this.lastReportedTextLength = 0;
         }
       }
-      // 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,
-                parametersRaw,
-                parameters,
-                parseError
-              }
-            };
-            return;
-          }
-        }
-        const remainingText = this.takeTextUntil(this.buffer.length);
-        if (remainingText !== void 0) {
-          yield { type: "text", content: remainingText };
-        }
+      // Execute multiple gadget calls in parallel
+      async executeAll(calls) {
+        return Promise.all(calls.map((call) => this.execute(call)));
       }
-      // Reset parser state (note: global invocation counter is NOT reset to ensure unique IDs)
-      reset() {
-        this.buffer = "";
-        this.lastReportedTextLength = 0;
+      /**
+       * Deep equality check for objects/arrays.
+       * Used to detect if parameters were modified by an interceptor.
+       */
+      deepEquals(a, b) {
+        if (a === b) return true;
+        if (a === null || b === null) return a === b;
+        if (typeof a !== typeof b) return false;
+        if (typeof a !== "object") return a === b;
+        if (Array.isArray(a) !== Array.isArray(b)) return false;
+        if (Array.isArray(a) && Array.isArray(b)) {
+          if (a.length !== b.length) return false;
+          return a.every((val, i) => this.deepEquals(val, b[i]));
+        }
+        const aObj = a;
+        const bObj = b;
+        const aKeys = Object.keys(aObj);
+        const bKeys = Object.keys(bObj);
+        if (aKeys.length !== bKeys.length) return false;
+        return aKeys.every((key) => this.deepEquals(aObj[key], bObj[key]));
       }
     };
   }
@@ -2011,7 +2411,8 @@ var init_stream_processor = __esm({
           options.registry,
           options.onHumanInputRequired,
           this.logger.getSubLogger({ name: "executor" }),
-          options.defaultGadgetTimeoutMs
+          options.defaultGadgetTimeoutMs,
+          { argPrefix: options.gadgetArgPrefix }
         );
       }
       /**
@@ -5460,7 +5861,8 @@ var CLI_DESCRIPTION = "Command line utilities for llmist agents and direct LLM a
 var COMMANDS = {
   complete: "complete",
   agent: "agent",
-  models: "models"
+  models: "models",
+  gadget: "gadget"
 };
 var LOG_LEVELS = ["silly", "trace", "debug", "info", "warn", "error", "fatal"];
 var DEFAULT_MODEL = "openai:gpt-5-nano";
@@ -5504,7 +5906,7 @@ var import_commander2 = require("commander");
 // package.json
 var package_default = {
   name: "llmist",
-  version: "0.8.0",
+  version: "1.1.0",
   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",
@@ -7491,8 +7893,439 @@ function resolveInheritance(config, configPath) {
   return resolved;
 }
 
-// src/cli/models-command.ts
+// src/cli/gadget-command.ts
+var import_chalk5 = __toESM(require("chalk"), 1);
+init_schema_to_json();
+init_schema_validator();
+
+// src/cli/gadget-prompts.ts
+var import_promises3 = require("readline/promises");
 var import_chalk4 = __toESM(require("chalk"), 1);
+init_schema_to_json();
+async function promptForParameters(schema, ctx) {
+  if (!schema) {
+    return {};
+  }
+  const jsonSchema = schemaToJSONSchema(schema, { target: "draft-7" });
+  if (!jsonSchema.properties || Object.keys(jsonSchema.properties).length === 0) {
+    return {};
+  }
+  const rl = (0, import_promises3.createInterface)({ input: ctx.stdin, output: ctx.stdout });
+  const params = {};
+  try {
+    for (const [key, prop] of Object.entries(jsonSchema.properties)) {
+      const value = await promptForField(rl, key, prop, jsonSchema.required ?? []);
+      if (value !== void 0) {
+        params[key] = value;
+      }
+    }
+  } finally {
+    rl.close();
+  }
+  const result = schema.safeParse(params);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+    throw new Error(`Invalid parameters:
+${issues}`);
+  }
+  return result.data;
+}
+async function promptForField(rl, key, prop, required) {
+  const isRequired = required.includes(key);
+  const typeHint = formatTypeHint(prop);
+  const defaultHint = prop.default !== void 0 ? import_chalk4.default.dim(` [default: ${JSON.stringify(prop.default)}]`) : "";
+  const requiredMarker = isRequired ? import_chalk4.default.red("*") : "";
+  let prompt = `
+${import_chalk4.default.cyan.bold(key)}${requiredMarker}`;
+  if (prop.description) {
+    prompt += import_chalk4.default.dim(` - ${prop.description}`);
+  }
+  prompt += `
+  ${typeHint}${defaultHint}
+  ${import_chalk4.default.green(">")} `;
+  const answer = await rl.question(prompt);
+  const trimmed = answer.trim();
+  if (!trimmed) {
+    if (prop.default !== void 0) {
+      return void 0;
+    }
+    if (!isRequired) {
+      return void 0;
+    }
+    throw new Error(`Parameter '${key}' is required.`);
+  }
+  return parseValue(trimmed, prop, key);
+}
+function formatTypeHint(prop) {
+  if (prop.enum) {
+    return import_chalk4.default.yellow(`(${prop.enum.join(" | ")})`);
+  }
+  if (prop.type === "array") {
+    const items = prop.items;
+    if (items?.enum) {
+      return import_chalk4.default.yellow(`(${items.enum.join(" | ")})[] comma-separated`);
+    }
+    const itemType = items?.type ?? "any";
+    return import_chalk4.default.yellow(`(${itemType}[]) comma-separated`);
+  }
+  if (prop.type === "object" && prop.properties) {
+    return import_chalk4.default.yellow("(object) enter as JSON");
+  }
+  return import_chalk4.default.yellow(`(${prop.type ?? "any"})`);
+}
+function parseValue(input, prop, key) {
+  const type = prop.type;
+  if (type === "number" || type === "integer") {
+    const num = Number(input);
+    if (Number.isNaN(num)) {
+      throw new Error(`Invalid number for '${key}': ${input}`);
+    }
+    if (type === "integer" && !Number.isInteger(num)) {
+      throw new Error(`Expected integer for '${key}', got: ${input}`);
+    }
+    return num;
+  }
+  if (type === "boolean") {
+    const lower = input.toLowerCase();
+    if (["true", "yes", "1", "y"].includes(lower)) return true;
+    if (["false", "no", "0", "n"].includes(lower)) return false;
+    throw new Error(`Invalid boolean for '${key}': ${input} (use true/false, yes/no, 1/0)`);
+  }
+  if (type === "array") {
+    const items = input.split(",").map((s) => s.trim()).filter(Boolean);
+    const itemType = prop.items?.type;
+    if (itemType === "number" || itemType === "integer") {
+      return items.map((item) => {
+        const num = Number(item);
+        if (Number.isNaN(num)) throw new Error(`Invalid number in '${key}' array: ${item}`);
+        return num;
+      });
+    }
+    if (itemType === "boolean") {
+      return items.map((item) => {
+        const lower = item.toLowerCase();
+        if (["true", "yes", "1", "y"].includes(lower)) return true;
+        if (["false", "no", "0", "n"].includes(lower)) return false;
+        throw new Error(`Invalid boolean in '${key}' array: ${item}`);
+      });
+    }
+    return items;
+  }
+  if (type === "object") {
+    try {
+      return JSON.parse(input);
+    } catch {
+      throw new Error(`Invalid JSON for '${key}': ${input}`);
+    }
+  }
+  return input;
+}
+async function readStdinJson(stdin) {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    if (typeof chunk === "string") {
+      chunks.push(chunk);
+    } else {
+      chunks.push(chunk.toString("utf8"));
+    }
+  }
+  const content = chunks.join("").trim();
+  if (!content) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(content);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("Stdin must contain a JSON object, not an array or primitive.");
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid JSON from stdin: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+// src/cli/gadget-command.ts
+async function selectGadget(file, nameOption, cwd) {
+  const gadgets = await loadGadgets([file], cwd);
+  if (gadgets.length === 0) {
+    throw new Error(
+      `No gadgets found in '${file}'.
+Ensure the file exports a Gadget class or instance.`
+    );
+  }
+  if (gadgets.length === 1) {
+    const gadget = gadgets[0];
+    const name = gadget.name ?? gadget.constructor.name;
+    return { gadget, name };
+  }
+  const names = gadgets.map((g) => g.name ?? g.constructor.name);
+  if (!nameOption) {
+    throw new Error(
+      `File '${file}' exports ${gadgets.length} gadgets.
+Use --name to select one:
+` + names.map((n) => `  - ${n}`).join("\n")
+    );
+  }
+  const found = gadgets.find((g) => (g.name ?? g.constructor.name) === nameOption);
+  if (!found) {
+    throw new Error(
+      `Gadget '${nameOption}' not found in '${file}'.
+Available gadgets:
+` + names.map((n) => `  - ${n}`).join("\n")
+    );
+  }
+  return { gadget: found, name: nameOption };
+}
+async function executeGadgetRun(file, options, env) {
+  const cwd = process.cwd();
+  const { gadget, name } = await selectGadget(file, options.name, cwd);
+  env.stderr.write(import_chalk5.default.cyan.bold(`
+\u{1F527} Running gadget: ${name}
+`));
+  let params;
+  if (env.isTTY) {
+    params = await promptForParameters(gadget.parameterSchema, {
+      stdin: env.stdin,
+      stdout: env.stderr
+      // Prompts go to stderr to keep stdout clean
+    });
+  } else {
+    env.stderr.write(import_chalk5.default.dim("Reading parameters from stdin...\n"));
+    const stdinParams = await readStdinJson(env.stdin);
+    if (gadget.parameterSchema) {
+      const result2 = gadget.parameterSchema.safeParse(stdinParams);
+      if (!result2.success) {
+        const issues = result2.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`Invalid parameters:
+${issues}`);
+      }
+      params = result2.data;
+    } else {
+      params = stdinParams;
+    }
+  }
+  env.stderr.write(import_chalk5.default.dim("\nExecuting...\n"));
+  const startTime = Date.now();
+  let result;
+  try {
+    if (gadget.timeoutMs && gadget.timeoutMs > 0) {
+      result = await Promise.race([
+        Promise.resolve(gadget.execute(params)),
+        new Promise(
+          (_, reject) => setTimeout(
+            () => reject(new Error(`Gadget timed out after ${gadget.timeoutMs}ms`)),
+            gadget.timeoutMs
+          )
+        )
+      ]);
+    } else {
+      result = await Promise.resolve(gadget.execute(params));
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Execution failed: ${message}`);
+  }
+  const elapsed = Date.now() - startTime;
+  env.stderr.write(import_chalk5.default.green(`
+\u2713 Completed in ${elapsed}ms
+
+`));
+  formatOutput(result, options, env.stdout);
+}
+function formatOutput(result, options, stdout) {
+  if (options.raw) {
+    stdout.write(result);
+    if (!result.endsWith("\n")) stdout.write("\n");
+    return;
+  }
+  if (options.json || looksLikeJson(result)) {
+    try {
+      const parsed = JSON.parse(result);
+      stdout.write(JSON.stringify(parsed, null, 2) + "\n");
+      return;
+    } catch {
+    }
+  }
+  stdout.write(result);
+  if (!result.endsWith("\n")) stdout.write("\n");
+}
+function looksLikeJson(str) {
+  const trimmed = str.trim();
+  return trimmed.startsWith("{") && trimmed.endsWith("}") || trimmed.startsWith("[") && trimmed.endsWith("]");
+}
+async function executeGadgetInfo(file, options, env) {
+  const cwd = process.cwd();
+  const { gadget, name } = await selectGadget(file, options.name, cwd);
+  if (options.json) {
+    const info = buildGadgetInfo(gadget, name);
+    env.stdout.write(JSON.stringify(info, null, 2) + "\n");
+    return;
+  }
+  env.stdout.write("\n");
+  env.stdout.write(import_chalk5.default.cyan.bold(`${name}
+`));
+  env.stdout.write(import_chalk5.default.cyan("\u2550".repeat(name.length)) + "\n\n");
+  env.stdout.write(import_chalk5.default.bold("Description:\n"));
+  env.stdout.write(`  ${gadget.description}
+
+`);
+  if (gadget.parameterSchema) {
+    env.stdout.write(import_chalk5.default.bold("Parameters:\n"));
+    const jsonSchema = schemaToJSONSchema(gadget.parameterSchema, { target: "draft-7" });
+    env.stdout.write(formatSchemaAsText(jsonSchema, "  ") + "\n\n");
+  } else {
+    env.stdout.write(import_chalk5.default.dim("No parameters required.\n\n"));
+  }
+  if (gadget.timeoutMs) {
+    env.stdout.write(import_chalk5.default.bold("Timeout:\n"));
+    env.stdout.write(`  ${gadget.timeoutMs}ms
+
+`);
+  }
+  if (gadget.examples && gadget.examples.length > 0) {
+    env.stdout.write(import_chalk5.default.bold("Examples:\n"));
+    for (const example of gadget.examples) {
+      if (example.comment) {
+        env.stdout.write(import_chalk5.default.dim(`  # ${example.comment}
+`));
+      }
+      env.stdout.write(`  Input: ${import_chalk5.default.cyan(JSON.stringify(example.params))}
+`);
+      if (example.output !== void 0) {
+        env.stdout.write(`  Output: ${import_chalk5.default.green(example.output)}
+`);
+      }
+      env.stdout.write("\n");
+    }
+  }
+}
+function buildGadgetInfo(gadget, name) {
+  const info = {
+    name,
+    description: gadget.description
+  };
+  if (gadget.parameterSchema) {
+    info.schema = schemaToJSONSchema(gadget.parameterSchema, { target: "draft-7" });
+  }
+  if (gadget.timeoutMs) {
+    info.timeoutMs = gadget.timeoutMs;
+  }
+  if (gadget.examples && gadget.examples.length > 0) {
+    info.examples = gadget.examples;
+  }
+  return info;
+}
+function formatSchemaAsText(schema, indent = "") {
+  const lines = [];
+  const properties = schema.properties || {};
+  const required = schema.required || [];
+  for (const [key, prop] of Object.entries(properties)) {
+    const type = prop.type;
+    const description = prop.description;
+    const isRequired = required.includes(key);
+    const enumValues = prop.enum;
+    const defaultValue = prop.default;
+    let line = `${indent}${import_chalk5.default.cyan(key)}`;
+    if (isRequired) {
+      line += import_chalk5.default.red("*");
+    }
+    if (type === "array") {
+      const items = prop.items;
+      const itemType = items?.type || "any";
+      line += import_chalk5.default.dim(` (${itemType}[])`);
+    } else if (type === "object" && prop.properties) {
+      line += import_chalk5.default.dim(" (object)");
+    } else {
+      line += import_chalk5.default.dim(` (${type})`);
+    }
+    if (defaultValue !== void 0) {
+      line += import_chalk5.default.dim(` [default: ${JSON.stringify(defaultValue)}]`);
+    }
+    if (description) {
+      line += `: ${description}`;
+    }
+    if (enumValues) {
+      line += import_chalk5.default.yellow(` - one of: ${enumValues.join(", ")}`);
+    }
+    lines.push(line);
+    if (type === "object" && prop.properties) {
+      lines.push(formatSchemaAsText(prop, indent + "  "));
+    }
+  }
+  return lines.join("\n");
+}
+async function executeGadgetValidate(file, env) {
+  const cwd = process.cwd();
+  try {
+    const gadgets = await loadGadgets([file], cwd);
+    if (gadgets.length === 0) {
+      throw new Error(
+        "No gadgets exported from file.\nA valid gadget must have:\n  - execute() method\n  - description property\n  - parameterSchema (optional)"
+      );
+    }
+    const issues = [];
+    for (const gadget of gadgets) {
+      const name = gadget.name ?? gadget.constructor.name;
+      if (!gadget.description) {
+        issues.push(`${name}: Missing 'description' property.`);
+      }
+      if (gadget.parameterSchema) {
+        try {
+          validateGadgetSchema(gadget.parameterSchema, name);
+        } catch (schemaError) {
+          const message = schemaError instanceof Error ? schemaError.message : String(schemaError);
+          issues.push(`${name}: ${message}`);
+        }
+      }
+      if (typeof gadget.execute !== "function") {
+        issues.push(`${name}: Missing 'execute()' method.`);
+      }
+    }
+    if (issues.length > 0) {
+      throw new Error(`Validation issues:
+${issues.map((i) => `  - ${i}`).join("\n")}`);
+    }
+    env.stdout.write(import_chalk5.default.green.bold("\n\u2713 Valid\n\n"));
+    env.stdout.write(import_chalk5.default.bold("Gadgets found:\n"));
+    for (const gadget of gadgets) {
+      const name = gadget.name ?? gadget.constructor.name;
+      const schemaInfo = gadget.parameterSchema ? import_chalk5.default.cyan("(with schema)") : import_chalk5.default.dim("(no schema)");
+      env.stdout.write(`  ${import_chalk5.default.bold(name)} ${schemaInfo}
+`);
+      env.stdout.write(import_chalk5.default.dim(`    ${gadget.description}
+`));
+    }
+    env.stdout.write("\n");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    env.stdout.write(import_chalk5.default.red.bold(`
+\u2717 Invalid
+
+`));
+    env.stdout.write(`${message}
+
+`);
+    env.setExitCode(1);
+  }
+}
+function registerGadgetCommand(program, env) {
+  const gadgetCmd = program.command("gadget").description("Test and inspect gadgets outside the agent loop.");
+  gadgetCmd.command("run <file>").description("Execute a gadget with interactive prompts or stdin JSON.").option("--name <gadget>", "Select gadget by name (required if file exports multiple)").option("--json", "Format output as pretty-printed JSON").option("--raw", "Output result as raw string without formatting").action(
+    (file, options) => executeAction(() => executeGadgetRun(file, options, env), env)
+  );
+  gadgetCmd.command("info <file>").description("Display gadget description, schema, and examples.").option("--name <gadget>", "Select gadget by name (required if file exports multiple)").option("--json", "Output as JSON instead of formatted text").action(
+    (file, options) => executeAction(() => executeGadgetInfo(file, options, env), env)
+  );
+  gadgetCmd.command("validate <file>").description("Check if file exports valid gadget(s).").action(
+    (file) => executeAction(() => executeGadgetValidate(file, env), env)
+  );
+}
+
+// src/cli/models-command.ts
+var import_chalk6 = __toESM(require("chalk"), 1);
 init_model_shortcuts();
 async function handleModelsCommand(options, env) {
   const client = env.createClient();
@@ -7512,13 +8345,13 @@ function renderTable(models, verbose, stream2) {
     }
     grouped.get(provider).push(model);
   }
-  stream2.write(import_chalk4.default.bold.cyan("\nAvailable Models\n"));
-  stream2.write(import_chalk4.default.cyan("=".repeat(80)) + "\n\n");
+  stream2.write(import_chalk6.default.bold.cyan("\nAvailable Models\n"));
+  stream2.write(import_chalk6.default.cyan("=".repeat(80)) + "\n\n");
   const providers = Array.from(grouped.keys()).sort();
   for (const provider of providers) {
     const providerModels = grouped.get(provider);
     const providerName = provider.charAt(0).toUpperCase() + provider.slice(1);
-    stream2.write(import_chalk4.default.bold.yellow(`${providerName} Models
+    stream2.write(import_chalk6.default.bold.yellow(`${providerName} Models
 `));
     if (verbose) {
       renderVerboseTable(providerModels, stream2);
@@ -7527,11 +8360,11 @@ function renderTable(models, verbose, stream2) {
     }
     stream2.write("\n");
   }
-  stream2.write(import_chalk4.default.bold.magenta("Model Shortcuts\n"));
-  stream2.write(import_chalk4.default.dim("\u2500".repeat(80)) + "\n");
+  stream2.write(import_chalk6.default.bold.magenta("Model Shortcuts\n"));
+  stream2.write(import_chalk6.default.dim("\u2500".repeat(80)) + "\n");
   const shortcuts = Object.entries(MODEL_ALIASES).sort((a, b) => a[0].localeCompare(b[0]));
   for (const [shortcut, fullName] of shortcuts) {
-    stream2.write(import_chalk4.default.cyan(`  ${shortcut.padEnd(15)}`) + import_chalk4.default.dim(" \u2192 ") + import_chalk4.default.white(fullName) + "\n");
+    stream2.write(import_chalk6.default.cyan(`  ${shortcut.padEnd(15)}`) + import_chalk6.default.dim(" \u2192 ") + import_chalk6.default.white(fullName) + "\n");
   }
   stream2.write("\n");
 }
@@ -7541,45 +8374,45 @@ function renderCompactTable(models, stream2) {
   const contextWidth = 13;
   const inputWidth = 10;
   const outputWidth = 10;
-  stream2.write(import_chalk4.default.dim("\u2500".repeat(idWidth + nameWidth + contextWidth + inputWidth + outputWidth + 8)) + "\n");
+  stream2.write(import_chalk6.default.dim("\u2500".repeat(idWidth + nameWidth + contextWidth + inputWidth + outputWidth + 8)) + "\n");
   stream2.write(
-    import_chalk4.default.bold(
+    import_chalk6.default.bold(
       "Model ID".padEnd(idWidth) + "  " + "Display Name".padEnd(nameWidth) + "  " + "Context".padEnd(contextWidth) + "  " + "Input".padEnd(inputWidth) + "  " + "Output".padEnd(outputWidth)
     ) + "\n"
   );
-  stream2.write(import_chalk4.default.dim("\u2500".repeat(idWidth + nameWidth + contextWidth + inputWidth + outputWidth + 8)) + "\n");
+  stream2.write(import_chalk6.default.dim("\u2500".repeat(idWidth + nameWidth + contextWidth + inputWidth + outputWidth + 8)) + "\n");
   for (const model of models) {
     const contextFormatted = formatTokens2(model.contextWindow);
     const inputPrice = `$${model.pricing.input.toFixed(2)}`;
     const outputPrice = `$${model.pricing.output.toFixed(2)}`;
     stream2.write(
-      import_chalk4.default.green(model.modelId.padEnd(idWidth)) + "  " + import_chalk4.default.white(model.displayName.padEnd(nameWidth)) + "  " + import_chalk4.default.yellow(contextFormatted.padEnd(contextWidth)) + "  " + import_chalk4.default.cyan(inputPrice.padEnd(inputWidth)) + "  " + import_chalk4.default.cyan(outputPrice.padEnd(outputWidth)) + "\n"
+      import_chalk6.default.green(model.modelId.padEnd(idWidth)) + "  " + import_chalk6.default.white(model.displayName.padEnd(nameWidth)) + "  " + import_chalk6.default.yellow(contextFormatted.padEnd(contextWidth)) + "  " + import_chalk6.default.cyan(inputPrice.padEnd(inputWidth)) + "  " + import_chalk6.default.cyan(outputPrice.padEnd(outputWidth)) + "\n"
     );
   }
-  stream2.write(import_chalk4.default.dim("\u2500".repeat(idWidth + nameWidth + contextWidth + inputWidth + outputWidth + 8)) + "\n");
-  stream2.write(import_chalk4.default.dim(`  * Prices are per 1M tokens
+  stream2.write(import_chalk6.default.dim("\u2500".repeat(idWidth + nameWidth + contextWidth + inputWidth + outputWidth + 8)) + "\n");
+  stream2.write(import_chalk6.default.dim(`  * Prices are per 1M tokens
 `));
 }
 function renderVerboseTable(models, stream2) {
   for (const model of models) {
-    stream2.write(import_chalk4.default.bold.green(`
+    stream2.write(import_chalk6.default.bold.green(`
   ${model.modelId}
 `));
-    stream2.write(import_chalk4.default.dim("  " + "\u2500".repeat(60)) + "\n");
-    stream2.write(`  ${import_chalk4.default.dim("Name:")}         ${import_chalk4.default.white(model.displayName)}
+    stream2.write(import_chalk6.default.dim("  " + "\u2500".repeat(60)) + "\n");
+    stream2.write(`  ${import_chalk6.default.dim("Name:")}         ${import_chalk6.default.white(model.displayName)}
 `);
-    stream2.write(`  ${import_chalk4.default.dim("Context:")}      ${import_chalk4.default.yellow(formatTokens2(model.contextWindow))}
+    stream2.write(`  ${import_chalk6.default.dim("Context:")}      ${import_chalk6.default.yellow(formatTokens2(model.contextWindow))}
 `);
-    stream2.write(`  ${import_chalk4.default.dim("Max Output:")}   ${import_chalk4.default.yellow(formatTokens2(model.maxOutputTokens))}
+    stream2.write(`  ${import_chalk6.default.dim("Max Output:")}   ${import_chalk6.default.yellow(formatTokens2(model.maxOutputTokens))}
 `);
-    stream2.write(`  ${import_chalk4.default.dim("Pricing:")}      ${import_chalk4.default.cyan(`$${model.pricing.input.toFixed(2)} input`)} ${import_chalk4.default.dim("/")} ${import_chalk4.default.cyan(`$${model.pricing.output.toFixed(2)} output`)} ${import_chalk4.default.dim("(per 1M tokens)")}
+    stream2.write(`  ${import_chalk6.default.dim("Pricing:")}      ${import_chalk6.default.cyan(`$${model.pricing.input.toFixed(2)} input`)} ${import_chalk6.default.dim("/")} ${import_chalk6.default.cyan(`$${model.pricing.output.toFixed(2)} output`)} ${import_chalk6.default.dim("(per 1M tokens)")}
 `);
     if (model.pricing.cachedInput !== void 0) {
-      stream2.write(`  ${import_chalk4.default.dim("Cached Input:")} ${import_chalk4.default.cyan(`$${model.pricing.cachedInput.toFixed(2)} per 1M tokens`)}
+      stream2.write(`  ${import_chalk6.default.dim("Cached Input:")} ${import_chalk6.default.cyan(`$${model.pricing.cachedInput.toFixed(2)} per 1M tokens`)}
 `);
     }
     if (model.knowledgeCutoff) {
-      stream2.write(`  ${import_chalk4.default.dim("Knowledge:")}    ${model.knowledgeCutoff}
+      stream2.write(`  ${import_chalk6.default.dim("Knowledge:")}    ${model.knowledgeCutoff}
 `);
     }
     const features = [];
@@ -7590,20 +8423,20 @@ function renderVerboseTable(models, stream2) {
     if (model.features.structuredOutputs) features.push("structured-outputs");
     if (model.features.fineTuning) features.push("fine-tuning");
     if (features.length > 0) {
-      stream2.write(`  ${import_chalk4.default.dim("Features:")}     ${import_chalk4.default.blue(features.join(", "))}
+      stream2.write(`  ${import_chalk6.default.dim("Features:")}     ${import_chalk6.default.blue(features.join(", "))}
 `);
     }
     if (model.metadata) {
       if (model.metadata.family) {
-        stream2.write(`  ${import_chalk4.default.dim("Family:")}       ${model.metadata.family}
+        stream2.write(`  ${import_chalk6.default.dim("Family:")}       ${model.metadata.family}
 `);
       }
       if (model.metadata.releaseDate) {
-        stream2.write(`  ${import_chalk4.default.dim("Released:")}     ${model.metadata.releaseDate}
+        stream2.write(`  ${import_chalk6.default.dim("Released:")}     ${model.metadata.releaseDate}
 `);
       }
       if (model.metadata.notes) {
-        stream2.write(`  ${import_chalk4.default.dim("Notes:")}        ${import_chalk4.default.italic(model.metadata.notes)}
+        stream2.write(`  ${import_chalk6.default.dim("Notes:")}        ${import_chalk6.default.italic(model.metadata.notes)}
 `);
       }
     }
@@ -7653,7 +8486,7 @@ function registerModelsCommand(program, env) {
 
 // src/cli/environment.ts
 var import_node_readline = __toESM(require("readline"), 1);
-var import_chalk5 = __toESM(require("chalk"), 1);
+var import_chalk7 = __toESM(require("chalk"), 1);
 init_client();
 init_logger();
 var LOG_LEVEL_MAP = {
@@ -7702,14 +8535,14 @@ function createPromptFunction(stdin, stdout) {
         output: stdout
       });
       stdout.write("\n");
-      stdout.write(`${import_chalk5.default.cyan("\u2500".repeat(60))}
+      stdout.write(`${import_chalk7.default.cyan("\u2500".repeat(60))}
 `);
-      stdout.write(import_chalk5.default.cyan.bold("\u{1F916} Agent asks:\n"));
+      stdout.write(import_chalk7.default.cyan.bold("\u{1F916} Agent asks:\n"));
       stdout.write(`${question}
 `);
-      stdout.write(`${import_chalk5.default.cyan("\u2500".repeat(60))}
+      stdout.write(`${import_chalk7.default.cyan("\u2500".repeat(60))}
 `);
-      rl.question(import_chalk5.default.green.bold("You: "), (answer) => {
+      rl.question(import_chalk7.default.green.bold("You: "), (answer) => {
         rl.close();
         resolve(answer);
       });
@@ -7799,6 +8632,7 @@ function createProgram(env, config) {
   registerCompleteCommand(program, env, config?.complete);
   registerAgentCommand(program, env, config?.agent);
   registerModelsCommand(program, env);
+  registerGadgetCommand(program, env);
   if (config) {
     const customNames = getCustomCommandNames(config);
     for (const name of customNames) {