mini-a-utils.js

// Author: Nuno Aguiar
// License: Apache 2.0
// Description: Mini-A utils tool for basic file operations within a specified root directory

loadLib("mini-a-common.js")

/**
 * <odoc>
 * <key>MiniUtilsTool(options) : MiniUtilsTool</key>
 * Creates a MiniUtilsTool instance to perform file operations within a specified root directory.
 * </odoc>
 */
var MiniUtilsTool = function(options) {
  this._initialized = false
  this._root = null
  this._rootWithSep = null
  this._readWrite = false
  this._separator = String(java.io.File.separator)
  this._listNestedKeys = ["files", "dirs", "children", "items", "list", "entries", "content"]
  this._skillTemplateCandidates = ["SKILL.yaml", "SKILL.yml", "SKILL.json", "SKILL.md", "skill.md"]
  this._skillsRoots = []
  this._wikiManager = __
  //if (isDef(options)) {
    this.init(options)
  //}
}

/**
 * <odoc>
 * <key>MiniUtilsTool.init(options) : Object</key>
 * Initializes the MiniUtilsTool instance with the specified options.
 *
 * The `options` parameter can be:
 * - A string representing the root directory path.
 * - An object with the following properties:
 *   - `root` (string): The root directory path. Defaults to the current directory (`"."`).
 *   - `readwrite` (boolean): If set to `true`, enables write operations. Defaults to `false` (read-only mode).
 *
 * Returns the MiniUtilsTool instance on success, or an error message string on failure.
 * </odoc>
 */
MiniUtilsTool.prototype.init = function(options) {
  try {
    if (isUnDef(options)) options = {}
    if (isString(options) || options instanceof java.lang.String) options = { root: options }
    var rootPath = options.root || "."
    var rootFile = io.fileInfo(rootPath)
    var canonicalRoot = rootFile.canonicalPath
    if (!io.fileExists(canonicalRoot)) {
      return "[ERROR] Root path not found: " + rootPath
    }
    if (!rootFile.isDirectory) {
      return "[ERROR] Root path is not a directory: " + canonicalRoot
    }

    var info = io.fileInfo(canonicalRoot)
    if (isUnDef(info) || info.isDirectory !== true) {
      return "[ERROR] Unable to load directory information for: " + canonicalRoot
    }

    this._root = canonicalRoot
    this._readWrite = options.readwrite === true
    this._skillsRoots = this._resolveSkillsRoots(options)
    var sep = String(java.io.File.separator)
    this._separator = sep
    if (canonicalRoot.indexOf(sep, canonicalRoot.length - sep.length) === -1) {
      this._rootWithSep = canonicalRoot + sep
    } else {
      this._rootWithSep = canonicalRoot
    }
    this._initialized = true
    return this
  } catch (e) {
    this._initialized = false
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

MiniUtilsTool.prototype._ensureInitialized = function() {
  if (this._initialized !== true) {
    throw new Error("File context not initialized")
  }
}

MiniUtilsTool.prototype._withinRoot = function(candidate) {
  if (!isString(candidate)) return false
  if (candidate === this._root) return true
  return isString(this._rootWithSep) && candidate.indexOf(this._rootWithSep) === 0
}

MiniUtilsTool.prototype._toRelative = function(targetPath) {
  if (!isString(targetPath)) return targetPath
  if (!this._withinRoot(targetPath)) return targetPath
  var relative = targetPath.substring(this._root.length)
  if (relative.indexOf(this._separator) === 0) {
    relative = relative.substring(this._separator.length)
  }
  if (relative.length === 0) {
    relative = "."
  }
  return relative
}

MiniUtilsTool.prototype._resolve = function(target) {
  var candidate = new java.io.File(target)
  if (!candidate.isAbsolute()) {
    candidate = new java.io.File(this._root, target)
  }
  var resolved = String(candidate.getCanonicalPath())
  if (!this._withinRoot(resolved)) {
    throw new Error("Path outside of allowed root: " + target)
  }
  return resolved
}

MiniUtilsTool.prototype._ensureWritable = function(operation) {
  if (this._readWrite !== true) {
    throw new Error("Read-only mode. Set readwrite=true to allow " + operation)
  }
}

MiniUtilsTool.prototype._createGlobMatcher = function(pattern) {
  try {
    var fileSystem = java.nio.file.FileSystems.getDefault()
    return fileSystem.getPathMatcher("glob:" + pattern)
  } catch (e) {
    return null
  }
}

MiniUtilsTool.prototype._resolveSkillsRoots = function(options) {
  options = isMap(options) ? options : {}
  var roots = []
  var seen = {}
  var self = this
  var addRoot = function(pathValue) {
    if (!(isString(pathValue) || pathValue instanceof java.lang.String)) return
    var trimmed = String(pathValue).trim()
    if (trimmed.length === 0) return
    var expanded = self._expandHomePath(trimmed)
    var canonical
    try {
      canonical = String(new java.io.File(expanded).getCanonicalPath())
    } catch (e) {
      return
    }
    if (seen[canonical]) return
    if (!io.fileExists(canonical)) return
    var info = io.fileInfo(canonical)
    if (isUnDef(info) || info.isDirectory !== true) return
    seen[canonical] = true
    roots.push(canonical)
  }

  if (isString(options.skillsroot) || options.skillsroot instanceof java.lang.String) addRoot(options.skillsroot)
  if (isArray(options.skillsroots)) {
    options.skillsroots.forEach(function(entry) {
      addRoot(entry)
    })
  }

  if (roots.length === 0) {
    var userHome = java.lang.System.getProperty("user.home")
    if (isString(userHome) || userHome instanceof java.lang.String) {
      userHome = String(userHome)
      if (userHome.length > 0) {
        addRoot(userHome + java.io.File.separator + ".openaf-mini-a" + java.io.File.separator + "skills")
      }
    }

    if (typeof __gHDir === "function") {
      try {
        var gHome = __gHDir()
        if (isString(gHome) || gHome instanceof java.lang.String) {
          gHome = String(gHome)
          if (gHome.length > 0) {
            addRoot(gHome + java.io.File.separator + ".openaf-mini-a" + java.io.File.separator + "skills")
          }
        }
      } catch (ignoreGHDirError) {
      }
    }
  }
  return roots
}

MiniUtilsTool.prototype._expandHomePath = function(pathValue) {
  if (!(isString(pathValue) || pathValue instanceof java.lang.String)) return pathValue
  pathValue = String(pathValue)
  if (pathValue === "~") return java.lang.System.getProperty("user.home")
  if (pathValue.indexOf("~/") === 0 || pathValue.indexOf("~\\") === 0) {
    var home = java.lang.System.getProperty("user.home")
    if (isString(home) && home.length > 0) {
      return home + pathValue.substring(1)
    }
  }
  return pathValue
}

MiniUtilsTool.prototype._getSkillRelativeToRoot = function(rootPath, targetPath) {
  if (!(isString(rootPath) || rootPath instanceof java.lang.String)) return targetPath
  if (!(isString(targetPath) || targetPath instanceof java.lang.String)) return targetPath
  rootPath = String(rootPath)
  targetPath = String(targetPath)
  if (targetPath === rootPath) return "."
  var sep = String(java.io.File.separator)
  var rootWithSep = rootPath
  if (rootPath.indexOf(sep, rootPath.length - sep.length) === -1) {
    rootWithSep = rootPath + sep
  }
  if (targetPath.indexOf(rootWithSep) === 0) {
    return targetPath.substring(rootWithSep.length)
  }
  return targetPath
}

MiniUtilsTool.prototype._resolveSkillTemplateFromFolder = function(folderPath) {
  if (!(isString(folderPath) || folderPath instanceof java.lang.String)) return __
  return __miniAResolveSkillTemplateFromFolder(String(folderPath), this._skillTemplateCandidates)
}

MiniUtilsTool.prototype._readSkillDescriptionFromTemplate = function(templatePath) {
  if (!(isString(templatePath) || templatePath instanceof java.lang.String)) return __
  return __miniAReadSkillDescriptionFromTemplate(String(templatePath))
}

MiniUtilsTool.prototype._listSkills = function(params) {
  var payload = isMap(params) ? params : {}
  var includeHidden = payload.includeHidden === true
  var query = isString(payload.query) ? payload.query.toLowerCase().trim() : ""
  var seenByName = {}
  var results = []
  var self = this
  var validName = /^[a-z0-9][a-z0-9_-]*$/

  this._skillsRoots.forEach(function(rootPath) {
    var listing
    try {
      listing = io.listFiles(rootPath)
    } catch (e) {
      listing = __
    }
    if (!isMap(listing) || !isArray(listing.files)) return

    listing.files.forEach(function(entry) {
      var entryName = __
      var isDirectory = false

      if (isMap(entry) && (isString(entry.filename) || entry.filename instanceof java.lang.String)) {
        entryName = String(entry.filename)
        isDirectory = entry.isDirectory === true
      } else if (isString(entry) || entry instanceof java.lang.String) {
        entryName = String(entry)
        try {
          var fromString = new java.io.File(rootPath, entryName)
          isDirectory = fromString.isDirectory()
        } catch (entryErr) {
          isDirectory = false
        }
      } else {
        return
      }

      if (!isString(entryName) || entryName.length === 0) return
      if (__miniAShouldIgnoreSkillEntryName(entryName, includeHidden)) return

      var name = __
      var sourceType = "file"
      var templatePath = __

      if (isDirectory === true) {
        name = entryName.toLowerCase()
        try {
          var folderPath = String(new java.io.File(rootPath, entryName).getCanonicalPath())
          templatePath = self._resolveSkillTemplateFromFolder(folderPath)
        } catch (folderErr) {
          templatePath = __
        }
        if (isUnDef(templatePath)) return
        sourceType = "folder"
      } else {
        if (!/\.(md|ya?ml|json)$/i.test(entryName)) return
        name = entryName.replace(/\.(md|ya?ml|json)$/i, "").toLowerCase()
        try {
          templatePath = String(new java.io.File(rootPath, entryName).getCanonicalPath())
        } catch (fileErr) {
          templatePath = __
        }
      }

      if (!isString(name) || !validName.test(name)) return
      if (!isString(templatePath) || !io.fileExists(templatePath)) return
      if (seenByName[name]) return

      var description = sourceType === "folder"
        ? self._readSkillDescriptionFromTemplate(templatePath)
        : (function() {
            var doc = __miniALoadSkillTemplateDocument(templatePath)
            return isObject(doc) && isString(doc.description) ? doc.description : __
          })()
      var skillFormat = __miniASkillTemplateFormatFromPath(templatePath)
      var relativePath = self._getSkillRelativeToRoot(rootPath, templatePath)
      var queryText = [
        name,
        isString(relativePath) ? relativePath : "",
        isString(description) ? description : ""
      ].join(" ").toLowerCase()
      if (query.length > 0 && queryText.indexOf(query) < 0) return

      seenByName[name] = true
      results.push({
        name        : name,
        sourceType  : sourceType,
        skillFormat : skillFormat,
        description : description,
        templatePath: templatePath,
        relativePath: relativePath,
        rootPath    : rootPath
      })
    })
  })

  results.sort(function(a, b) {
    return String(a.name).localeCompare(String(b.name))
  })
  return results
}

MiniUtilsTool.prototype._parseSkillArgs = function(rawValue) {
  var raw = isString(rawValue) ? rawValue.trim() : ""
  if (raw.length === 0) return { ok: true, raw: "", argv: [], argc: 0 }

  var argv = []
  var current = ""
  var quote = ""
  var escaping = false
  for (var i = 0; i < raw.length; i++) {
    var ch = raw.charAt(i)

    if (escaping) {
      current += ch
      escaping = false
      continue
    }

    if (ch === "\\") {
      escaping = true
      continue
    }

    if (quote.length > 0) {
      if (ch === quote) quote = ""
      else current += ch
      continue
    }

    if (ch === "'" || ch === "\"") {
      quote = ch
      continue
    }

    if (/\s/.test(ch)) {
      if (current.length > 0) {
        argv.push(current)
        current = ""
      }
      continue
    }
    current += ch
  }

  if (escaping || quote.length > 0) {
    return { ok: false, error: "Unbalanced quotes or trailing escape in arguments." }
  }
  if (current.length > 0) argv.push(current)
  return {
    ok  : true,
    raw : raw,
    argv: argv,
    argc: argv.length
  }
}

MiniUtilsTool.prototype._renderSkillTemplate = function(template, parsedArgs) {
  return __miniARenderSkillTemplate(template, parsedArgs)
}

MiniUtilsTool.prototype._normalizeSkillReferencePath = function(rawPath) {
  if (!isString(rawPath)) return __
  var normalized = rawPath.trim()
  if (normalized.length === 0) return __
  if (normalized.charAt(0) === "<" && normalized.charAt(normalized.length - 1) === ">") {
    normalized = normalized.substring(1, normalized.length - 1).trim()
  }
  return normalized.length > 0 ? normalized : __
}

MiniUtilsTool.prototype._isAbsoluteOrExternalSkillPath = function(pathValue) {
  if (!isString(pathValue) || pathValue.length === 0) return false
  if (pathValue.charAt(0) === "/" || pathValue.charAt(0) === "~") return true
  if (/^[A-Za-z]:[\\/]/.test(pathValue)) return true
  if (/^[a-z][a-z0-9+.-]*:/i.test(pathValue)) return true
  if (pathValue.indexOf("//") === 0) return true
  return false
}

MiniUtilsTool.prototype._normalizeSkillVirtualPath = function(rawPath) {
  if (!isString(rawPath)) return __
  var normalized = rawPath.trim().replace(/\\/g, "/")
  if (normalized.length === 0) return __
  if (normalized.charAt(0) === "<" && normalized.charAt(normalized.length - 1) === ">") normalized = normalized.substring(1, normalized.length - 1).trim()
  if (normalized.indexOf("./") === 0) normalized = normalized.substring(2)
  while (normalized.indexOf("//") >= 0) normalized = normalized.replace(/\/\//g, "/")
  return normalized.length > 0 ? normalized : __
}

MiniUtilsTool.prototype._recordSkillReference = function(references, seen, ref) {
  if (!isArray(references) || !isMap(ref)) return
  var key = (isString(ref.type) ? ref.type : "file") + ":" + (isString(ref.path) ? ref.path : "")
  if (key === "file:") return
  if (seen[key]) return
  seen[key] = true
  references.push(ref)
}

MiniUtilsTool.prototype._preprocessSkillTemplateReferences = function(templateText, selected, loadedDoc) {
  var result = {
    text: isString(templateText) ? String(templateText) : "",
    references: []
  }
  if (!isString(result.text) || result.text.length === 0) return result
  if (!isMap(selected) || !isString(selected.templatePath) || selected.templatePath.trim().length === 0) return result

  var templatePath = String(selected.templatePath)
  var templateDir = templatePath.replace(/[\\\/][^\\\/]+$/, "")
  if (!isString(templateDir) || templateDir.length === 0) return result

  var virtualFiles = (isObject(loadedDoc) && isObject(loadedDoc.virtualFiles)) ? loadedDoc.virtualFiles : {}
  var references = []
  var seen = {}
  var self = this

  function splitAttachmentToken(rawToken) {
    var token = isString(rawToken) ? rawToken : ""
    var suffix = ""
    while (token.length > 0) {
      var lastChar = token.charAt(token.length - 1)
      if (/[,.;:!?)\]}'"]/.test(lastChar)) {
        suffix = lastChar + suffix
        token = token.substring(0, token.length - 1)
        continue
      }
      break
    }
    return { filePath: token, suffix: suffix }
  }

  function countImmediateBackslashes(text, position) {
    if (!isString(text) || !isNumber(position) || position <= 0) return 0
    var count = 0
    for (var idx = position - 1; idx >= 0 && text.charAt(idx) === "\\"; idx--) count++
    return count
  }

  function canStartInlineShortcut(text, markerPos) {
    if (!isString(text) || !isNumber(markerPos) || markerPos < 0 || markerPos >= text.length) return false
    if (markerPos === 0) return true
    var prevChar = text.charAt(markerPos - 1)
    if (/\s/.test(prevChar)) return true
    if (/[\(\[\{<"'`,;:!?]/.test(prevChar)) return true
    return false
  }

  var text = result.text
  var chunks = []
  var cursor = 0
  var wsPattern = /\s/
  while (cursor < text.length) {
    var atPos = text.indexOf("@", cursor)
    if (atPos < 0) {
      chunks.push(text.substring(cursor))
      break
    }
    if (countImmediateBackslashes(text, atPos) > 0 || !canStartInlineShortcut(text, atPos)) {
      chunks.push(text.substring(cursor, atPos + 1))
      cursor = atPos + 1
      continue
    }

    var endPos = atPos + 1
    while (endPos < text.length && !wsPattern.test(text.charAt(endPos))) endPos++
    var rawToken = text.substring(atPos + 1, endPos)
    var tokenParts = splitAttachmentToken(rawToken)
    var filePath = self._normalizeSkillReferencePath(tokenParts.filePath)
    var replacement = "@" + tokenParts.filePath
    var normalizedVirtualPath = self._normalizeSkillVirtualPath(filePath)

    if (isString(normalizedVirtualPath) && Object.prototype.hasOwnProperty.call(virtualFiles, normalizedVirtualPath)) {
      var virtualBody = virtualFiles[normalizedVirtualPath]
      if (!isString(virtualBody)) virtualBody = String(virtualBody || "")
      self._recordSkillReference(references, seen, { type: "embedded", path: normalizedVirtualPath })
      replacement = "\n\n--- Skill reference from " + normalizedVirtualPath + " ---\n" + virtualBody + "\n--- End of " + normalizedVirtualPath + " ---\n"
    } else if (isString(filePath) && filePath.length > 0 && !self._isAbsoluteOrExternalSkillPath(filePath)) {
      var resolved = String(new java.io.File(templateDir, filePath).getCanonicalPath())
      try {
        if (io.fileExists(resolved) && io.fileInfo(resolved).isFile === true) {
          self._recordSkillReference(references, seen, { type: "file", path: resolved, relativePath: filePath })
          replacement = "@" + resolved
        }
      } catch(ignoreResolvedSkillRefError) { }
    }

    chunks.push(text.substring(cursor, atPos))
    chunks.push(replacement)
    if (tokenParts.suffix.length > 0) chunks.push(tokenParts.suffix)
    cursor = endPos
  }
  text = chunks.join("")

  var includedPaths = {}
  var includeBlocks = []
  text.replace(/\[[^\]]*\]\(([^)\n]+)\)/g, function(_, targetSpec) {
    var spec = isString(targetSpec) ? targetSpec.trim() : ""
    if (spec.length === 0) return _
    var firstToken = spec.split(/\s+/)[0]
    var normalizedTarget = self._normalizeSkillReferencePath(firstToken)
    if (!isString(normalizedTarget) || normalizedTarget.length === 0) return _
    if (normalizedTarget.charAt(0) === "#") return _
    if (self._isAbsoluteOrExternalSkillPath(normalizedTarget)) return _

    var cleanTarget = normalizedTarget.split("#")[0].split("?")[0]
    if (!/\.md$/i.test(cleanTarget)) return _
    var normalizedVirtualTarget = self._normalizeSkillVirtualPath(cleanTarget)
    if (isString(normalizedVirtualTarget) && Object.prototype.hasOwnProperty.call(virtualFiles, normalizedVirtualTarget)) {
      if (Object.prototype.hasOwnProperty.call(includedPaths, "virtual:" + normalizedVirtualTarget)) return _
      includedPaths["virtual:" + normalizedVirtualTarget] = true
      var virtualRefContent = virtualFiles[normalizedVirtualTarget]
      if (!isString(virtualRefContent)) virtualRefContent = String(virtualRefContent || "")
      self._recordSkillReference(references, seen, { type: "embedded", path: normalizedVirtualTarget })
      includeBlocks.push("\n\n--- Skill reference from " + normalizedVirtualTarget + " ---\n" + virtualRefContent + "\n--- End of " + normalizedVirtualTarget + " ---\n")
      return _
    }

    var resolvedPath = String(new java.io.File(templateDir, cleanTarget).getCanonicalPath())
    if (Object.prototype.hasOwnProperty.call(includedPaths, resolvedPath)) return _
    includedPaths[resolvedPath] = true
    try {
      if (!io.fileExists(resolvedPath) || io.fileInfo(resolvedPath).isFile !== true) return _
      var refContent = io.readFileString(resolvedPath)
      self._recordSkillReference(references, seen, { type: "file", path: resolvedPath, relativePath: cleanTarget })
      includeBlocks.push("\n\n--- Skill reference from " + cleanTarget + " ---\n" + refContent + "\n--- End of " + cleanTarget + " ---\n")
    } catch(ignoreSkillRefError) { }
    return _
  })

  if (includeBlocks.length > 0) text += includeBlocks.join("")
  result.text = text
  result.references = references
  return result
}

MiniUtilsTool.prototype._serializeSkillArgv = function(argv) {
  if (!isArray(argv) || argv.length === 0) return ""
  return argv.map(function(value) {
    var token = String(value)
    if (token.length === 0) return "\"\""
    if (/[\\\s"]/.test(token)) {
      return "\"" + token.replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + "\""
    }
    return token
  }).join(" ")
}

MiniUtilsTool.prototype._listEntries = function(baseDir, options) {
  var self = this
  options = options || {}
  var includeHidden = options.includeHidden === true
  var recursive = options.recursive === true
  var results = []
  var seen = {}

  var pushEntry = function(fullPath) {
    if (!isString(fullPath)) return
    if (!self._withinRoot(fullPath)) return
    if (fullPath === baseDir) return
    if (seen[fullPath]) return
    var fileObj = new java.io.File(fullPath)
    var fileName = String(fileObj.getName())
    if (!includeHidden && (fileObj.isHidden() || fileName.charAt(0) === ".")) return
    var info = io.fileInfo(fullPath)
    if (isUnDef(info)) return
    info.filename = isString(info.filename) ? info.filename : fileName
    info.lastModified = isDef(info.lastModified) ? new Date(info.lastModified) : __
    info.createTime = isDef(info.createTime) ? new Date(info.createTime) : __
    info.lastAccess = isDef(info.lastAccess) ? new Date(info.lastAccess) : __
    info.relativePath = self._toRelative(info.canonicalPath || fullPath)
    info.isDirectory = info.isDirectory === true
    info.isFile = info.isFile === true
    info.hidden = fileObj.isHidden()
    delete info.canonicalPath
    delete info.filepath
    delete info.path
    results.push(info)
    seen[fullPath] = true
  }

  var _traverse = function(value, ctxDir) {
    if (isUnDef(value)) return
    if (isArray(value)) {
      value.forEach(function(entry) {
        _traverse(entry, ctxDir)
      })
      return
    }
    if (isString(value)) {
      try {
        var fromString = new java.io.File(isString(ctxDir) ? ctxDir : baseDir, value)
        var resolved = String(fromString.getCanonicalPath())
        pushEntry(resolved)
      } catch (innerErr) {
      }
      return
    }
    if (isMap(value)) {
      var resolved
      var candidate = value.canonicalPath || value.filepath || value.path
      if (isString(candidate)) {
        try {
          var fileCandidate = new java.io.File(candidate)
          if (!fileCandidate.isAbsolute()) {
            fileCandidate = new java.io.File(isString(ctxDir) ? ctxDir : baseDir, candidate)
          }
          resolved = String(fileCandidate.getCanonicalPath())
          pushEntry(resolved)
        } catch (innerErr2) {
          resolved = null
        }
      } else if (isString(value.filename)) {
        try {
          var parentDir = value.directory
          var baseForName
          if (isString(parentDir)) {
            baseForName = new java.io.File(parentDir)
            if (!baseForName.isAbsolute()) {
              baseForName = new java.io.File(isString(ctxDir) ? ctxDir : baseDir, parentDir)
            }
          } else {
            baseForName = new java.io.File(isString(ctxDir) ? ctxDir : baseDir)
          }
          resolved = String(new java.io.File(baseForName, value.filename).getCanonicalPath())
          pushEntry(resolved)
        } catch (innerErr3) {
          resolved = null
        }
      }

      var childContext = resolved
      if (!isString(childContext) || value.isDirectory !== true) {
        childContext = ctxDir
      }
      self._listNestedKeys.forEach(function(key) {
        if (isDef(value[key])) {
          _traverse(value[key], childContext)
        }
      })
    }
  }

  var fallbackEnumerate = function(currentDir) {
    try {
      var listed = io.listFiles(currentDir).files || []
      if (isArray(listed)) {
        listed.forEach(function(entry) {
          try {
            var childFile = new java.io.File(currentDir, entry)
            var childPath = String(childFile.getCanonicalPath())
            pushEntry(childPath)
            if (recursive) {
              var childInfo = io.fileInfo(childPath)
              if (isDef(childInfo) && childInfo.isDirectory === true) {
                fallbackEnumerate(childPath)
              }
            }
          } catch (innerErr) {
          }
        })
      } else {
        _traverse(listed, currentDir)
      }
    } catch (innerErr2) {
    }
  }

  var raw
  try {
    raw = recursive ? listFilesRecursive(baseDir) : io.listFiles(baseDir).files
  } catch (e) {
    raw = null
  }

  if (isUnDef(raw)) {
    fallbackEnumerate(baseDir)
  } else {
    _traverse(raw, baseDir)
    if (results.length === 0) {
      fallbackEnumerate(baseDir)
    }
  }

  results.sort(function(a, b) {
    var left = isDef(a.relativePath) ? String(a.relativePath) : String(a.path || a.filename || "")
    var right = isDef(b.relativePath) ? String(b.relativePath) : String(b.path || b.filename || "")
    return left.localeCompare(right)
  })

  return results
}

/**
 * <odoc>
 * <key>MiniUtilsTool.readFile(params) : Object</key>
 * Reads the content of a file specified by the `path` parameter.
 * The `params` object can have the following properties:
 * - `path` (string, required): The relative or absolute path to the file to be read.
 * - `encoding` (string, optional): The character encoding to use when reading the file. Defaults to `"utf-8"`.
 * - `byteStart` (number, optional): Zero-based byte offset to start reading from.
 * - `byteEnd` (number, optional): Zero-based byte offset to stop reading (inclusive).
 * - `byteLength` (number, optional): Number of bytes to read from `byteStart`.
 * - `lineStart` (number, optional): One-based line number to start reading from.
 * - `lineEnd` (number, optional): One-based line number to stop reading (inclusive).
 * - `maxLines` (number, optional): Maximum number of lines to read (useful with `lineStart`).
 * - `lineSeparator` (string, optional): Line separator to use when joining output. Defaults to "\n".
 * - `countLines` (boolean, optional): If true, returns the total line count without loading full contents.
 *  
 * Returns an object containing file details and content on success, or an error message string on failure.
 * The returned object includes:
 * - `path`: The canonical path of the file.
 * - `relativePath`: The path of the file relative to the root directory.
 * - `encoding`: The encoding used to read the file.
 * - `content`: The content of the file as a string.
 * - Other file metadata such as size, last modified date, etc.
 * </odoc>
 */
MiniUtilsTool.prototype.readFile = function(params) {
  params = params || {}
  if (isUnDef(params.path)) return "[ERROR] path is required"
  try {
    this._ensureInitialized()
    var filePath = this._resolve(params.path)
    if (!io.fileExists(filePath)) {
      return "[ERROR] File not found: " + params.path
    }
    var details = io.fileInfo(filePath)
    if (isUnDef(details) || details.isFile !== true) {
      return "[ERROR] Path is not a file: " + params.path
    }
    var encoding = params.encoding || "utf-8"
    var hasByteRange = isDef(params.byteStart) || isDef(params.byteEnd) || isDef(params.byteLength)
    var hasLineRange = isDef(params.lineStart) || isDef(params.lineEnd) || isDef(params.maxLines)
    var shouldCountLines = params.countLines === true

    if (hasByteRange && hasLineRange) {
      return "[ERROR] byte range and line range options are mutually exclusive"
    }
    if (hasByteRange && shouldCountLines) {
      return "[ERROR] countLines cannot be combined with byte range options"
    }

    var content = ""
    var byteDetails = null
    var lineDetails = null
    var totalLines = null

    if (hasByteRange) {
      var byteStart = isDef(params.byteStart) ? Number(params.byteStart) : 0
      var byteEnd = isDef(params.byteEnd) ? Number(params.byteEnd) : __
      var byteLength = isDef(params.byteLength) ? Number(params.byteLength) : __

      if (isNaN(byteStart) || byteStart < 0) return "[ERROR] byteStart must be >= 0"
      if (isDef(byteEnd) && (isNaN(byteEnd) || byteEnd < 0)) return "[ERROR] byteEnd must be >= 0"
      if (isDef(byteLength) && (isNaN(byteLength) || byteLength < 0)) return "[ERROR] byteLength must be >= 0"
      if (isDef(byteEnd) && byteEnd < byteStart) return "[ERROR] byteEnd must be >= byteStart"

      var raf = io.randomAccessFile(filePath, "r")
      var fileSize = Number(raf.length())
      if (byteStart > fileSize) byteStart = fileSize

      var computedEnd = null
      if (isDef(byteLength)) {
        computedEnd = byteStart + byteLength - 1
      } else if (isDef(byteEnd)) {
        computedEnd = byteEnd
      } else {
        computedEnd = fileSize > 0 ? fileSize - 1 : 0
      }
      if (computedEnd >= fileSize) computedEnd = fileSize > 0 ? fileSize - 1 : 0

      var readLength = (fileSize === 0 || computedEnd < byteStart) ? 0 : (computedEnd - byteStart + 1)
      var bytesRead = 0
      if (readLength > 0) {
        raf.seek(byteStart)
        var buffer = java.lang.reflect.Array.newInstance(java.lang.Byte.TYPE, readLength)
        while (bytesRead < readLength) {
          var read = raf.read(buffer, bytesRead, readLength - bytesRead)
          if (read === -1) break
          bytesRead += read
        }
        content = String(new java.lang.String(buffer, 0, bytesRead, encoding))
      }
      raf.close()

      byteDetails = {
        byteStart: byteStart,
        byteEnd: bytesRead === 0 ? byteStart : (byteStart + bytesRead - 1),
        bytesRead: bytesRead
      }
    } else if (hasLineRange) {
      var lineStart = isDef(params.lineStart) ? Number(params.lineStart) : 1
      var lineEnd = isDef(params.lineEnd) ? Number(params.lineEnd) : __
      var maxLines = isDef(params.maxLines) ? Number(params.maxLines) : null
      var lineSeparator = isDef(params.lineSeparator) ? String(params.lineSeparator) : "\n"

      if (isNaN(lineStart) || lineStart < 1) return "[ERROR] lineStart must be >= 1"
      if (isDef(lineEnd) && (isNaN(lineEnd) || lineEnd < 1)) return "[ERROR] lineEnd must be >= 1"
      if (isDef(maxLines) && (isNaN(maxLines) || maxLines < 0)) return "[ERROR] maxLines must be >= 0"
      if (isDef(lineEnd) && lineEnd < lineStart) return "[ERROR] lineEnd must be >= lineStart"

      var lineNo = 0
      var lines = []
      var countAll = 0
      var reader = new java.io.BufferedReader(
        new java.io.InputStreamReader(new java.io.FileInputStream(filePath), encoding)
      )
      try {
        while (true) {
          var line = reader.readLine()
          if (line === null) break
          lineNo++
          countAll++

          var inRange = lineNo >= lineStart && (!isDef(lineEnd) || lineNo <= lineEnd)
          if (inRange) {
            if (!isDef(maxLines) || lines.length < maxLines) {
              lines.push(String(line))
            }
          }

          if (!shouldCountLines) {
            if (isDef(lineEnd) && lineNo >= lineEnd) break
            if (isDef(maxLines) && lines.length >= maxLines && lineNo >= lineStart) break
          }
        }
      } finally {
        try { reader.close() } catch (e) {}
      }

      content = lines.join(lineSeparator)
      lineDetails = {
        lineStart: lineStart,
        lineEnd: lines.length === 0 ? lineStart - 1 : (lineStart + lines.length - 1),
        linesRead: lines.length,
        lineSeparator: lineSeparator
      }

      if (shouldCountLines) {
        totalLines = countAll
      }
    } else {
      if (shouldCountLines) {
        var reader2 = new java.io.BufferedReader(
          new java.io.InputStreamReader(new java.io.FileInputStream(filePath), encoding)
        )
        var count2 = 0
        try {
          while (reader2.readLine() !== null) {
            count2++
          }
        } finally {
          try { reader2.close() } catch (e) {}
        }
        totalLines = count2
      } else {
        content = io.readFileString(filePath, encoding)
      }
    }

    if (params.compact === true) {
      var compactResult = {
        relativePath: this._toRelative(details.canonicalPath || filePath),
        size: details.size,
        encoding: encoding,
        content: content
      }
      if (totalLines !== null) {
        compactResult.linesTotal = totalLines
      }
      if (byteDetails) {
        compactResult.byteStart = byteDetails.byteStart
        compactResult.byteEnd = byteDetails.byteEnd
        compactResult.bytesRead = byteDetails.bytesRead
      }
      if (lineDetails) {
        compactResult.lineStart = lineDetails.lineStart
        compactResult.lineEnd = lineDetails.lineEnd
        compactResult.linesRead = lineDetails.linesRead
        compactResult.lineSeparator = lineDetails.lineSeparator
      }
      return compactResult
    }

    details.path = isString(details.canonicalPath) ? details.canonicalPath : filePath
    details.relativePath = this._toRelative(details.path)
    details.encoding = encoding
    details.content = content
    if (totalLines !== null) {
      details.linesTotal = totalLines
    }
    if (byteDetails) {
      details.byteStart = byteDetails.byteStart
      details.byteEnd = byteDetails.byteEnd
      details.bytesRead = byteDetails.bytesRead
    }
    if (lineDetails) {
      details.lineStart = lineDetails.lineStart
      details.lineEnd = lineDetails.lineEnd
      details.linesRead = lineDetails.linesRead
      details.lineSeparator = lineDetails.lineSeparator
    }
    return details
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.listDirectory(params) : Array</key>
 * Lists the contents of a directory specified by the `path` parameter.
 * The `params` object can have the following properties:
 * - `path` (string, optional): The relative or absolute path to the directory to be listed. Defaults to the root directory (`"."`).
 * - `includeHidden` (boolean, optional): If set to `true`, includes hidden files and directories in the listing. Defaults to `false`.
 * - `recursive` (boolean, optional): If set to `true`, lists contents recursively. Defaults to `false`.
 * 
 * Returns an array of objects representing the files and directories within the specified directory on success, or an error message string on failure.
 * Each object in the returned array includes:
 * - `relativePath`: The path of the file or directory relative to the root directory.
 * - Other file metadata such as size, last modified date, type (file or directory), etc.
 * </odoc>
 */
MiniUtilsTool.prototype.listDirectory = function(params) {
  params = params || {}
  try {
    this._ensureInitialized()
    var dirPath = this._resolve(isDef(params.path) ? params.path : ".")
    var info = io.fileInfo(dirPath)
    if (isUnDef(info) || info.isDirectory !== true) {
      return "[ERROR] Path is not a directory: " + (isDef(params.path) ? params.path : ".")
    }
    var includeHidden = params.includeHidden === true
    var recursive = params.recursive === true
    var entries = this._listEntries(dirPath, {
      recursive: recursive,
      includeHidden: includeHidden
    })

    if (params.compact === true) {
      var fileCount = 0
      var dirCount = 0
      var compactEntries = entries.map(function(entry) {
        if (entry.isDirectory) dirCount++
        if (entry.isFile) fileCount++
        return {
          name: entry.filename,
          relativePath: entry.relativePath,
          isDirectory: entry.isDirectory,
          isFile: entry.isFile,
          size: entry.size
        }
      })
      return {
        count: entries.length,
        files: fileCount,
        directories: dirCount,
        items: compactEntries
      }
    }

    return entries
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

MiniUtilsTool.prototype.globFiles = function(params) {
  params = params || {}
  if (isUnDef(params.pattern)) return "[ERROR] pattern is required"
  try {
    this._ensureInitialized()
    var basePath = this._resolve(isDef(params.path) ? params.path : ".")
    var info = io.fileInfo(basePath)
    if (isUnDef(info)) {
      return "[ERROR] Path not found: " + (isDef(params.path) ? params.path : ".")
    }

    var matcher = this._createGlobMatcher(params.pattern)
    if (!matcher) return "[ERROR] Invalid glob pattern: " + params.pattern

    var includeHidden = params.includeHidden === true
    var recursive = params.recursive !== false
    var entries = []

    if (info.isFile === true) {
      var entryInfo = io.fileInfo(basePath)
      if (isDef(entryInfo)) {
        entryInfo.filename = isString(entryInfo.filename) ? entryInfo.filename : new java.io.File(basePath).getName()
        entryInfo.relativePath = this._toRelative(entryInfo.canonicalPath || basePath)
        entryInfo.isDirectory = entryInfo.isDirectory === true
        entryInfo.isFile = entryInfo.isFile === true
        entries.push(entryInfo)
      }
    } else if (info.isDirectory === true) {
      entries = this._listEntries(basePath, {
        recursive: recursive,
        includeHidden: includeHidden
      })
    }

    var baseRelative = this._toRelative(basePath)
    if (baseRelative === ".") baseRelative = ""
    var sep = this._separator
    var altMatcher = null
    if (isString(params.pattern) && params.pattern.indexOf("**/") === 0) {
      altMatcher = this._createGlobMatcher(params.pattern.substring(3))
    }
    var filtered = entries.filter(function(entry) {
      var relPath = entry.relativePath || entry.filename || ""
      var matchPath = relPath
      if (baseRelative.length > 0 && matchPath.indexOf(baseRelative + sep) === 0) {
        matchPath = matchPath.substring(baseRelative.length + sep.length)
      }
      try {
        var pathObj = java.nio.file.Paths.get(matchPath)
        if (matcher.matches(pathObj)) return true
        if (altMatcher) return altMatcher.matches(pathObj)
        return false
      } catch (e) {
        return false
      }
    })

    if (params.compact === true) {
      var fileCount = 0
      var dirCount = 0
      var compactEntries = filtered.map(function(entry) {
        if (entry.isDirectory) dirCount++
        if (entry.isFile) fileCount++
        return {
          name: entry.filename,
          relativePath: entry.relativePath,
          isDirectory: entry.isDirectory,
          isFile: entry.isFile,
          size: entry.size
        }
      })
      return {
        count: filtered.length,
        files: fileCount,
        directories: dirCount,
        items: compactEntries
      }
    }

    return filtered
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

MiniUtilsTool.prototype._collectFiles = function(startPath, recursive) {
  var entries = this._listEntries(startPath, { recursive: recursive, includeHidden: true })
  var files = []
  var self = this
  entries.forEach(function(entry) {
    if (entry.isDirectory === true) return
    try {
      var absolute = self._resolve(entry.relativePath)
      files.push({
        filepath: absolute,
        relativePath: entry.relativePath
      })
    } catch (err) {
    }
  })
  return files
}

MiniUtilsTool.prototype._isMarkdownPath = function(pathValue) {
  if (!isString(pathValue)) return false
  return pathValue.toLowerCase().endsWith(".md")
}

MiniUtilsTool.prototype._collectMarkdownFiles = function(startPath, recursive, includeHidden) {
  var files = []
  var seen = {}
  var self = this
  var pushFile = function(filePath) {
    if (!isString(filePath)) return
    if (seen[filePath]) return
    var info = io.fileInfo(filePath)
    if (isUnDef(info) || info.isFile !== true) return
    var relativePath = self._toRelative(info.canonicalPath || filePath)
    if (!self._isMarkdownPath(relativePath)) return
    seen[filePath] = true
    files.push({
      filepath: filePath,
      relativePath: relativePath,
      size: info.size,
      lastModified: isDef(info.lastModified) ? new Date(info.lastModified) : __
    })
  }

  var info = io.fileInfo(startPath)
  if (isUnDef(info)) return files
  if (info.isFile === true) {
    pushFile(startPath)
    return files
  }
  if (info.isDirectory !== true) return files

  var entries = this._listEntries(startPath, {
    recursive: recursive === true,
    includeHidden: includeHidden === true
  })
  entries.forEach(function(entry) {
    if (entry.isFile !== true) return
    if (!self._isMarkdownPath(entry.relativePath)) return
    try {
      pushFile(self._resolve(entry.relativePath))
    } catch (ignoreResolveError) {
    }
  })
  return files
}

/**
 * <odoc>
 * <key>MiniUtilsTool.searchContent(params) : Array</key>
 * Searches for a specified pattern within the content of files starting from a given directory.
 * The `params` object can have the following properties:
 * - `pattern` (string, required): The pattern to search for within the file contents.
 * - `path` (string, optional): The relative or absolute path to the directory or file to start the search from. Defaults to the root directory (`"."`).
 * - `regex` (boolean, optional): If set to `true`, treats the pattern as a regular expression. Defaults to `false`.
 * - `caseSensitive` (boolean, optional): If set to `true`, makes the search case-sensitive. Defaults to `false`.
 * - `recursive` (boolean, optional): If set to `true`, searches files recursively in subdirectories. Defaults to `true`.
 * - `maxResults` (number, optional): The maximum number of results to return. Defaults to `0` (no limit).
 * 
 * Returns an array of objects representing the search results on success, or an error message string on failure.
 * Each object in the returned array includes:
 * - `path`: The canonical path of the file where the pattern was found.
 * - `relativePath`: The path of the file relative to the root directory.
 * - `line`: The line number where the pattern was found.
 * - `preview`: A preview of the line containing the pattern.
 * </odoc>
 */
MiniUtilsTool.prototype.searchContent = function(params) {
  params = params || {}
  if (isUnDef(params.pattern)) return "[ERROR] pattern is required"
  try {
    this._ensureInitialized()
    if (!isString(params.pattern)) {
      return "[ERROR] pattern is required"
    }
    var startPath = this._resolve(isDef(params.path) ? params.path : ".")
    var searchInfo = io.fileInfo(startPath)
    if (isUnDef(searchInfo)) {
      return "[ERROR] Path not found: " + (isDef(params.path) ? params.path : ".")
    }

    var regexMode = params.regex === true
    var caseSensitive = params.caseSensitive === true
    var recursive = params.recursive !== false
    var maxResults = Number(params.maxResults || 0)
    var collected = 0
    var matcher = null
    if (regexMode) {
      var flags = caseSensitive ? "g" : "gi"
      matcher = new RegExp(params.pattern, flags)
    }
    var patternValue = caseSensitive ? params.pattern : String(params.pattern).toLowerCase()
    var files = []
    if (searchInfo.isFile === true) {
      files.push({
        filepath: startPath,
        relativePath: this._toRelative(startPath)
      })
    }
    if (searchInfo.isDirectory === true) {
      files = files.concat(this._collectFiles(startPath, recursive))
    }

    var results = []
    var self = this
    files.some(function(entry) {
      if (maxResults > 0 && collected >= maxResults) return true
      try {
        var content = io.readFileString(entry.filepath)
        var lines = content.split(/\r?\n/)
        for (var i = 0; i < lines.length; i++) {
          if (maxResults > 0 && collected >= maxResults) break
          var line = lines[i]
          var matched = false
          if (regexMode) {
            matcher.lastIndex = 0
            matched = matcher.test(line)
          } else {
            var haystack = caseSensitive ? line : line.toLowerCase()
            matched = haystack.indexOf(patternValue) >= 0
          }
          if (matched) {
            collected++
            var preview = line
            if (params.compact === true && preview.length > 100) {
              preview = preview.substring(0, 100) + "..."
            }
            results.push({
              path: entry.filepath,
              relativePath: entry.relativePath,
              line: i + 1,
              preview: preview
            })
            break
          }
        }
      } catch (err) {
        results.push({ error: err })
      }
      return maxResults > 0 && collected >= maxResults
    })

    var filtered = results.filter(function(r) {
      return r != null && isMap(r)
    })

    if (params.compact === true) {
      return {
        count: filtered.length,
        matches: filtered
      }
    }

    return filtered
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.markdownFiles(params) : Object|Array</key>
 * Provides markdown-focused filesystem operations limited to `*.md` files.
 * The `params` object supports:
 * - `operation` (string, optional): `list` (default), `search`, or `read`.
 * - `path` (string, optional): Base directory or markdown file path. Defaults to `"."`.
 * - `recursive` (boolean, optional): Recursively scan directories for `list`/`search`. Defaults to `true`.
 * - `includeHidden` (boolean, optional): Include hidden files/directories during scans. Defaults to `false`.
 * - `pattern` (string, required for `search`): Text/regex pattern to find in markdown files.
 * - `regex` (boolean, optional): Treat search pattern as regular expression. Defaults to `false`.
 * - `caseSensitive` (boolean, optional): Case-sensitive search. Defaults to `false`.
 * - `maxResults` (number, optional): Maximum number of matches for `search`. Defaults to `0` (no limit).
 * - Read options for `read`: `encoding`, `lineStart`, `lineEnd`, `maxLines`, `lineSeparator`, `countLines`, `compact`.
 * </odoc>
 */
MiniUtilsTool.prototype.markdownFiles = function(params) {
  params = params || {}
  try {
    this._ensureInitialized()
    var operation = isString(params.operation) ? params.operation.toLowerCase().trim() : "list"
    var startPath = this._resolve(isDef(params.path) ? params.path : ".")
    var recursive = params.recursive !== false
    var includeHidden = params.includeHidden === true

    if (operation === "list") {
      var markdowns = this._collectMarkdownFiles(startPath, recursive, includeHidden)
      markdowns.sort(function(a, b) { return String(a.relativePath).localeCompare(String(b.relativePath)) })

      if (params.compact === true) {
        return {
          count: markdowns.length,
          files: markdowns.map(function(entry) { return entry.relativePath })
        }
      }
      return markdowns
    }

    if (operation === "search") {
      if (!isString(params.pattern) || params.pattern.length === 0) return "[ERROR] pattern is required for markdown search"
      var files = this._collectMarkdownFiles(startPath, recursive, includeHidden)
      var regexMode = params.regex === true
      var caseSensitive = params.caseSensitive === true
      var maxResults = Number(params.maxResults || 0)
      var matcher = regexMode ? new RegExp(params.pattern, caseSensitive ? "g" : "gi") : null
      var needle = caseSensitive ? params.pattern : String(params.pattern).toLowerCase()
      var results = []
      var totalMatches = 0

      files.some(function(entry) {
        if (maxResults > 0 && totalMatches >= maxResults) return true
        try {
          var content = io.readFileString(entry.filepath)
          var lines = String(content).split(/\r?\n/)
          for (var i = 0; i < lines.length; i++) {
            if (maxResults > 0 && totalMatches >= maxResults) break
            var line = lines[i]
            var matched = false
            if (regexMode) {
              matcher.lastIndex = 0
              matched = matcher.test(line)
            } else {
              var haystack = caseSensitive ? line : line.toLowerCase()
              matched = haystack.indexOf(needle) >= 0
            }
            if (matched) {
              totalMatches++
              results.push({
                relativePath: entry.relativePath,
                line: i + 1,
                preview: line
              })
            }
          }
        } catch (ignoreReadError) {
        }
        return maxResults > 0 && totalMatches >= maxResults
      })

      if (params.compact === true) {
        return { count: results.length, matches: results }
      }
      return results
    }

    if (operation === "read" || operation === "get" || operation === "view" || operation === "cat") {
      if (isUnDef(params.path)) return "[ERROR] path is required for markdown read"
      var targetRelative = this._toRelative(startPath)
      if (!this._isMarkdownPath(targetRelative)) {
        return "[ERROR] markdown read only supports *.md files"
      }
      return this.readFile(params)
    }

    return "[ERROR] Unknown markdown operation: " + operation
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.skills(params) : Object|Array</key>
 * Discovers and uses installed skills from configured skill roots.
 * The `params` object supports:
 * - `operation` (string, optional): `list` (default), `search`, `read`, `render`, or `invoke`.
 * - `name` (string, required for `read`/`render`/`invoke`): Skill name.
 * - `query` (string, required for `search`): Query string to match skill metadata.
 * - `args` (string, optional): Raw arguments used by `render`.
 * - `argv` (array, optional): Explicit argument list for `render` (overrides parsed `args`).
 * - `includeHidden` (boolean, optional): Include hidden entries for discovery.
 * - `compact` (boolean, optional): Return compact payload.
 * </odoc>
 */
MiniUtilsTool.prototype.skills = function(params) {
  params = params || {}
  try {
    this._ensureInitialized()
    var op = isString(params.operation) ? params.operation.toLowerCase().trim() : "list"
    if (op === "get") op = "read"
    if (op === "view") op = "read"
    if (op === "cat") op = "read"
    if (op === "use") op = "render"
    if (op === "expand") op = "render"
    if (op === "apply") op = "render"
    if (op === "run") op = "invoke"

    var listParams = {
      includeHidden: params.includeHidden === true
    }
    if (op === "search") {
      if (!isString(params.query) || params.query.trim().length === 0) return "[ERROR] query is required for search"
      listParams.query = params.query
    }

    if (op === "list" || op === "search") {
      var skills = this._listSkills(listParams)
      if (params.compact === true) {
        return {
          count : skills.length,
          skills: skills.map(function(entry) { return entry.name })
        }
      }
      return {
        count : skills.length,
        skills: skills.map(function(entry) {
          return {
            name       : entry.name,
            sourceType : entry.sourceType,
            skillFormat: entry.skillFormat,
            description: entry.description,
            relativePath: entry.relativePath
          }
        })
      }
    }

    if (op === "read" || op === "render" || op === "invoke") {
      if (!isString(params.name) || params.name.trim().length === 0) return "[ERROR] name is required"
      var requestedName = params.name.trim().toLowerCase()
      var discovered = this._listSkills({ includeHidden: params.includeHidden === true })
      var selected = __
      for (var i = 0; i < discovered.length; i++) {
        if (discovered[i].name === requestedName) {
          selected = discovered[i]
          break
        }
      }
      if (isUnDef(selected)) return "[ERROR] Skill not found: " + params.name

      var loadedDoc = __miniALoadSkillTemplateDocument(selected.templatePath)
      if (!isObject(loadedDoc)) return "[ERROR] Failed to parse skill template: " + selected.name
      var content = isString(loadedDoc.rawContent) ? loadedDoc.rawContent : io.readFileString(selected.templatePath)
      var processedContent = isString(loadedDoc.bodyTemplate) ? loadedDoc.bodyTemplate : ""
      var referenced = this._preprocessSkillTemplateReferences(processedContent, selected, loadedDoc)
      var referencedFiles = isMap(referenced) && isArray(referenced.references) ? referenced.references : []
      if (op === "read") {
        if (params.compact === true) {
          return {
            name  : selected.name,
            skillFormat: selected.skillFormat,
            templatePath: selected.templatePath,
            referencedFiles: referencedFiles,
            content: content
          }
        }
        return {
          name        : selected.name,
          sourceType  : selected.sourceType,
          skillFormat : selected.skillFormat,
          description : selected.description,
          relativePath: selected.relativePath,
          templatePath: selected.templatePath,
          referencedFiles: referencedFiles,
          contentLength: isString(content) ? content.length : 0,
          content     : content
        }
      }

      var parsedArgs
      if (isArray(params.argv)) {
        var argv = params.argv.map(function(value) { return String(value) })
        var rawFromArgv = this._serializeSkillArgv(argv)
        parsedArgs = {
          ok  : true,
          raw : isString(params.args) ? params.args : rawFromArgv,
          argv: argv,
          argc: argv.length
        }
      } else {
        parsedArgs = this._parseSkillArgs(isString(params.args) ? params.args : "")
      }
      if (!isMap(parsedArgs) || parsedArgs.ok !== true) {
        return "[ERROR] " + (isMap(parsedArgs) && isString(parsedArgs.error) ? parsedArgs.error : "Invalid skill arguments")
      }

      var renderedTemplate = isMap(referenced) && isString(referenced.text) ? referenced.text : processedContent
      var rendered = this._renderSkillTemplate(renderedTemplate, parsedArgs)
      var invocationSuffix = isString(parsedArgs.raw) && parsedArgs.raw.length > 0 ? " " + parsedArgs.raw : ""
      var skillInvocation = "$" + selected.name + invocationSuffix
      var slashInvocation = "/" + selected.name + invocationSuffix
      if (params.compact === true) {
        if (op === "invoke") {
          return {
            name      : selected.name,
            invocation: skillInvocation,
            templatePath: selected.templatePath,
            referencedFiles: referencedFiles,
            rendered  : rendered
          }
        }
        return {
          name           : selected.name,
          templatePath   : selected.templatePath,
          referencedFiles: referencedFiles,
          rendered       : rendered
        }
      }
      return {
        name        : selected.name,
        sourceType  : selected.sourceType,
        skillFormat : selected.skillFormat,
        description : selected.description,
        relativePath: selected.relativePath,
        templatePath: selected.templatePath,
        referencedFiles: referencedFiles,
        args        : {
          raw : parsedArgs.raw,
          argv: parsedArgs.argv,
          argc: parsedArgs.argc
        },
        rendered     : rendered,
        invocation   : skillInvocation,
        slashCommand : slashInvocation
      }
    }

    return "[ERROR] Unknown skills operation: " + op
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.wiki(params) : Object|String</key>
 * Interact with the wiki knowledge base configured in the agent.
 * The `params` object supports:
 * - `operation` (string): list, read, search, write, delete, lint.
 * - `path` (string): Page path for read/write operations.
 * - `query` (string): Search query for operation=search.
 * - `content` (string): Raw markdown content for operation=write.
 * - `compact` (boolean): Return compact output.
 * </odoc>
 */
MiniUtilsTool.prototype.wiki = function(params) {
  params = params || {}
  try {
    this._ensureInitialized()
    var wm = isObject(this._wikiManager) ? this._wikiManager : __
    if (!isObject(wm)) return "[ERROR] Wiki is not configured. Set usewiki=true and wikiroot (or wikibackend=s3) when starting the agent."
    var op = isString(params.operation) ? params.operation.toLowerCase().trim()
      : (isString(params.op) ? params.op.toLowerCase().trim() : "list")
    if (op === "get" || op === "view" || op === "cat") op = "read"
    if (op === "find") op = "search"
    if (op === "validate" || op === "check") op = "lint"
    if (op === "save" || op === "put" || op === "create" || op === "update") op = "write"

    if (op === "list") {
      var prefix = isString(params.path) ? params.path : ""
      var pages = wm.list(prefix)
      if (params.compact === true) return { count: pages.length, pages: pages }
      return { count: pages.length, pages: pages }
    }

    if (op === "read") {
      if (!isString(params.path) || params.path.trim().length === 0) return "[ERROR] path is required for read"
      var page = wm.read(params.path.trim())
      if (!isObject(page)) return "[ERROR] Page not found: " + params.path
      if (params.compact === true) return { path: page.path, title: isString(page.meta.title) ? page.meta.title : page.path, body: page.body }
      return page
    }

    if (op === "search") {
      if (!isString(params.query) || params.query.trim().length === 0) return "[ERROR] query is required for search"
      var hits = wm.search(params.query.trim(), { limit: isNumber(params.limit) ? params.limit : 20 })
      return { count: hits.length, results: hits }
    }

    if (op === "write") {
      if (!isString(params.path) || params.path.trim().length === 0) return "[ERROR] path is required for write"
      if (!isString(params.content) || params.content.trim().length === 0) return "[ERROR] content is required for write"
      var wResult = wm.write(params.path.trim(), params.content)
      return isObject(wResult) ? wResult : { ok: false, error: String(wResult) }
    }

    if (op === "lint") {
      var lintOpts = {}
      if (isNumber(params.staleDays)) lintOpts.staleDays = params.staleDays
      var lintResult = wm.lint(__, lintOpts)
      if (params.compact === true) return lintResult.summary
      return lintResult
    }

    if (op === "delete" || op === "remove" || op === "rm") {
      if (!isString(params.path) || params.path.trim().length === 0) return "[ERROR] path is required for delete"
      var dResult = wm.delete(params.path.trim())
      return isObject(dResult) ? dResult : { ok: false, error: String(dResult) }
    }

    if (op === "init") {
      var iResult = wm.init()
      return isObject(iResult) ? iResult : { ok: false, error: String(iResult) }
    }

    return "[ERROR] Unknown wiki operation: " + op + ". Use list, read, search, write, delete, lint, init."
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.getFileInfo(params) : Object</key>
 * Retrieves information about a file or directory specified by the `path` parameter.
 * The `params` object can have the following properties:
 * - `path` (string, required): The relative or absolute path to the file or directory.
 * 
 * Returns an object containing file or directory details on success, or an error message string on failure.
 * The returned object includes:
 * - `path`: The canonical path of the file or directory.
 * - `relativePath`: The path of the file or directory relative to the root directory.
 * - Other file metadata such as size, type (file or directory), last modified date, etc.
 * </odoc>
 */
MiniUtilsTool.prototype.getFileInfo = function(params) {
  params = params || {}
  if (isUnDef(params.path)) return "[ERROR] path is required"
  try {
    this._ensureInitialized()
    var filePath = this._resolve(params.path)
    if (!io.fileExists(filePath)) {
      return "[ERROR] Path not found: " + params.path
    }
    var info = io.fileInfo(filePath)
    if (isUnDef(info)) {
      return "[ERROR] Unable to retrieve file info: " + params.path
    }

    if (params.compact === true) {
      return {
        relativePath: this._toRelative(info.canonicalPath || filePath),
        isFile: info.isFile,
        isDirectory: info.isDirectory,
        size: info.size,
        lastModified: isDef(info.lastModified) ? new Date(info.lastModified) : __
      }
    }

    info.path = isString(info.canonicalPath) ? info.canonicalPath : filePath
    info.relativePath = this._toRelative(info.path)
    return info
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.writeFile(params) : Object</key>
 * Writes content to a file specified by the `path` parameter.
 * The `params` object can have the following properties:
 * - `path` (string, required): The relative or absolute path to the file to be written.
 * - `content` (string, required): The content to write to the file.
 * - `encoding` (string, optional): The character encoding to use when writing the file. Defaults to `"utf-8"`.
 * - `append` (boolean, optional): If set to `true`, appends the content to the file instead of overwriting it. Defaults to `false`.
 * - `createMissingDirs` (boolean, optional): If set to `true`, creates any missing parent directories. Defaults to `true`.
 * 
 * Returns an object containing file details on success, or an error message string on failure.
 * The returned object includes:
 * - `path`: The canonical path of the file.
 * - `relativePath`: The path of the file relative to the root directory.
 * - `encoding`: The encoding used to write the file.
 * - `contentLength`: The length of the content written to the file.
 * - `append`: Indicates whether the content was appended to the file.
 * - Other file metadata such as size, last modified date, etc.
 * </odoc>
 */
MiniUtilsTool.prototype.writeFile = function(params) {
  params = params || {}
  if (isUnDef(params.path)) return "[ERROR] path is required"
  if (isUnDef(params.content)) return "[ERROR] content is required"
  try {
    this._ensureInitialized()
    this._ensureWritable("write operations")
    var filePath = this._resolve(params.path)
    var targetFile = new java.io.File(filePath)
    var parent = targetFile.getParentFile()
    if (params.createMissingDirs !== false && parent !== null && !parent.exists()) {
      parent.mkdirs()
    }
    var encoding = params.encoding || "utf-8"
    io.writeFileString(filePath, params.content, encoding, params.append === true)
    var info = io.fileInfo(filePath)
    if (isDef(info)) {
      info.path = isString(info.canonicalPath) ? info.canonicalPath : filePath
      info.relativePath = this._toRelative(info.path)
      info.encoding = encoding
      info.contentLength = isString(params.content) ? params.content.length : 0
      info.append = params.append === true
      return info
    }
    return {
      path: filePath,
      relativePath: this._toRelative(filePath),
      size: isString(params.content) ? params.content.length : 0,
      encoding: encoding
    }
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

MiniUtilsTool.prototype.editFile = function(params) {
  params = params || {}
  if (isUnDef(params.path)) return "[ERROR] path is required"
  if (isUnDef(params.pattern)) return "[ERROR] pattern is required"
  if (isUnDef(params.replacement)) return "[ERROR] replacement is required"
  try {
    this._ensureInitialized()
    this._ensureWritable("edit operations")
    var filePath = this._resolve(params.path)
    if (!io.fileExists(filePath)) {
      return "[ERROR] File not found: " + params.path
    }
    var details = io.fileInfo(filePath)
    if (isUnDef(details) || details.isFile !== true) {
      return "[ERROR] Path is not a file: " + params.path
    }

    var encoding = params.encoding || "utf-8"
    var content = io.readFileString(filePath, encoding)
    var pattern = String(params.pattern)
    if (pattern.length === 0) return "[ERROR] pattern cannot be empty"
    var replacement = String(params.replacement)
    var caseSensitive = params.caseSensitive === true
    var maxReplacements = isDef(params.maxReplacements) ? Number(params.maxReplacements) : 0
    if (maxReplacements < 0 || isNaN(maxReplacements)) maxReplacements = 0

    var replacements = 0
    var resultText
    if (params.regex === true) {
      var flags = caseSensitive ? "g" : "gi"
      var regex = new RegExp(pattern, flags)
      resultText = String(content).replace(regex, function(match) {
        if (maxReplacements > 0 && replacements >= maxReplacements) return match
        replacements++
        return replacement
      })
    } else {
      var source = String(content)
      var needle = caseSensitive ? pattern : pattern.toLowerCase()
      var haystack = caseSensitive ? source : source.toLowerCase()
      var start = 0
      var output = ""
      while (true) {
        if (maxReplacements > 0 && replacements >= maxReplacements) break
        var idx = haystack.indexOf(needle, start)
        if (idx === -1) break
        output += source.substring(start, idx) + replacement
        start = idx + pattern.length
        replacements++
      }
      output += source.substring(start)
      resultText = output
    }

    if (params.requireMatch === true && replacements === 0) {
      return "[ERROR] No matches found for pattern: " + params.pattern
    }

    if (resultText !== content) {
      io.writeFileString(filePath, resultText, encoding, false)
    }

    return {
      path: filePath,
      relativePath: this._toRelative(filePath),
      encoding: encoding,
      replacements: replacements,
      changed: resultText !== content,
      contentLength: resultText.length
    }
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

MiniUtilsTool.prototype._deleteRecursive = function(targetPath) {
  var self = this
  var entries = this._listEntries(targetPath, { recursive: true, includeHidden: true })
  entries.sort(function(a, b) {
    var left = String(a.relativePath || "")
    var right = String(b.relativePath || "")
    return right.length - left.length
  })
  entries.forEach(function(entry) {
    try {
      var entryPath = self._resolve(entry.relativePath)
      io.rm(entryPath)
    } catch (err) {
    }
  })
  io.rm(targetPath)
}

/**
 * <odoc>
 * <key>MiniUtilsTool.deleteFile(params) : Object</key>
 * Deletes a file or directory specified by the `path` parameter.
 * The `params` object can have the following properties:
 * - `path` (string, required): The relative or absolute path to the file or directory to be deleted.
 * - `confirm` (boolean, required): Must be set to `true` to confirm the deletion operation.
 * - `recursive` (boolean, optional): If set to `true`, allows deletion of directories and their contents. Defaults to `false`.
 * 
 * Returns an object containing deletion details on success, or an error message string on failure.
 * The returned object includes:
 * - `path`: The canonical path of the deleted file or directory.
 * - `relativePath`: The path of the deleted file or directory relative to the root directory.
 * - `deleted`: A boolean indicating whether the deletion was successful.
 * - `type`: Indicates whether the deleted item was a `"file"` or `"directory"`.
 * </odoc>
 */
MiniUtilsTool.prototype.deleteFile = function(params) {
  params = params || {}
  if (isUnDef(params.path)) return "[ERROR] path is required"
  if (isUnDef(params.confirm)) return "[ERROR] confirm is required"
  try {
    this._ensureInitialized()
    this._ensureWritable("delete operations")
    if (params.confirm !== true) {
      return "[ERROR] Deletion blocked: confirm=true is required"
    }
    var targetPath = this._resolve(params.path)
    if (!io.fileExists(targetPath)) {
      return "[ERROR] Path not found: " + params.path
    }
    var info = io.fileInfo(targetPath)
    if (isUnDef(info)) {
      return "[ERROR] Unable to retrieve target info: " + params.path
    }
    if (info.isDirectory === true && params.recursive !== true) {
      return "[ERROR] Path is a directory. Set recursive=true to delete directories"
    }

    if (info.isDirectory === true) {
      this._deleteRecursive(targetPath)
    } else {
      io.rm(targetPath)
    }
    return {
      path: targetPath,
      relativePath: this._toRelative(targetPath),
      deleted: true,
      type: info.isDirectory === true ? "directory" : "file"
    }
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

MiniUtilsTool.prototype.filesystemQuery = function(params) {
  var payload = isObject(params) ? params : {}
  var opValue = payload.operation
  if (isUnDef(opValue) || !isString(opValue) || opValue.trim().length === 0) {
    return "[ERROR] operation parameter is required (use: read, list, search, glob, or info)"
  }
  var normalized = opValue.trim().toLowerCase()
  var map = {
    read       : "readFile",
    readfile   : "readFile",
    get        : "readFile",
    view       : "readFile",
    list       : "listDirectory",
    ls         : "listDirectory",
    listdirectory: "listDirectory",
    dir        : "listDirectory",
    search     : "searchContent",
    searchcontent: "searchContent",
    grep       : "searchContent",
    find       : "searchContent",
    glob       : "globFiles",
    info       : "getFileInfo",
    stat       : "getFileInfo",
    metadata   : "getFileInfo",
    getfileinfo: "getFileInfo"
  }
  var target = map[normalized]
  if (!target && isString(opValue) && isFunction(this[opValue])) target = opValue
  if (!target) {
    return "[ERROR] Unknown filesystem query operation: " + (isString(opValue) ? opValue : normalized)
  }

  var innerParams = {}
  for (var key in payload) {
    if (!Object.prototype.hasOwnProperty.call(payload, key)) continue
    if (key === "operation") continue
    innerParams[key] = payload[key]
  }

  try {
    var handler = this[target]
    if (!isFunction(handler)) {
      return "[ERROR] Unsupported filesystem query handler: " + target
    }
    return handler.call(this, innerParams)
  } catch (e) {
    return "[ERROR] " + (e && e.message ? e.message : String(e))
  }
}

MiniUtilsTool.prototype.filesystemModify = function(params) {
  var payload = isObject(params) ? params : {}
  var opValue = payload.operation
  if (!isString(opValue) || opValue.trim().length === 0) {
    return "[ERROR] operation is required"
  }
  var normalized = opValue.trim().toLowerCase()
  var map = {
    write     : "writeFile",
    writefile : "writeFile",
    save      : "writeFile",
    append    : "writeFile",
    edit      : "editFile",
    replace   : "editFile",
    delete    : "deleteFile",
    remove    : "deleteFile",
    rm        : "deleteFile",
    deletefile: "deleteFile"
  }
  var target = map[normalized]
  if (!target && isString(opValue) && isFunction(this[opValue])) target = opValue
  if (!target) {
    return "[ERROR] Unknown filesystem modify operation: " + opValue
  }

  var innerParams = {}
  for (var key in payload) {
    if (!Object.prototype.hasOwnProperty.call(payload, key)) continue
    if (key === "operation") continue
    innerParams[key] = payload[key]
  }
  if (normalized === "append" && innerParams.append !== true) {
    innerParams.append = true
  }

  try {
    var handler = this[target]
    if (!isFunction(handler)) {
      return "[ERROR] Unsupported filesystem modify handler: " + target
    }
    return handler.call(this, innerParams)
  } catch (e) {
    return "[ERROR] " + (e && e.message ? e.message : String(e))
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.mathematics(params) : Object</key>
 * Performs mathematical operations including calculations, statistics, unit conversions, and random number generation.
 * The `params` object can have the following properties:
 * - `operation` (string, required): The operation to perform (calculate, statistics, convert-unit, random).
 * - For calculate: `op` (add, subtract, multiply, divide, power, sqrt, abs, round), `values` (array of numbers), `precision` (optional)
 * - For statistics: `values` (array of numbers), `metrics` (optional array of: mean, median, min, max, sum, count)
 * - For convert-unit: `value` (number), `fromUnit` (string), `toUnit` (string), `precision` (optional)
 * - For random: `type` (integer, sequence, choice, boolean, hex), type-specific params (min/max, items, count, seed, etc.)
 * </odoc>
 */
MiniUtilsTool.prototype.mathematics = function(params) {
  params = params || {}
  var op = (params.operation || "calculate").toLowerCase()

  try {
    if (op === "calculate") {
      var mathOp = (params.op || "add").toLowerCase()
      var values = params.values || []
      if (!isArray(values) || values.length === 0) return "[ERROR] values array required"

      var ops = {
        add: function(v) { return v.reduce(function(a,b){return a+b}, 0) },
        subtract: function(v) { return v.reduce(function(a,b){return a-b}) },
        multiply: function(v) { return v.reduce(function(a,b){return a*b}, 1) },
        divide: function(v) { return v.reduce(function(a,b){if(b===0)throw"Division by zero";return a/b}) },
        power: function(v) { if(v.length!==2)throw"Power requires 2 values";return Math.pow(v[0],v[1]) },
        sqrt: function(v) { if(v.length!==1)throw"Sqrt requires 1 value";return Math.sqrt(v[0]) },
        abs: function(v) { if(v.length!==1)throw"Abs requires 1 value";return Math.abs(v[0]) },
        round: function(v) { if(v.length!==1)throw"Round requires 1 value";return Math.round(v[0]) }
      }

      if (!ops[mathOp]) return "[ERROR] Unknown operation: " + mathOp
      var result = ops[mathOp](values.map(Number))
      if (isDef(params.precision)) result = Number(result.toFixed(params.precision))
      return { operation: mathOp, values: values, result: result }

    } else if (op === "statistics") {
      var vals = (params.values || []).map(Number).sort(function(a,b){return a-b})
      if (vals.length === 0) return "[ERROR] values array required"

      var sum = vals.reduce(function(a,b){return a+b}, 0)
      var mean = sum / vals.length
      var n = vals.length
      var median = n % 2 === 0 ? (vals[n/2-1] + vals[n/2])/2 : vals[Math.floor(n/2)]

      var all = { count: n, sum: sum, mean: mean, median: median, min: vals[0], max: vals[n-1] }
      if (isDef(params.metrics) && isArray(params.metrics)) {
        var result = {}
        params.metrics.forEach(function(m) { if (all[m]) result[m] = all[m] })
        return result
      }
      return all

    } else if (op === "convert-unit" || op === "convert") {
      var value = Number(params.value)
      var from = String(params.fromUnit || "").toLowerCase()
      var to = String(params.toUnit || "").toLowerCase()

      var conversions = {
        m: 1, km: 1000, cm: 0.01, mm: 0.001, mi: 1609.344, ft: 0.3048, in: 0.0254,
        kg: 1, g: 0.001, lb: 0.453592, oz: 0.0283495,
        l: 1, ml: 0.001, gal: 3.78541
      }

      if (!conversions[from] || !conversions[to]) return "[ERROR] Unknown unit"
      var result = (value * conversions[from]) / conversions[to]
      if (isDef(params.precision)) result = Number(result.toFixed(params.precision))
      return { value: value, fromUnit: from, toUnit: to, result: result }

    } else if (op === "random") {
      var Random = java.util.Random
      var seed = params.seed
      var rng = isDef(seed) ? new Random(Number(seed)) : new Random()
      var type = (params.type || "integer").toLowerCase()

      if (type === "integer") {
        var min = Math.ceil(Number(params.min || 0))
        var max = Math.floor(Number(params.max || 100))
        if (min > max) return "[ERROR] min must be <= max"
        var range = max - min + 1
        var value = min + rng.nextInt(range)
        return { type: type, min: min, max: max, value: Number(value), seed: isDef(seed) ? Number(seed) : null }

      } else if (type === "sequence") {
        var start = Math.ceil(Number(params.start || 0))
        var end = Math.floor(Number(params.end || 10))
        if (start > end) return "[ERROR] start must be <= end"

        var seq = []
        for (var i = start; i <= end; i++) seq.push(i)
        for (var i = seq.length - 1; i > 0; i--) {
          var j = rng.nextInt(i + 1)
          var temp = seq[i]; seq[i] = seq[j]; seq[j] = temp
        }

        var count = isDef(params.count) ? Math.min(seq.length, Math.max(0, params.count)) : seq.length
        return { type: type, start: start, end: end, count: count, sequence: seq.slice(0, count), seed: isDef(seed) ? Number(seed) : null }

      } else if (type === "choice") {
        var items = params.items
        if (!isArray(items) || items.length === 0) return "[ERROR] items array required"

        var count = Math.max(1, Math.floor(Number(params.count || 1)))
        var unique = params.unique === true

        if (unique && count > items.length) return "[ERROR] count exceeds unique items"

        var results = []
        if (unique) {
          var indices = items.map(function(_, i) { return i })
          for (var i = indices.length - 1; i > 0; i--) {
            var j = rng.nextInt(i + 1)
            var temp = indices[i]; indices[i] = indices[j]; indices[j] = temp
          }
          for (var i = 0; i < count; i++) results.push(items[indices[i]])
        } else {
          for (var i = 0; i < count; i++) results.push(items[rng.nextInt(items.length)])
        }

        return { type: type, count: count, unique: unique, choices: results, seed: isDef(seed) ? Number(seed) : null }

      } else if (type === "boolean") {
        var count = Math.max(1, Math.floor(Number(params.count || 1)))
        var prob = Number(params.probabilityTrue || 0.5)
        if (prob < 0 || prob > 1) return "[ERROR] probabilityTrue must be 0-1"

        var values = []
        for (var i = 0; i < count; i++) values.push(rng.nextDouble() < prob)
        return { type: type, count: count, probabilityTrue: prob, values: values, seed: isDef(seed) ? Number(seed) : null }

      } else if (type === "hex") {
        var length = Math.max(1, Math.floor(Number(params.length || 16)))
        var upper = params.uppercase === true
        var chars = upper ? "0123456789ABCDEF" : "0123456789abcdef"

        var result = ""
        for (var i = 0; i < length; i++) result += chars.charAt(rng.nextInt(16))
        return { type: type, length: length, uppercase: upper, value: result, seed: isDef(seed) ? Number(seed) : null }
      }

      return "[ERROR] Unknown random type: " + type
    }

    return "[ERROR] Unknown operation: " + op
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.timeUtilities(params) : Object</key>
 * Performs time and timezone operations.
 * The `params` object can have the following properties:
 * - `operation` (string): The operation to perform (current-time, convert, sleep). Defaults to current-time.
 * - For current-time: `timezone` (optional IANA timezone), `format` (optional Java time pattern)
 * - For convert: `targetTimezone` (required), `sourceTimezone` (optional), `datetime` (optional ISO string)
 * - For sleep: `milliseconds` (required)
 * </odoc>
 */
MiniUtilsTool.prototype.timeUtilities = function(params) {
  params = params || {}
  var op = (params.operation || "current-time").toLowerCase()

  try {
    if (op === "current-time" || op === "current") {
      var ZoneId = java.time.ZoneId
      var ZonedDateTime = java.time.ZonedDateTime
      var DateTimeFormatter = java.time.format.DateTimeFormatter
      var ChronoUnit = java.time.temporal.ChronoUnit

      var zone = isDef(params.timezone) ? ZoneId.of(params.timezone) : ZoneId.systemDefault()
      var now = ZonedDateTime.now(zone)
      var truncatedNow = now.truncatedTo(ChronoUnit.SECONDS)
      var pattern = params.format || "yyyy-MM-dd'T'HH:mm:ssXXX"
      var formatter = DateTimeFormatter.ofPattern(pattern)
      var timeFormatter = DateTimeFormatter.ofPattern("HH:mm:ss")

      return {
        timezone: String(zone.getId()),
        iso8601: String(now.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME)),
        formatted: String(now.format(formatter)),
        date: String(now.toLocalDate()),
        time: String(truncatedNow.toLocalTime().format(timeFormatter)),
        unixEpochSeconds: Number(now.toEpochSecond()),
        unixEpochMilliseconds: Number(now.toInstant().toEpochMilli())
      }

    } else if (op === "convert" || op === "timezone-convert") {
      if (isUnDef(params.targetTimezone)) return "[ERROR] targetTimezone required"

      var ZoneId = java.time.ZoneId
      var ZonedDateTime = java.time.ZonedDateTime
      var DateTimeFormatter = java.time.format.DateTimeFormatter

      var sourceZone = isDef(params.sourceTimezone) ? ZoneId.of(params.sourceTimezone) : ZoneId.systemDefault()
      var targetZone = ZoneId.of(params.targetTimezone)
      var dt = isDef(params.datetime) ? ZonedDateTime.parse(params.datetime) : ZonedDateTime.now(sourceZone)
      var converted = dt.withZoneSameInstant(targetZone)

      return {
        sourceTimezone: String(sourceZone.getId()),
        targetTimezone: String(targetZone.getId()),
        sourceIso8601: String(dt.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME)),
        targetIso8601: String(converted.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME))
      }

    } else if (op === "sleep") {
      var duration = Number(params.milliseconds || 0)
      if (duration < 0) return "[ERROR] milliseconds must be non-negative"
      sleep(duration, true)
      return { sleptMilliseconds: duration }
    }

    return "[ERROR] Unknown operation: " + op
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.textUtilities(params) : Object</key>
 * Performs text and data transformation operations.
 * The `params` object can have the following properties:
 * - `operation` (string, required): The operation to perform.
 * - For encode/decode: `data` (string/bytes), `format` (base64, hex, url, html)
 * - For hash: `data` (string), `algorithm` (md5, sha1, sha256, sha384, sha512)
 * - For format conversion: `data` (string/object), source/target formats (JSON, YAML, TOON, CSV)
 * - For text operations: operation-specific parameters
 * </odoc>
 */
MiniUtilsTool.prototype.textUtilities = function(params) {
  params = params || {}
  var op = (params.operation || "").toLowerCase()

  try {
    // Encoding/Decoding operations
    if (op === "encode") {
      var format = (params.format || "base64").toLowerCase()
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"

      if (format === "base64") {
        var bytes = isString(data) ? af.fromString2Bytes(data) : data
        return { format: "base64", result: af.fromBytes2String(af.toBase64Bytes(bytes)) }
      } else if (format === "hex") {
        var bytes = isString(data) ? af.fromString2Bytes(data) : data
        return { format: "hex", result: af.fromBytes2String(af.fromBytes2HexString(bytes)) }
      } else if (format === "url") {
        return { format: "url", result: encodeURIComponent(String(data)) }
      } else if (format === "html") {
        var encoded = String(data)
          .replace(/&/g, "&amp;")
          .replace(/</g, "&lt;")
          .replace(/>/g, "&gt;")
          .replace(/"/g, "&quot;")
          .replace(/'/g, "&#39;")
        return { format: "html", result: encoded }
      }
      return "[ERROR] Unknown encoding format: " + format

    } else if (op === "decode") {
      var format = (params.format || "base64").toLowerCase()
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"

      if (format === "base64") {
        return { format: "base64", result: af.fromBytes2String(af.fromBase64(data)) }
      } else if (format === "hex") {
        return { format: "hex", result: af.fromBytes2String(af.fromHexString2Bytes(data)) }
      } else if (format === "url") {
        return { format: "url", result: decodeURIComponent(String(data)) }
      } else if (format === "html") {
        var decoded = String(data)
          .replace(/&lt;/g, "<")
          .replace(/&gt;/g, ">")
          .replace(/&quot;/g, '"')
          .replace(/&#39;/g, "'")
          .replace(/&amp;/g, "&")
        return { format: "html", result: decoded }
      }
      return "[ERROR] Unknown decoding format: " + format

    } else if (op === "hash") {
      var algorithm = (params.algorithm || "sha256").toLowerCase()
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"

      var result
      if (algorithm === "md5") result = md5(data)
      else if (algorithm === "sha1") result = sha1(data)
      else if (algorithm === "sha256") result = sha256(data)
      else if (algorithm === "sha384") result = sha384(data)
      else if (algorithm === "sha512") result = sha512(data)
      else return "[ERROR] Unknown hash algorithm: " + algorithm

      return { algorithm: algorithm, hash: result }

    } else if (op === "json-to-yaml" || op === "json2yaml") {
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"
      var obj = isString(data) ? af.fromJson(data) : data
      return { format: "yaml", result: af.toYAML(obj) }

    } else if (op === "yaml-to-json" || op === "yaml2json") {
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"
      var obj = isString(data) ? af.fromYAML(data) : data
      var compact = params.compact === true
      return { format: "json", result: af.toJson(obj, compact ? "" : undefined) }

    } else if (op === "json-to-toon" || op === "json2toon") {
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"
      var obj = isString(data) ? af.fromJson(data) : data
      return { format: "toon", result: af.toTOON(obj) }

    } else if (op === "csv-to-json" || op === "csv2json") {
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"
      ow.loadFormat()
      var csv = new CSV()
      var tempFile = ".temp_csv_" + nowNano() + ".csv"
      try {
        io.writeFileString(tempFile, data)
        var result = csv.fromFile2Array(tempFile)
        io.rm(tempFile)
        return { format: "json", result: result }
      } catch (e) {
        try { io.rm(tempFile) } catch (e2) {}
        throw e
      }

    } else if (op === "json-to-csv" || op === "json2csv") {
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"
      var arr = isString(data) ? af.fromJson(data) : data
      if (!isArray(arr)) return "[ERROR] data must be an array"
      ow.loadFormat()
      var csv = new CSV()
      var tempFile = ".temp_csv_" + nowNano() + ".csv"
      try {
        csv.fromArray2File(arr, tempFile, params.fields)
        var result = io.readFileString(tempFile)
        io.rm(tempFile)
        return { format: "csv", result: result }
      } catch (e) {
        try { io.rm(tempFile) } catch (e2) {}
        throw e
      }

    } else if (op === "webfetch" || op === "fetch") {
      var url = params.url
      if (isUnDef(url)) return "[ERROR] url is required"

      var method = String(params.method || "GET").toUpperCase()
      var timeout = isDef(params.timeout) ? Number(params.timeout) : 30000
      var maxBytes = isDef(params.maxBytes) ? Number(params.maxBytes) : 1048576
      if (isNaN(maxBytes) || maxBytes < 0) maxBytes = 1048576
      var encoding = params.encoding || "utf-8"

      var connection = new java.net.URL(String(url)).openConnection()
      if (timeout > 0) {
        connection.setConnectTimeout(timeout)
        connection.setReadTimeout(timeout)
      }

      if (connection instanceof java.net.HttpURLConnection) {
        connection.setInstanceFollowRedirects(true)
        connection.setRequestMethod(method)
      }

      if (isMap(params.headers)) {
        Object.keys(params.headers).forEach(function(key) {
          connection.setRequestProperty(String(key), String(params.headers[key]))
        })
      }

      if (isDef(params.body)) {
        connection.setDoOutput(true)
        var out = connection.getOutputStream()
        out.write(af.fromString2Bytes(String(params.body)))
        out.close()
      }

      var status = null
      var statusText = null
      if (connection instanceof java.net.HttpURLConnection) {
        status = Number(connection.getResponseCode())
        statusText = String(connection.getResponseMessage())
      }

      var stream = null
      if (connection instanceof java.net.HttpURLConnection && status !== null && status >= 400) {
        stream = connection.getErrorStream()
      } else {
        stream = connection.getInputStream()
      }
      if (isUnDef(stream)) return "[ERROR] Unable to read response stream"

      var buffer = java.lang.reflect.Array.newInstance(java.lang.Byte.TYPE, 8192)
      var output = new java.io.ByteArrayOutputStream()
      var total = 0
      var truncated = false

      while (true) {
        var read = stream.read(buffer)
        if (read === -1) break
        if (maxBytes > 0 && total + read > maxBytes) {
          var remaining = maxBytes - total
          if (remaining > 0) {
            output.write(buffer, 0, remaining)
            total += remaining
          }
          truncated = true
          break
        }
        output.write(buffer, 0, read)
        total += read
      }
      stream.close()

      var resultBytes = output.toByteArray()
      var body = String(new java.lang.String(resultBytes, encoding))
      var headers = {}
      try {
        var headerFields = connection.getHeaderFields()
        if (isDef(headerFields)) {
          var iterator = headerFields.entrySet().iterator()
          while (iterator.hasNext()) {
            var entry = iterator.next()
            var key = entry.getKey()
            if (isUnDef(key)) continue
            headers[String(key)] = String(entry.getValue())
          }
        }
      } catch (e) {
      }

      return {
        url: String(url),
        status: status,
        statusText: statusText,
        headers: headers,
        bytes: total,
        truncated: truncated,
        body: body
      }

    } else if (op === "diff") {
      var text1 = params.text1
      var text2 = params.text2
      if (isUnDef(text1) || isUnDef(text2)) return "[ERROR] text1 and text2 are required"

      var lines1 = String(text1).split(/\r?\n/)
      var lines2 = String(text2).split(/\r?\n/)
      var differences = []
      var maxLines = Math.max(lines1.length, lines2.length)

      for (var i = 0; i < maxLines; i++) {
        var line1 = i < lines1.length ? lines1[i] : undefined
        var line2 = i < lines2.length ? lines2[i] : undefined
        if (line1 !== line2) {
          differences.push({
            line: i + 1,
            text1: line1,
            text2: line2
          })
        }
      }

      return {
        totalLines1: lines1.length,
        totalLines2: lines2.length,
        differenceCount: differences.length,
        differences: differences
      }

    } else if (op === "template" || op === "templify") {
      var template = params.template
      var data = params.data || {}
      if (isUnDef(template)) return "[ERROR] template is required"

      return { result: templify(template, data) }

    } else if (op === "replace") {
      var text = params.text
      var pattern = params.pattern
      var replacement = params.replacement
      if (isUnDef(text) || isUnDef(pattern) || isUnDef(replacement)) {
        return "[ERROR] text, pattern, and replacement are required"
      }

      var flags = params.caseSensitive === true ? "g" : "gi"
      var regex = params.regex === true ? new RegExp(pattern, flags) : new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), flags)
      return { result: String(text).replace(regex, replacement) }

    } else if (op === "extract") {
      var text = params.text
      var pattern = params.pattern
      if (isUnDef(text) || isUnDef(pattern)) return "[ERROR] text and pattern are required"

      var flags = params.caseSensitive === true ? "" : "i"
      var regex = new RegExp(pattern, flags)
      var match = String(text).match(regex)
      return { matches: match || [] }

    } else if (op === "split") {
      var text = params.text
      var delimiter = params.delimiter
      if (isUnDef(text)) return "[ERROR] text is required"
      if (isUnDef(delimiter)) delimiter = ","

      var regex = params.regex === true ? new RegExp(delimiter) : delimiter
      var parts = String(text).split(regex)
      return { count: parts.length, parts: parts }

    } else if (op === "join") {
      var array = params.array
      var delimiter = params.delimiter
      if (isUnDef(array)) return "[ERROR] array is required"
      if (!isArray(array)) return "[ERROR] array must be an array"
      if (isUnDef(delimiter)) delimiter = ","

      return { result: array.join(delimiter) }

    } else if (op === "trim") {
      var text = params.text
      if (isUnDef(text)) return "[ERROR] text is required"

      var chars = params.characters
      var result = String(text)
      if (isDef(chars)) {
        var pattern = "[" + chars.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + "]"
        result = result.replace(new RegExp("^" + pattern + "+"), "")
        result = result.replace(new RegExp(pattern + "+$"), "")
      } else {
        result = result.trim()
      }
      return { result: result }

    } else if (op === "line-count") {
      var text = params.text
      if (isUnDef(text)) return "[ERROR] text is required"
      var lines = String(text).split(/\r?\n/)
      return { count: lines.length }

    } else if (op === "word-count") {
      var text = params.text
      if (isUnDef(text)) return "[ERROR] text is required"
      var words = String(text).trim().split(/\s+/).filter(function(w) { return w.length > 0 })
      return { count: words.length }
    }

    return "[ERROR] Unknown operation: " + op
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.pathUtilities(params) : Object</key>
 * Performs path manipulation operations without filesystem access.
 * The `params` object can have the following properties:
 * - `operation` (string, required): The operation to perform (join, resolve, parse, dirname, basename, extname, normalize, relative, is-absolute).
 * - Operation-specific parameters
 * </odoc>
 */
MiniUtilsTool.prototype.pathUtilities = function(params) {
  params = params || {}
  var op = (params.operation || "").toLowerCase()

  try {
    if (op === "join") {
      var paths = params.paths
      if (!isArray(paths)) return "[ERROR] paths array is required"
      if (paths.length === 0) return { result: "" }

      var result = String(paths[0] || "")
      for (var i = 1; i < paths.length; i++) {
        var file = new java.io.File(result, String(paths[i]))
        result = String(file.getPath())
      }
      return { result: result }

    } else if (op === "resolve") {
      var path = params.path
      if (isUnDef(path)) return "[ERROR] path is required"

      var file = new java.io.File(path)
      return {
        absolute: String(file.getAbsolutePath()),
        canonical: String(file.getCanonicalPath())
      }

    } else if (op === "parse") {
      var path = params.path
      if (isUnDef(path)) return "[ERROR] path is required"

      var file = new java.io.File(path)
      var name = String(file.getName())
      var parent = file.getParent()
      var lastDot = name.lastIndexOf(".")

      return {
        dir: parent ? String(parent) : "",
        base: name,
        name: lastDot > 0 ? name.substring(0, lastDot) : name,
        ext: lastDot > 0 ? name.substring(lastDot) : ""
      }

    } else if (op === "dirname") {
      var path = params.path
      if (isUnDef(path)) return "[ERROR] path is required"

      var parent = new java.io.File(path).getParent()
      return { result: parent ? String(parent) : "" }

    } else if (op === "basename") {
      var path = params.path
      if (isUnDef(path)) return "[ERROR] path is required"

      var name = String(new java.io.File(path).getName())

      if (params.removeExtension === true) {
        var lastDot = name.lastIndexOf(".")
        if (lastDot > 0) name = name.substring(0, lastDot)
      }

      return { result: name }

    } else if (op === "extname") {
      var path = params.path
      if (isUnDef(path)) return "[ERROR] path is required"

      var name = String(new java.io.File(path).getName())
      var lastDot = name.lastIndexOf(".")

      return { result: lastDot > 0 ? name.substring(lastDot) : "" }

    } else if (op === "normalize") {
      var path = params.path
      if (isUnDef(path)) return "[ERROR] path is required"

      return { result: String(new java.io.File(path).getPath()) }

    } else if (op === "relative") {
      var from = params.from
      var to = params.to
      if (isUnDef(from) || isUnDef(to)) return "[ERROR] from and to are required"

      var fromPath = java.nio.file.Paths.get(from)
      var toPath = java.nio.file.Paths.get(to)
      var relative = fromPath.relativize(toPath)

      return { result: String(relative) }

    } else if (op === "is-absolute") {
      var path = params.path
      if (isUnDef(path)) return "[ERROR] path is required"

      return { result: new java.io.File(path).isAbsolute() }
    }

    return "[ERROR] Unknown operation: " + op
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.filesystemBatch(params) : Array</key>
 * Executes multiple filesystem operations in a single call.
 * The `params` object can have the following properties:
 * - `operations` (array, required): Array of operation objects, each with `type` and `params`
 * - `stopOnError` (boolean, optional): Stop execution on first error. Defaults to false.
 * - `compact` (boolean, optional): Return compact results. Defaults to false.
 * </odoc>
 */
MiniUtilsTool.prototype.filesystemBatch = function(params) {
  params = params || {}
  var operations = params.operations
  if (!isArray(operations)) return "[ERROR] operations array is required"

  var stopOnError = params.stopOnError === true
  var compact = params.compact === true
  var results = []

  try {
    this._ensureInitialized()

    for (var i = 0; i < operations.length; i++) {
      var op = operations[i]
      var rawType = isMap(op) ? (isString(op.type) ? op.type : op.operation) : null
      if (!isMap(op) || !isString(rawType)) {
        results.push({ error: "Invalid operation at index " + i, success: false })
        if (stopOnError) break
        continue
      }

      var opType = rawType.toLowerCase()
      var opParams = isMap(op.params) ? op.params : {}
      Object.keys(op).forEach(function(key) {
        if (key === "type" || key === "operation" || key === "params") return
        if (isUnDef(opParams[key])) opParams[key] = op[key]
      })
      if (compact) opParams.compact = true

      var result
      try {
        if (opType === "read" || opType === "readfile") {
          result = this.readFile(opParams)
        } else if (opType === "list" || opType === "listdirectory") {
          result = this.listDirectory(opParams)
        } else if (opType === "search" || opType === "searchcontent") {
          result = this.searchContent(opParams)
        } else if (opType === "glob") {
          result = this.globFiles(opParams)
        } else if (opType === "info" || opType === "getfileinfo") {
          result = this.getFileInfo(opParams)
        } else {
          result = "[ERROR] Unknown operation type: " + opType
        }

        if (isString(result) && result.indexOf("[ERROR]") === 0) {
          results.push({ error: result, success: false, operation: opType })
          if (stopOnError) break
        } else {
          results.push({ data: result, success: true, operation: opType })
        }
      } catch (e) {
        results.push({ error: __miniAErrMsg(e), success: false, operation: opType })
        if (stopOnError) break
      }
    }

    return {
      totalOperations: operations.length,
      completed: results.length,
      results: results
    }
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.validationUtilities(params) : Object</key>
 * Validates data formats and tests conditions.
 * The `params` object can have the following properties:
 * - `operation` (string, required): The operation to perform (validate-json, validate-yaml, validate-toon, validate-regex, validate-url, test-regex, file-exists).
 * - Operation-specific parameters
 * </odoc>
 */
MiniUtilsTool.prototype.validationUtilities = function(params) {
  params = params || {}
  var op = (params.operation || "").toLowerCase()

  try {
    if (op === "validate-json") {
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"

      try {
        af.fromJson(data)
        return { valid: true, format: "json" }
      } catch (e) {
        return { valid: false, format: "json", error: __miniAErrMsg(e) }
      }

    } else if (op === "validate-yaml") {
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"

      try {
        af.fromYAML(data)
        return { valid: true, format: "yaml" }
      } catch (e) {
        return { valid: false, format: "yaml", error: __miniAErrMsg(e) }
      }

    } else if (op === "validate-toon") {
      var data = params.data
      if (isUnDef(data)) return "[ERROR] data is required"

      try {
        af.fromTOON(data)
        return { valid: true, format: "toon" }
      } catch (e) {
        return { valid: false, format: "toon", error: __miniAErrMsg(e) }
      }

    } else if (op === "validate-regex") {
      var pattern = params.pattern
      if (isUnDef(pattern)) return "[ERROR] pattern is required"

      try {
        new RegExp(pattern)
        return { valid: true, pattern: pattern }
      } catch (e) {
        return { valid: false, pattern: pattern, error: __miniAErrMsg(e) }
      }

    } else if (op === "validate-url") {
      var url = params.url
      if (isUnDef(url)) return "[ERROR] url is required"

      try {
        new java.net.URL(url)
        return { valid: true, url: url }
      } catch (e) {
        return { valid: false, url: url, error: __miniAErrMsg(e) }
      }

    } else if (op === "test-regex") {
      var pattern = params.pattern
      var text = params.text
      if (isUnDef(pattern) || isUnDef(text)) return "[ERROR] pattern and text are required"

      try {
        var flags = params.caseSensitive === true ? "" : "i"
        var regex = new RegExp(pattern, flags)
        var matches = String(text).match(regex)
        return {
          matches: matches !== null,
          pattern: pattern,
          matchedText: matches ? matches[0] : null,
          allMatches: matches || []
        }
      } catch (e) {
        return { valid: false, error: __miniAErrMsg(e) }
      }

    } else if (op === "file-exists") {
      var path = params.path
      if (isUnDef(path)) return "[ERROR] path is required"

      try {
        this._ensureInitialized()
        var filePath = this._resolve(path)
        return { exists: io.fileExists(filePath), path: this._toRelative(filePath) }
      } catch (e) {
        return { exists: false, error: __miniAErrMsg(e) }
      }
    }

    return "[ERROR] Unknown operation: " + op
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.systemInfo(params) : Object</key>
 * Retrieves system information about the execution environment.
 * The `params` object can have the following properties:
 * - `operation` (string, required): The operation to perform (environment, platform, cwd, user, memory, disk).
 * - For environment: `filter` (optional string) - regex to filter env vars
 * </odoc>
 */
MiniUtilsTool.prototype.systemInfo = function(params) {
  params = params || {}
  var op = (params.operation || "platform").toLowerCase()

  try {
    if (op === "environment" || op === "env") {
      var filter = params.filter
      var envVars = {}
      var env = java.lang.System.getenv()
      var iterator = env.entrySet().iterator()

      while (iterator.hasNext()) {
        var entry = iterator.next()
        var key = String(entry.getKey())
        var value = String(entry.getValue())

        if (isDef(filter)) {
          var regex = new RegExp(filter, "i")
          if (regex.test(key)) {
            envVars[key] = value
          }
        } else {
          envVars[key] = value
        }
      }

      return { environment: envVars, count: Object.keys(envVars).length }

    } else if (op === "platform") {
      return {
        os: String(java.lang.System.getProperty("os.name")),
        version: String(java.lang.System.getProperty("os.version")),
        arch: String(java.lang.System.getProperty("os.arch")),
        javaVersion: String(java.lang.System.getProperty("java.version")),
        separator: String(java.io.File.separator),
        pathSeparator: String(java.io.File.pathSeparator)
      }

    } else if (op === "cwd") {
      return { cwd: String(java.lang.System.getProperty("user.dir")) }

    } else if (op === "user") {
      return {
        name: String(java.lang.System.getProperty("user.name")),
        home: String(java.lang.System.getProperty("user.home"))
      }

    } else if (op === "memory") {
      var runtime = java.lang.Runtime.getRuntime()
      return {
        totalMemory: Number(runtime.totalMemory()),
        freeMemory: Number(runtime.freeMemory()),
        maxMemory: Number(runtime.maxMemory()),
        usedMemory: Number(runtime.totalMemory() - runtime.freeMemory())
      }

    } else if (op === "disk") {
      this._ensureInitialized()
      var rootFile = new java.io.File(this._root)
      return {
        totalSpace: Number(rootFile.getTotalSpace()),
        freeSpace: Number(rootFile.getFreeSpace()),
        usableSpace: Number(rootFile.getUsableSpace()),
        path: this._root
      }
    }

    return "[ERROR] Unknown operation: " + op
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.memoryStore(params) : Object</key>
 * Simple key-value store for temporary data storage during execution.
 * The `params` object can have the following properties:
 * - `operation` (string, required): The operation to perform (set, get, delete, list, clear).
 * - For set: `key` (string), `value` (any), `ttl` (optional milliseconds)
 * - For get/delete: `key` (string)
 * </odoc>
 */
MiniUtilsTool.prototype.memoryStore = function(params) {
  params = params || {}
  var op = (params.operation || "").toLowerCase()

  if (isUnDef(this._kvStore)) {
    this._kvStore = {}
  }

  try {
    if (op === "set") {
      var key = params.key
      var value = params.value
      if (isUnDef(key)) return "[ERROR] key is required"
      if (isUnDef(value)) return "[ERROR] value is required"

      var entry = { value: value, timestamp: nowNano() }
      if (isDef(params.ttl) && Number(params.ttl) > 0) {
        entry.expiresAt = nowNano() + (Number(params.ttl) * 1000000)
      }

      this._kvStore[key] = entry
      return { key: key, stored: true }

    } else if (op === "get") {
      var key = params.key
      if (isUnDef(key)) return "[ERROR] key is required"

      var entry = this._kvStore[key]
      if (isUnDef(entry)) {
        return { key: key, found: false }
      }

      // Check TTL
      if (isDef(entry.expiresAt) && nowNano() > entry.expiresAt) {
        delete this._kvStore[key]
        return { key: key, found: false, expired: true }
      }

      return { key: key, found: true, value: entry.value }

    } else if (op === "delete") {
      var key = params.key
      if (isUnDef(key)) return "[ERROR] key is required"

      var existed = isDef(this._kvStore[key])
      delete this._kvStore[key]
      return { key: key, deleted: existed }

    } else if (op === "list") {
      var keys = []
      var now = nowNano()

      for (var key in this._kvStore) {
        if (!this._kvStore.hasOwnProperty(key)) continue
        var entry = this._kvStore[key]

        // Skip expired entries
        if (isDef(entry.expiresAt) && now > entry.expiresAt) {
          delete this._kvStore[key]
          continue
        }

        keys.push(key)
      }

      return { count: keys.length, keys: keys }

    } else if (op === "clear") {
      var count = Object.keys(this._kvStore).length
      this._kvStore = {}
      return { cleared: count }
    }

    return "[ERROR] Unknown operation: " + op
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.todoList(params) : Object</key>
 * Lightweight in-memory todo list helper for temporary task tracking during execution.
 * The `params` object can have the following properties:
 * - `operation` (string, required): The operation to perform (write, read).
 * - For write: `items` (array) or `item` (single value), `append` (boolean)
 * </odoc>
 */
MiniUtilsTool.prototype.todoList = function(params) {
  params = params || {}
  var op = (params.operation || "").toLowerCase()

  if (isUnDef(this._todoList)) {
    this._todoList = []
  }

  try {
    if (op === "write") {
      var items = params.items
      var item = params.item
      var append = params.append === true

      if (isUnDef(items) && isUnDef(item)) return "[ERROR] items or item is required"
      if (isDef(items) && !isArray(items)) return "[ERROR] items must be an array"

      var nextList = append ? this._todoList.slice(0) : []
      if (isArray(items)) {
        items.forEach(function(entry) {
          if (isDef(entry)) nextList.push(entry)
        })
      } else if (isDef(item)) {
        nextList.push(item)
      }

      this._todoList = nextList
      return { count: this._todoList.length, items: this._todoList.slice(0) }
    } else if (op === "read") {
      return { count: this._todoList.length, items: this._todoList.slice(0) }
    }

    return "[ERROR] Unknown operation: " + op
  } catch (e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

MiniUtilsTool.prototype._ask = function(prompt, mask) {
  return ask(prompt, mask)
}

MiniUtilsTool.prototype._askEncrypt = function(prompt) {
  return askEncrypt(prompt)
}

MiniUtilsTool.prototype._ask1 = function(prompt, options) {
  return ask1(prompt, options)
}

MiniUtilsTool.prototype._askChoose = function(prompt, options, max, help) {
  return askChoose(prompt, options, max, help)
}

MiniUtilsTool.prototype._askChooseMultiple = function(prompt, options, max, help) {
  var result = askChooseMultiple(prompt, options, max, help)
  return isArray(result) ? result : []
}

MiniUtilsTool.prototype._askStruct = function(questions) {
  return askStruct(questions)
}

/**
 * <odoc>
 * <key>MiniUtilsTool.showMessage(params) : Object</key>
 * Displays a message to the user during execution.
 * </odoc>
 */
MiniUtilsTool.prototype.showMessage = function(params) {
  params = params || {}
  // Some models incorrectly reuse the userInput shape and send `prompt`.
  // Accept it as a compatibility alias so status messages still render.
  var message = isString(params.message) ? params.message : ""
  if (message.length === 0 && isString(params.prompt)) message = params.prompt
  if (message.length === 0) return "[ERROR] message is required"

  var level = isString(params.level) ? params.level.toLowerCase().trim() : "info"
  var title = isString(params.title) ? params.title.trim() : ""

  var colorFn = (typeof ansiColor === "function") ? ansiColor : function(_, t) { return t }
  var borderColorMap = { info: "FG(51)", warn: "FG(220)", error: "FG(196)", success: "FG(46)", debug: "FG(244)" }
  var textStyleMap   = {
    info   : "BG(235),FG(255)",
    warn   : "BG(235),FG(255)",
    error  : "BG(52),FG(255)",
    success: "BG(22),FG(255)",
    debug  : "BG(236),FG(252)"
  }
  var prefixMap = { info: "i", warn: "!", error: "x", success: "✓", debug: "🐞" }
  var borderColor = borderColorMap[level] || "FG(51)"
  var textStyle   = textStyleMap[level]   || "BG(235),FG(255)"
  var prefix      = prefixMap[level]      || "i"

  try {
    ow.loadFormat()
    var lines = []
    var messageBgColor = ""
    var messageBgMatch = textStyle.match(/(?:^|,)(BG\([^)]+\)|BG_[A-Z0-9_]+)(?:,|$)/)
    if (isArray(messageBgMatch) && isString(messageBgMatch[1])) messageBgColor = messageBgMatch[1]
    var messageLineWidth = isDef(__con) ? __con.getTerminal().getWidth() - 3 : 77
    var renderedMessage = ow.format.withMD(message, __, Math.max(1, messageLineWidth), messageBgColor)
    //var renderedMessage = message
    if (title.length > 0) {
      lines.push(colorFn("BOLD", title))
    }
    lines.push("(" + prefix + ") " + renderedMessage)
    print("")
    var line = ow.format.withSideLine(lines.join("\n"), __, borderColor, textStyle, ow.format.withSideLineThemes().closedCurvedRect)
    if (level === "error" || level === "warn") {
      printErr(line)
    } else {
      print(line)
    }
    print("")
    return { operation: "showMessage", displayed: true, level: level, message: message }
  } catch(e) {
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

/**
 * <odoc>
 * <key>MiniUtilsTool.userInput(params) : Object</key>
 * Interactively asks the user for input using OpenAF ask* helpers.
 * This tool is intended for interactive console sessions.
 * The `params` object can have the following properties:
 * - `operation` (string, required): ask, secret, char, choose, multiple, struct
 * - `prompt` (string): Prompt text for ask/secret/char/choose/multiple
 * - `mask` (string): Optional mask character for ask
 * - `options` (array): Allowed/available options for char/choose/multiple
 * - `max` (number): Optional max display size for choose/multiple
 * - `help` (string): Optional help text for choose/multiple
 * - `output` (string): For choose/multiple/struct, set to `index` to return selected indexes
 * - `questions` (array): askStruct-compatible question definitions for operation=struct
 * </odoc>
 */
MiniUtilsTool.prototype.userInput = function(params) {
  params = params || {}
  var op = String(params.operation || "ask").toLowerCase()

  try {
    if (isObject(global.__mini_a_metrics) && isObject(global.__mini_a_metrics.user_input_requested)) {
      global.__mini_a_metrics.user_input_requested.inc()
    }

    var result
    var prompt = isString(params.prompt) ? params.prompt : ""
    var options = isArray(params.options) ? params.options : __
    var outputMode = isString(params.output) ? params.output.toLowerCase().trim() : ""

    switch(op) {
    case "ask":
    case "question":
      if (prompt.length === 0) return "[ERROR] prompt is required"
      result = {
        operation: "ask",
        answer   : this._ask(prompt, params.mask)
      }
      break
    case "secret":
    case "password":
    case "encrypt":
      if (prompt.length === 0) return "[ERROR] prompt is required"
      result = {
        operation: "secret",
        answer   : this._askEncrypt(prompt)
      }
      break
    case "char":
    case "ask1":
      if (prompt.length === 0) return "[ERROR] prompt is required"
      if (!isArray(options) || options.length === 0) return "[ERROR] options array is required"
      result = {
        operation: "char",
        answer   : this._ask1(prompt, options)
      }
      break
    case "choose":
      if (prompt.length === 0) return "[ERROR] prompt is required"
      if (!isArray(options) || options.length === 0) return "[ERROR] options array is required"
      var selectedIndex = this._askChoose(prompt, options, params.max, params.help)
      result = {
        operation    : "choose",
        selectedIndex: selectedIndex,
        answer       : outputMode === "index" ? selectedIndex : options[selectedIndex]
      }
      break
    case "multiple":
    case "multi":
      if (prompt.length === 0) return "[ERROR] prompt is required"
      if (!isArray(options) || options.length === 0) return "[ERROR] options array is required"
      var selectedValues = this._askChooseMultiple(prompt, options, params.max, params.help)
      result = {
        operation: "multiple",
        count    : isArray(selectedValues) ? selectedValues.length : 0,
        answer   : outputMode === "index" && isArray(selectedValues)
          ? selectedValues.map(function(entry) { return options.indexOf(entry) })
          : selectedValues
      }
      break
    case "struct":
    case "form":
      if (!isArray(params.questions) || params.questions.length === 0) return "[ERROR] questions array is required"
      result = {
        operation: "struct",
        answers  : this._askStruct(params.questions)
      }
      break
    default:
      return "[ERROR] Unknown operation: " + op
    }

    if (isObject(global.__mini_a_metrics) && isObject(global.__mini_a_metrics.user_input_completed)) {
      global.__mini_a_metrics.user_input_completed.inc()
    }
    return result
  } catch (e) {
    if (isObject(global.__mini_a_metrics) && isObject(global.__mini_a_metrics.user_input_failed)) {
      global.__mini_a_metrics.user_input_failed.inc()
    }
    return "[ERROR] " + __miniAErrMsg(e)
  }
}

MiniUtilsTool._metadataByFn = (function() {
  var queryReadOps = ["read", "readfile", "get", "view"]
  var queryListOps = ["list", "ls", "listdirectory", "dir"]
  var querySearchOps = ["search", "searchcontent", "grep", "find", "glob"]
  var queryInfoOps = ["info", "stat", "metadata", "getfileinfo"]
  var queryReadInfoOps = queryReadOps.concat(queryInfoOps)
  var queryAllOps = queryReadOps
    .concat(queryListOps)
    .concat(querySearchOps)
    .concat(queryInfoOps)

  var modifyWriteOps = ["write", "writefile", "save", "append"]
  var modifyEditOps = ["edit", "replace"]
  var modifyDeleteOps = ["delete", "remove", "rm", "deletefile"]
  var modifyAllOps = modifyWriteOps.concat(modifyEditOps).concat(modifyDeleteOps)

  var mathOperationTypes = ["calculate", "statistics", "convert-unit", "convert", "random"]
  var timeOperationTypes = ["current-time", "current", "timezone-convert", "sleep"]

  // Text utilities operation types
  var textEncodeOps = ["encode", "decode"]
  var textHashOps = ["hash"]
  var textConvertOps = ["json-to-yaml", "json2yaml", "yaml-to-json", "yaml2json", "json-to-toon", "json2toon", "csv-to-json", "csv2json", "json-to-csv", "json2csv"]
  var textFetchOps = ["webfetch", "fetch"]
  var textManipOps = ["diff", "template", "templify", "replace", "extract", "split", "join", "trim", "line-count", "word-count"]
  var textAllOps = textEncodeOps.concat(textHashOps).concat(textConvertOps).concat(textFetchOps).concat(textManipOps)

  // Path utilities operation types
  var pathOps = ["join", "resolve", "parse", "dirname", "basename", "extname", "normalize", "relative", "is-absolute"]

  // Validation utilities operation types
  var validationOps = ["validate-json", "validate-yaml", "validate-toon", "validate-regex", "validate-url", "test-regex", "file-exists"]

  // System info operation types
  var systemInfoOps = ["environment", "env", "platform", "cwd", "user", "memory", "disk"]

  var memoryStoreOps = ["set", "get", "delete", "list", "clear"]
  var todoListOps = ["write", "read"]
  var userInputOps = ["ask", "question", "secret", "password", "encrypt", "char", "ask1", "choose", "multiple", "multi", "struct", "form"]
  var markdownOps = ["list", "search", "read", "get", "view", "cat"]
  var skillOps = ["list", "search", "read", "get", "view", "cat", "render", "use", "expand", "apply", "invoke", "run"]

  return {
    init: {
      name       : "init",
      description: "Re-initialize the MiniUtilsTool with a new root directory and permissions for file operations.",
      inputSchema: {
        type      : "object",
        properties: {
          root     : { type: "string", description: "Root directory for subsequent file operations. Defaults to current directory." },
          readwrite: { type: "boolean", description: "Enable write and delete operations when set to true." },
          skillsroot: { type: "string", description: "Optional additional skill root directory for skill discovery." },
          skillsroots: { type: "array", items: { type: "string" }, description: "Optional ordered skill root directories for skill discovery." }
        }
      }
    },
    filesystemQuery: {
      name       : "filesystemQuery",
      description: "Unified read-only filesystem tool: read files, list directories, search content, glob match paths, or get file info. Use this to explore codebases, locate files, or inspect metadata while keeping output compact.",
      inputSchema: {
        type      : "object",
        properties: {
          operation    : {
            type       : "string",
            description: "Operation to execute (read, list, search, glob, info). Use read for file contents, list for directory contents, search for text matches, glob for path patterns, info for metadata.",
            enum       : queryAllOps,
            default    : "read"
          },
          path         : { type: "string", description: "Target file or directory path for the operation." },
          encoding     : { type: "string", description: "Character encoding to use when reading files." },
          byteStart    : { type: "number", description: "Zero-based byte offset to start reading from (read operation)." },
          byteEnd      : { type: "number", description: "Zero-based byte offset to stop reading (inclusive, read operation)." },
          byteLength   : { type: "number", description: "Number of bytes to read from byteStart (read operation)." },
          lineStart    : { type: "number", description: "One-based line number to start reading from (read operation)." },
          lineEnd      : { type: "number", description: "One-based line number to stop reading (inclusive, read operation)." },
          maxLines     : { type: "number", description: "Maximum number of lines to read (read operation)." },
          lineSeparator: { type: "string", description: "Line separator for line reads (read operation, default \\n)." },
          countLines   : { type: "boolean", description: "Return total line count without loading full content (read operation)." },
          includeHidden: { type: "boolean", description: "Include hidden files in list operations when true." },
          recursive    : { type: "boolean", description: "Traverse directories recursively when supported." },
          pattern      : { type: "string", description: "Pattern to search for when operation is set to search or glob (glob uses filesystem-style patterns)." },
          regex        : { type: "boolean", description: "Treat pattern as a regular expression when operation is search (ignored for glob)." },
          caseSensitive: { type: "boolean", description: "Perform case-sensitive searches when operation is search." },
          maxResults   : { type: "number", description: "Maximum number of search matches to return (0 means no limit)." },
          compact      : { type: "boolean", description: "Return compact results with minimal metadata to save context." }
        },
        allOf    : [
          {
            if  : { not: { required: ["operation"] } },
            then: { required: ["path"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: queryReadInfoOps } } },
            then: { required: ["path"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: querySearchOps } } },
            then: { required: ["pattern"] }
          }
        ]
      }
    },
    filesystemModify: {
      name       : "filesystemModify",
      description: "Unified write filesystem tool: write/append files, edit in-place, or delete paths. Use for controlled file changes; requires readwrite=true.",
      inputSchema: {
        type      : "object",
        properties: {
          operation        : {
            type       : "string",
            description: "Operation to execute (write, append, edit, delete). Use edit for in-place replacements, delete for cleanup.",
            enum       : modifyAllOps
          },
          path             : { type: "string", description: "Target file or directory path for the operation." },
          content          : { type: "string", description: "Content to write when operation is set to write or append." },
          encoding         : { type: "string", description: "Character encoding to use when writing content." },
          append           : { type: "boolean", description: "Append to the file instead of overwriting when supported." },
          createMissingDirs: { type: "boolean", description: "Create parent directories when writing files if they do not exist." },
          pattern          : { type: "string", description: "Pattern to search for when operation is set to edit (literal unless regex=true)." },
          replacement      : { type: "string", description: "Replacement text when operation is set to edit." },
          regex            : { type: "boolean", description: "Treat pattern as a regular expression when operation is edit." },
          caseSensitive    : { type: "boolean", description: "Case-sensitive matching when operation is edit." },
          maxReplacements  : { type: "number", description: "Maximum number of replacements to perform when editing." },
          requireMatch     : { type: "boolean", description: "Require at least one match when editing (error if none)." },
          confirm          : { type: "boolean", description: "Must be true to confirm deletion operations." },
          recursive        : { type: "boolean", description: "Delete directories and their contents recursively when true." }
        },
        required : ["operation", "path"],
        allOf    : [
          {
            if  : { required: ["operation"], properties: { operation: { enum: modifyWriteOps } } },
            then: { required: ["content"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: modifyEditOps } } },
            then: { required: ["pattern", "replacement"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: modifyDeleteOps } } },
            then: { required: ["confirm"] }
          }
        ]
      }
    },
    mathematics: {
      name       : "mathematics",
      description: "Perform calculations, statistics, unit conversions, random generation. Use for: computing values, analyzing datasets, converting units, generating test data.",
      inputSchema: {
        type      : "object",
        properties: {
          operation: {
            type       : "string",
            description: "Operation type: calculate, statistics, convert-unit, or random.",
            enum       : mathOperationTypes,
            default    : "calculate"
          },
          op           : { type: "string", description: "Math operation for calculate: add, subtract, multiply, divide, power, sqrt, abs, round." },
          values       : { type: "array", items: { type: "number" }, description: "Array of numbers for calculate or statistics operations." },
          precision    : { type: "number", description: "Decimal precision for rounding results." },
          metrics      : { type: "array", items: { type: "string" }, description: "Specific metrics for statistics: mean, median, min, max, sum, count." },
          value        : { type: "number", description: "Value to convert for convert-unit operation." },
          fromUnit     : { type: "string", description: "Source unit for conversion (m, km, cm, mm, mi, ft, in, kg, g, lb, oz, l, ml, gal)." },
          toUnit       : { type: "string", description: "Target unit for conversion." },
          type         : { type: "string", description: "Random type: integer, sequence, choice, boolean, hex." },
          min          : { type: "number", description: "Minimum value for random integer." },
          max          : { type: "number", description: "Maximum value for random integer or sequence end." },
          start        : { type: "number", description: "Start value for random sequence." },
          end          : { type: "number", description: "End value for random sequence." },
          count        : { type: "number", description: "Count of items to generate or select." },
          items        : { type: "array", description: "Array of items for random choice." },
          unique       : { type: "boolean", description: "Ensure unique choices when true." },
          seed         : { type: "number", description: "Seed for deterministic random generation." },
          probabilityTrue: { type: "number", description: "Probability (0-1) for random boolean generation." },
          length       : { type: "number", description: "Length of random hex string." },
          uppercase    : { type: "boolean", description: "Use uppercase for hex string." }
        },
        required : []
      }
    },
    timeUtilities: {
      name       : "timeUtilities",
      description: "Get current time, convert timezones, pause execution. Use for: timestamps, timezone conversions, scheduling delays, time formatting.",
      inputSchema: {
        type      : "object",
        properties: {
          operation     : {
            type       : "string",
            description: "Operation type: current-time, convert, or sleep.",
            enum       : timeOperationTypes,
            default    : "current-time"
          },
          timezone       : { type: "string", description: "IANA timezone identifier (e.g., 'America/New_York', 'Europe/London')." },
          format         : { type: "string", description: "Java time pattern for formatting (e.g., 'yyyy-MM-dd HH:mm:ss')." },
          targetTimezone : { type: "string", description: "Target timezone for conversion (required for convert operation)." },
          sourceTimezone : { type: "string", description: "Source timezone for conversion (defaults to system timezone)." },
          datetime       : { type: "string", description: "ISO 8601 datetime string for conversion (defaults to current time)." },
          milliseconds   : { type: "number", description: "Duration in milliseconds for sleep operation." }
        },
        required : []
      }
    },
    textUtilities: {
      name       : "textUtilities",
      description: "Text/data helper: encode/decode, hash, convert JSON/YAML/TOON/CSV, fetch URLs, and manipulate strings. Use for quick transformations or lightweight web fetches.",
      inputSchema: {
        type      : "object",
        properties: {
          operation  : {
            type       : "string",
            description: "Operation type: encode, decode, hash, json-to-yaml, yaml-to-json, json-to-toon, csv-to-json, json-to-csv, webfetch, diff, template, replace, extract, split, join, trim, line-count, word-count.",
            enum       : textAllOps
          },
          data       : { type: "string", description: "Data to process (text, JSON, YAML, CSV, etc.)." },
          format     : { type: "string", description: "Encoding format for encode/decode: base64, hex, url, html." },
          algorithm  : { type: "string", description: "Hash algorithm: md5, sha1, sha256, sha384, sha512." },
          url        : { type: "string", description: "URL to fetch when operation is webfetch." },
          method     : { type: "string", description: "HTTP method for webfetch (default GET)." },
          headers    : { type: "object", description: "HTTP headers for webfetch." },
          body       : { type: "string", description: "Request body for webfetch." },
          timeout    : { type: "number", description: "Timeout in milliseconds for webfetch." },
          maxBytes   : { type: "number", description: "Maximum bytes to read for webfetch (prevents huge responses)." },
          encoding   : { type: "string", description: "Response encoding for webfetch." },
          text       : { type: "string", description: "Text input for text operations." },
          text1      : { type: "string", description: "First text for diff operation." },
          text2      : { type: "string", description: "Second text for diff operation." },
          template   : { type: "string", description: "Template string with {{variable}} placeholders." },
          pattern    : { type: "string", description: "Pattern for replace/extract operations." },
          replacement: { type: "string", description: "Replacement text for replace operation." },
          delimiter  : { type: "string", description: "Delimiter for split/join operations." },
          array      : { type: "array", description: "Array for join operation." },
          characters : { type: "string", description: "Characters to trim." },
          regex      : { type: "boolean", description: "Treat pattern as regular expression." },
          caseSensitive: { type: "boolean", description: "Case-sensitive operations." },
          compact    : { type: "boolean", description: "Compact JSON output." },
          fields     : { type: "array", description: "CSV fields to include." }
        },
        required : ["operation"]
      }
    },
    pathUtilities: {
      name       : "pathUtilities",
      description: "Manipulate file paths without filesystem access: join, resolve, parse, get dirname/basename/extension. Use for: path construction, path parsing, checking path types.",
      inputSchema: {
        type      : "object",
        properties: {
          operation      : {
            type       : "string",
            description: "Operation type: join, resolve, parse, dirname, basename, extname, normalize, relative, is-absolute.",
            enum       : pathOps
          },
          path           : { type: "string", description: "Path to process." },
          paths          : { type: "array", items: { type: "string" }, description: "Array of path segments to join." },
          from           : { type: "string", description: "Source path for relative operation." },
          to             : { type: "string", description: "Target path for relative operation." },
          removeExtension: { type: "boolean", description: "Remove extension from basename." }
        },
        required : ["operation"]
      }
    },
    filesystemBatch: {
      name       : "filesystemBatch",
      description: "Execute multiple filesystem operations in one call to reduce roundtrips. Use for: batch reading files, checking multiple paths, efficient multi-file operations.",
      inputSchema: {
        type      : "object",
        properties: {
          operations : {
            type       : "array",
            description: "Array of operations to execute.",
            items      : {
              type      : "object",
              properties: {
                type  : { type: "string", description: "Operation type: read, list, search, glob, info." },
                params: { type: "object", description: "Parameters for the operation." }
              },
              required : ["type"]
            }
          },
          stopOnError: { type: "boolean", description: "Stop processing on first error." },
          compact    : { type: "boolean", description: "Return compact results." }
        },
        required : ["operations"]
      }
    },
    validationUtilities: {
      name       : "validationUtilities",
      description: "Validate data formats and test conditions: JSON/YAML/TOON syntax, regex patterns, URLs, file existence. Use for: validating input, checking syntax, testing patterns before use.",
      inputSchema: {
        type      : "object",
        properties: {
          operation    : {
            type       : "string",
            description: "Operation type: validate-json, validate-yaml, validate-toon, validate-regex, validate-url, test-regex, file-exists.",
            enum       : validationOps
          },
          data         : { type: "string", description: "Data to validate (JSON/YAML/TOON string)." },
          pattern      : { type: "string", description: "Regex pattern to validate or test." },
          text         : { type: "string", description: "Text to test against pattern." },
          url          : { type: "string", description: "URL to validate." },
          path         : { type: "string", description: "File path to check existence." },
          caseSensitive: { type: "boolean", description: "Case-sensitive regex testing." }
        },
        required : ["operation"]
      }
    },
    systemInfo: {
      name       : "systemInfo",
      description: "Get system information: environment variables, platform details, current directory, user info, memory/disk usage. Use for: understanding execution environment, checking resources, getting system context.",
      inputSchema: {
        type      : "object",
        properties: {
          operation: {
            type       : "string",
            description: "Operation type: environment, platform, cwd, user, memory, disk.",
            enum       : systemInfoOps,
            default    : "platform"
          },
          filter   : { type: "string", description: "Regex filter for environment variables." }
        },
        required : []
      }
    },
    memoryStore: {
      name       : "memoryStore",
      description: "Ephemeral memory helper: store and retrieve short-lived key/value data between steps.",
      inputSchema: {
        type      : "object",
        properties: {
          operation: {
            type       : "string",
            description: "Operation type: set, get, delete, list, clear.",
            enum       : memoryStoreOps
          },
          key      : { type: "string", description: "Key for set/get/delete operations." },
          value    : { description: "Value to store (any type)." },
          ttl      : { type: "number", description: "Time-to-live in milliseconds." }
        },
        required : ["operation"]
      }
    },
    todoList: {
      name       : "todoList",
      description: "Lightweight in-memory todo list helper. Use for short task lists that only need write/read behavior.",
      inputSchema: {
        type      : "object",
        properties: {
          operation: {
            type       : "string",
            description: "Operation type: write or read.",
            enum       : todoListOps
          },
          items    : { type: "array", description: "Todo items array for write operation." },
          item     : { description: "Single todo item for write operation." },
          append   : { type: "boolean", description: "Append to existing todo list when true." }
        },
        required : ["operation"]
      }
    },
    userInput: {
      name       : "userInput",
      description: "Request input or a decision from the user. Call this tool whenever you need a value, clarification, or choice from the user — instead of asking in your final answer or stopping execution. Supports free-form text (ask), secret/password (secret), single-key (char), single-choice list (choose), multi-choice list (multiple), and structured multi-question forms (struct).",
      inputSchema: {
        type      : "object",
        properties: {
          operation: {
            type       : "string",
            description: "Operation type: ask, secret, char, choose, multiple, or struct.",
            enum       : userInputOps,
            default    : "ask"
          },
          prompt   : { type: "string", description: "Prompt shown to the user for ask/secret/char/choose/multiple operations." },
          mask     : { type: "string", description: "Optional mask character for ask operation." },
          options  : { type: "array", items: {}, description: "Allowed or selectable options for char/choose/multiple operations." },
          max      : { type: "number", description: "Optional max number of options to display at once for choose/multiple." },
          help     : { type: "string", description: "Optional help text shown during choose/multiple operations." },
          output   : { type: "string", description: "Optional output mode. Set to 'index' to return selected indexes for choose/multiple or askStruct questions configured that way." },
          questions: {
            type       : "array",
            description: "askStruct-compatible question definitions for operation=struct.",
            items      : {
              type      : "object",
              properties: {
                name   : { type: "string", description: "Stable field name for the question." },
                prompt : { type: "string", description: "Prompt shown to the user." },
                type   : { type: "string", description: "Question type: question, secret, char, choose, multiple." },
                options: { type: "array", items: {}, description: "Selectable options for char/choose/multiple question types." },
                max    : { type: "number", description: "Optional max display size for choose/multiple." },
                help   : { type: "string", description: "Optional help text." },
                output : { type: "string", description: "Optional output mode. Set to 'index' to return indexes instead of values." }
              },
              required : ["name"]
            }
          }
        },
        allOf: [
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["ask", "question", "secret", "password", "encrypt", "char", "ask1", "choose", "multiple", "multi"] } } },
            then: { required: ["prompt"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["char", "ask1", "choose", "multiple", "multi"] } } },
            then: { required: ["options"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["struct", "form"] } } },
            then: { required: ["questions"] }
          }
        ]
      }
    },
    showMessage: {
      name       : "showMessage",
      description: "Display a message to the user during execution — before the final answer. Use this for progress updates, status notifications, important findings, or any output the user should see immediately in real time. Supports levels: info (cyan), warn (yellow), error (red), success (green), debug (faint). Optionally provide a title to print a bold header line above the message.",
      inputSchema: {
        type      : "object",
        properties: {
          message: { type: "string", description: "The message text to display." },
          level  : {
            type       : "string",
            description: "Display level controlling color and prefix. Default: 'info'.",
            enum       : ["info", "warn", "error", "success", "debug"],
            default    : "info"
          },
          title  : { type: "string", description: "Optional bold header printed above the message." }
        },
        required: ["message"]
      }
    },
    markdownFiles: {
      name       : "markdownFiles",
      description: "Read-only markdown helper limited to *.md files inside the configured root. " +
        "Call with operation='list' (no path) to discover all available documentation files and their relative paths. " +
        "Use operation='read' with a relative path returned by 'list' to read a specific file. " +
        "Use operation='search' with a pattern to find content across all markdown files.",
      inputSchema: {
        type      : "object",
        properties: {
          operation    : {
            type       : "string",
            description: "Operation type: 'list' to enumerate markdown files, 'search' to find content, or 'read' to read a specific file.",
            enum       : markdownOps,
            default    : "list"
          },
          path         : { type: "string", description: "Relative path within the root: a directory for list/search, or a markdown file path (from a previous 'list' result) for read." },
          recursive    : { type: "boolean", description: "Traverse subdirectories for list/search operations." },
          includeHidden: { type: "boolean", description: "Include hidden files/directories in list/search operations." },
          pattern      : { type: "string", description: "Pattern to find when operation=search." },
          regex        : { type: "boolean", description: "Treat search pattern as regular expression." },
          caseSensitive: { type: "boolean", description: "Case-sensitive matching for search." },
          maxResults   : { type: "number", description: "Maximum number of matches for search (0 means unlimited)." },
          encoding     : { type: "string", description: "Character encoding for read operation." },
          lineStart    : { type: "number", description: "One-based start line for read operation." },
          lineEnd      : { type: "number", description: "One-based end line for read operation." },
          maxLines     : { type: "number", description: "Maximum lines to read for read operation." },
          lineSeparator: { type: "string", description: "Line separator used when joining lines for read operation." },
          countLines   : { type: "boolean", description: "Return total line count for read operation." },
          compact      : { type: "boolean", description: "Return compact responses to reduce token usage." }
        },
        allOf: [
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["search"] } } },
            then: { required: ["pattern"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["read", "get", "view", "cat"] } } },
            then: { required: ["path"] }
          }
        ]
      }
    },
    skills: {
      name       : "skills",
      description: "Discover and use existing skills from configured skill directories. Start with operation='list', use operation='read' to inspect a skill template, and operation='invoke' to render a skill with arguments and get a canonical invocation string.",
      inputSchema: {
        type      : "object",
        properties: {
          operation    : {
            type       : "string",
            description: "Operation type: list/search/read/render/invoke (aliases: get/view/cat, use/expand/apply, run).",
            enum       : skillOps,
            default    : "list"
          },
          name         : { type: "string", description: "Skill name for read/render/invoke operations." },
          query        : { type: "string", description: "Search query for operation=search." },
          args         : { type: "string", description: "Raw argument string for render/invoke operations." },
          argv         : { type: "array", items: { type: "string" }, description: "Explicit argument array for render/invoke operations (overrides parsed args parsing)." },
          includeHidden: { type: "boolean", description: "Include hidden files/folders during skill discovery." },
          compact      : { type: "boolean", description: "Return compact responses to reduce token usage." }
        },
        allOf: [
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["search"] } } },
            then: { required: ["query"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["read", "get", "view", "cat", "render", "use", "expand", "apply", "invoke", "run"] } } },
            then: { required: ["name"] }
          }
        ]
      }
    },
    wiki: {
      name       : "wiki",
      description: "Interact with the wiki knowledge base. Use operation='list' to browse pages, 'read' to get a page, 'search' to find pages by keyword, 'write' to create/update a page, 'delete' to remove a page (requires wikiaccess=rw), 'lint' to validate wiki health, and 'init' to create AGENTS.md and index.md if they don't exist (requires wikiaccess=rw).",
      inputSchema: {
        type      : "object",
        properties: {
          operation: {
            type       : "string",
            description: "Operation: list, read, search, write, delete, lint, init (aliases: get/view/cat for read; find for search; validate/check for lint; save/put/create/update for write; remove/rm for delete).",
            enum       : ["list", "read", "search", "write", "delete", "lint", "init", "get", "view", "cat", "find", "validate", "check", "save", "put", "create", "update", "remove", "rm"],
            default    : "list"
          },
          path     : { type: "string", description: "Page path for read/write/delete operations, or path prefix for list." },
          query    : { type: "string", description: "Search query for operation=search." },
          content  : { type: "string", description: "Raw markdown content for operation=write." },
          limit    : { type: "number", description: "Maximum results for search." },
          staleDays: { type: "number", description: "Override stale threshold in days for lint." },
          compact  : { type: "boolean", description: "Return compact responses to reduce token usage." }
        },
        allOf: [
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["read", "get", "view", "cat"] } } },
            then: { required: ["path"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["search", "find"] } } },
            then: { required: ["query"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["write", "save", "put", "create", "update"] } } },
            then: { required: ["path", "content"] }
          },
          {
            if  : { required: ["operation"], properties: { operation: { enum: ["delete", "remove", "rm"] } } },
            then: { required: ["path"] }
          }
        ]
      }
    }
  }
})()

MiniUtilsTool.getMetadataByFn = function() {
  return MiniUtilsTool._metadataByFn || {}
}

MiniUtilsTool.getExposedMethodNames = function() {
  var metadata = MiniUtilsTool.getMetadataByFn()
  return Object.keys(metadata)
}