Merge pull request #71 from OpenAF/codex/improve-function-names-and-descriptions

Rename MCP utility tool methods for clarity

Author: nmaguiar

AGENTS.md

@@ -19,7 +19,7 @@ Automated tests exist for utility modules under `tests/`. Run the mini-a-utils t
 For core agent behavior, validate by scripting representative goals (see `USAGE.md`) and capture the agent transcript with `debug=true`. When adding MCP integrations, run the corresponding `mcp-*.yaml` job standalone before wiring it into Mini-A. Document manual verification steps in the PR description, and note any scenarios not exercised.
 
 Current test coverage includes:
-- **File Operations**: init, readFile, writeFile, listDirectory, searchContent, getFileInfo, deleteFile, fileOps, fileModify, path security
+- **File Operations**: init, readFile, writeFile, listDirectory, searchContent, getFileInfo, deleteFile, filesystemQuery, filesystemModify, path security
 - **Mathematical Operations**: calculate (add, subtract, multiply, divide, power, sqrt, abs, round), statistics (mean, median, min, max, sum, count), unit conversions, random generation (integer, sequence, choice, boolean, hex)
 - **Time Operations**: current time with timezone/format options, timezone conversions, sleep functionality
 - **Advanced Parameters**: UTF-8 encoding, createMissingDirs, contentLength reporting, append flags

USAGE.md

@@ -390,7 +390,7 @@ If every stage returns an empty list (or errors), Mini-A logs the issue and fall
 #### Libraries and Extensions
 - **`libs`** (string): Comma-separated list of additional OpenAF libraries to load
 - **`useutils`** (boolean, default: false): Auto-register the Mini File Tool utilities as a dummy MCP server for quick file operations
-  - Exposes three streamlined actions: `init` (configure the working root and permissions), `fileQuery` (read/list/search/info via the `operation` field), and `fileModify` (write/append/delete with `operation` plus required `content` or `confirm` flags)
+  - Exposes three streamlined actions: `init` (configure the working root and permissions), `filesystemQuery` (read/list/search/info via the `operation` field), and `filesystemModify` (write/append/delete with `operation` plus required `content` or `confirm` flags)
 
 #### Conversation Management
 - **`conversation`** (string): Path to file for loading/saving conversation history
@@ -400,7 +400,7 @@ If every stage returns an empty list (or errors), Mini-A logs the issue and fall
 - **`mode`** (string): Shortcut for loading a preset argument bundle from [`mini-a-modes.yaml`](mini-a-modes.yaml) or `~/.openaf-mini-a_modes.yaml` (custom modes override built-in ones). Presets are merged before explicit flags, so command-line overrides always win. Bundled configurations include:
   - `shell` – Enables read-only shell access.
   - `shellrw` – Enables shell access with write permissions (`readwrite=true`).
-  - `shellutils` – Adds the Mini File Tool helpers as an MCP (`useutils=true usetools=true`) exposing `init`, `fileQuery`, and `fileModify` actions.
+  - `shellutils` – Adds the Mini File Tool helpers as an MCP (`useutils=true usetools=true`) exposing `init`, `filesystemQuery`, and `filesystemModify` actions.
   - `chatbot` – Switches to conversational mode (`chatbotmode=true`).
   - `web` – Optimizes for the browser UI with MCP tools registered (`usetools=true`).
   - `webfull` – Turns on diagrams, charts, ASCII sketches, attachments, history retention, and planning for the web UI (`usetools=true usediagrams=true usecharts=true useascii=true usehistory=true useattach=true historykeep=true useplanning=true`).

mini-a-con.js

@@ -66,7 +66,7 @@ try {
   var consoleReader         = __
   var commandHistory        = __
   var lastConversationStats = __
-  var slashCommands         = ["help", "set", "toggle", "unset", "show", "reset", "last", "clear", "context", "compact", "history", "exit", "quit"]
+  var slashCommands         = ["help", "set", "toggle", "unset", "show", "reset", "last", "clear", "context", "compact", "summarize", "history", "exit", "quit"]
   var resumeConversation    = parseBoolean(findArgumentValue(args, "resume")) === true
   var conversationArgValue  = findArgumentValue(args, "conversation")
   var initialConversationPath = isString(conversationArgValue) && conversationArgValue.trim().length > 0
@@ -500,6 +500,22 @@ try {
     }
   }
 
+  function summarize(ctx) {
+    if (!isObject(activeAgent) || typeof activeAgent.summarizeText !== "function") {
+      return ctx.substring(0, 400)
+    }
+
+    try {
+      var summaryResponse = activeAgent.summarizeText(ctx, { verbose: false })
+      if (isString(summaryResponse) && summaryResponse.trim().length > 0) {
+        return summaryResponse.trim()
+      }
+    } catch (summarizeError) {
+      printErr(ansiColor("ITALIC," + errorColor, "!!") + colorifyText(" Summarization failed: " + summarizeError, errorColor))
+    }
+    return ctx.substring(0, 400)
+  }
+
   function compactConversationContext(preserveCount) {
     var stats = refreshConversationStats(activeAgent)
     if (!isObject(stats) || !isArray(stats.entries) || stats.entries.length === 0) {
@@ -588,6 +604,68 @@ try {
     }
   }
 
+  function summarizeConversation(preserveCount) {
+    // First, compact the conversation
+    compactConversationContext(preserveCount)
+
+    // Then generate and display a user-friendly summary of the entire conversation
+    var stats = refreshConversationStats(activeAgent)
+    if (!isObject(stats) || !isArray(stats.entries) || stats.entries.length === 0) {
+      print(colorifyText("No conversation to summarize.", hintColor))
+      return
+    }
+
+    if (!isObject(activeAgent) || typeof activeAgent.summarizeText !== "function") {
+      print(colorifyText("No active agent available. Run a goal first to enable summarization.", hintColor))
+      return
+    }
+
+    var conversationText = []
+    stats.entries.forEach(function(entry) {
+      var role = isString(entry.role) ? entry.role.toUpperCase() : "UNKNOWN"
+      var content = flattenConversationContent(entry.content)
+      conversationText.push(`${role}: ${content}`)
+    })
+
+    var conversationPayload = conversationText.join("\n")
+
+    if (conversationPayload.trim().length === 0) {
+      print(colorifyText("No conversation content to summarize.", hintColor))
+      return
+    }
+
+    try {
+      print(colorifyText("Generating conversation summary...", hintColor))
+      var instructionText = "You are summarizing a conversation between a user and an AI assistant. Provide a clear, concise summary that:\n1) Identifies the main topics discussed\n2) Highlights key decisions or outcomes\n3) Notes any unresolved questions or next steps\n\nFormat the summary in a readable way with bullet points where appropriate."
+
+      var fullSummary = activeAgent.summarizeText(conversationPayload, {
+        verbose: false,
+        instructionText: instructionText
+      })
+
+      if (isString(fullSummary) && fullSummary.trim().length > 0) {
+        print()
+        print(colorifyText("=".repeat(60), accentColor))
+        print(colorifyText("Conversation Summary", "BOLD," + accentColor))
+        print(colorifyText("=".repeat(60), accentColor))
+        print()
+        var _m = jsonParse(fullSummary)
+        if (isMap(_m) && isString(_m.answer)) _m.answer = ow.format.withMD(_m.answer)
+        print(isObject(_m) ? printTree(_m) : ow.format.withMD(fullSummary.trim()))
+        print()
+        print(colorifyText("=".repeat(60), accentColor))
+      } else {
+        print(colorifyText("Unable to generate summary. Response was: " + stringify(fullSummary), errorColor))
+        print(colorifyText("Conversation payload length: " + conversationPayload.length + " characters", hintColor))
+      }
+    } catch (summaryError) {
+      printErr(ansiColor("ITALIC," + errorColor, "!!") + colorifyText(" Failed to generate conversation summary: " + summaryError, errorColor))
+      if (isDef(summaryError.stack)) {
+        print(colorifyText("Stack trace: " + summaryError.stack, errorColor))
+      }
+    }
+  }
+
   function resetOptions() {
     var opts = {}
     Object.keys(parameterDefinitions).forEach(function(key) {
@@ -997,6 +1075,7 @@ try {
       "  " + colorifyText("/clear", "BOLD") + colorifyText("              Reset the ongoing conversation", hintColor),
       "  " + colorifyText("/context", "BOLD") + colorifyText("            Visualize conversation/context size", hintColor),
       "  " + colorifyText("/compact", "BOLD") + colorifyText(" [n]        Summarize old context, keep last n messages", hintColor),
+      "  " + colorifyText("/summarize", "BOLD") + colorifyText(" [n]      Compact and display an LLM-generated conversation summary", hintColor),
       "  " + colorifyText("/history", "BOLD") + colorifyText(" [n]        Show the last n conversation turns", hintColor),
       "  " + colorifyText("/exit", "BOLD") + colorifyText("               Leave the console", hintColor)
     ]
@@ -1094,6 +1173,20 @@ try {
         }
         continue
       }
+      if (command === "summarize") {
+        summarizeConversation()
+        continue
+      }
+      if (command.indexOf("summarize ") === 0) {
+        var keepValue = command.substring(10).trim()
+        var parsedKeep = parseInt(keepValue, 10)
+        if (isNaN(parsedKeep)) {
+          print(colorifyText("Usage: /summarize [messagesToKeep]", errorColor))
+        } else {
+          summarizeConversation(parsedKeep)
+        }
+        continue
+      }
       if (command === "history") {
         printConversationHistory()
         continue

mini-a-utils.js

@@ -616,7 +616,7 @@ MiniUtilsTool.prototype.deleteFile = function(params) {
   }
 }
 
-MiniUtilsTool.prototype.fileOps = function(params) {
+MiniUtilsTool.prototype.filesystemQuery = function(params) {
   var payload = isObject(params) ? params : {}
   var opValue = payload.operation
   var normalized = isString(opValue) && opValue.trim().length > 0 ? opValue.trim().toLowerCase() : "read"
@@ -641,7 +641,7 @@ MiniUtilsTool.prototype.fileOps = function(params) {
   var target = map[normalized]
   if (!target && isString(opValue) && isFunction(this[opValue])) target = opValue
   if (!target) {
-    return "[ERROR] Unknown file query operation: " + (isString(opValue) ? opValue : normalized)
+    return "[ERROR] Unknown filesystem query operation: " + (isString(opValue) ? opValue : normalized)
   }
 
   var innerParams = {}
@@ -654,15 +654,15 @@ MiniUtilsTool.prototype.fileOps = function(params) {
   try {
     var handler = this[target]
     if (!isFunction(handler)) {
-      return "[ERROR] Unsupported file query handler: " + target
+      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.fileModify = function(params) {
+MiniUtilsTool.prototype.filesystemModify = function(params) {
   var payload = isObject(params) ? params : {}
   var opValue = payload.operation
   if (!isString(opValue) || opValue.trim().length === 0) {
@@ -682,7 +682,7 @@ MiniUtilsTool.prototype.fileModify = function(params) {
   var target = map[normalized]
   if (!target && isString(opValue) && isFunction(this[opValue])) target = opValue
   if (!target) {
-    return "[ERROR] Unknown file modify operation: " + opValue
+    return "[ERROR] Unknown filesystem modify operation: " + opValue
   }
 
   var innerParams = {}
@@ -698,7 +698,7 @@ MiniUtilsTool.prototype.fileModify = function(params) {
   try {
     var handler = this[target]
     if (!isFunction(handler)) {
-      return "[ERROR] Unsupported file modify handler: " + target
+      return "[ERROR] Unsupported filesystem modify handler: " + target
     }
     return handler.call(this, innerParams)
   } catch (e) {
@@ -708,7 +708,7 @@ MiniUtilsTool.prototype.fileModify = function(params) {
 
 /**
  * <odoc>
- * <key>MiniUtilsTool.mathOps(params) : Object</key>
+ * <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).
@@ -718,7 +718,7 @@ MiniUtilsTool.prototype.fileModify = function(params) {
  * - For random: `type` (integer, sequence, choice, boolean, hex), type-specific params (min/max, items, count, seed, etc.)
  * </odoc>
  */
-MiniUtilsTool.prototype.mathOps = function(params) {
+MiniUtilsTool.prototype.mathematics = function(params) {
   params = params || {}
   var op = (params.operation || "calculate").toLowerCase()
 
@@ -859,7 +859,7 @@ MiniUtilsTool.prototype.mathOps = function(params) {
 
 /**
  * <odoc>
- * <key>MiniUtilsTool.timeOps(params) : Object</key>
+ * <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.
@@ -868,7 +868,7 @@ MiniUtilsTool.prototype.mathOps = function(params) {
  * - For sleep: `milliseconds` (required)
  * </odoc>
  */
-MiniUtilsTool.prototype.timeOps = function(params) {
+MiniUtilsTool.prototype.timeUtilities = function(params) {
   params = params || {}
   var op = (params.operation || "current-time").toLowerCase()
 
@@ -938,8 +938,8 @@ MiniUtilsTool._metadataByFn = (function() {
   var modifyDeleteOps = ["delete", "remove", "rm", "deletefile"]
   var modifyAllOps = modifyWriteOps.concat(modifyDeleteOps)
 
-  var mathOps = ["calculate", "statistics", "convert-unit", "convert", "random"]
-  var timeOps = ["current-time", "current", "timezone-convert", "sleep"]
+  var mathOperationTypes = ["calculate", "statistics", "convert-unit", "convert", "random"]
+  var timeOperationTypes = ["current-time", "current", "timezone-convert", "sleep"]
 
   return {
     init: {
@@ -953,9 +953,9 @@ MiniUtilsTool._metadataByFn = (function() {
         }
       }
     },
-    fileOps: { // Suggested name change for clarity
-      name       : "fileOps",
-      description: "Perform various operations on files and directories within the configured root, including reading, listing, searching, and retrieving information.",
+    filesystemQuery: {
+      name       : "filesystemQuery",
+      description: "Execute read-only filesystem actions such as reading file contents, listing directories, searching text, or retrieving metadata within the configured root.",
       inputSchema: {
         type      : "object",
         properties: {
@@ -990,9 +990,9 @@ MiniUtilsTool._metadataByFn = (function() {
         ]
       }
     },
-    fileModify: { // Suggested name change for clarity
-      name       : "fileModify",
-      description: "Modify files and directories by writing, appending, or deleting them (requires readwrite=true for modifications).",
+    filesystemModify: {
+      name       : "filesystemModify",
+      description: "Perform write, append, or delete operations on files and directories within the configured root (requires readwrite=true).",
       inputSchema: {
         type      : "object",
         properties: {
@@ -1022,16 +1022,16 @@ MiniUtilsTool._metadataByFn = (function() {
         ]
       }
     },
-    mathOps: {
-      name       : "mathOps",
-      description: "Perform mathematical operations including calculations, statistics, unit conversions, and random number generation.",
+    mathematics: {
+      name       : "mathematics",
+      description: "Run mathematical utilities including arithmetic calculations, descriptive statistics, unit conversions, and random value generation.",
       inputSchema: {
         type      : "object",
         properties: {
           operation: {
             type       : "string",
             description: "Operation type: calculate, statistics, convert-unit, or random.",
-            enum       : mathOps,
+            enum       : mathOperationTypes,
             default    : "calculate"
           },
           op           : { type: "string", description: "Math operation for calculate: add, subtract, multiply, divide, power, sqrt, abs, round." },
@@ -1057,16 +1057,16 @@ MiniUtilsTool._metadataByFn = (function() {
         required : []
       }
     },
-    timeOps: {
-      name       : "timeOps",
-      description: "Perform time and timezone operations including getting current time, timezone conversions, and sleep.",
+    timeUtilities: {
+      name       : "timeUtilities",
+      description: "Work with time by returning the current time, converting between time zones, or pausing execution.",
       inputSchema: {
         type      : "object",
         properties: {
           operation     : {
             type       : "string",
             description: "Operation type: current-time, convert, or sleep.",
-            enum       : timeOps,
+            enum       : timeOperationTypes,
             default    : "current-time"
           },
           timezone       : { type: "string", description: "IANA timezone identifier (e.g., 'America/New_York', 'Europe/London')." },