@zds-ai/cli 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 A conversational AI CLI tool powered by Grok with intelligent text editor capabilities and tool usage.
 
-<img width="980" height="435" alt="Screenshot 2025-07-21 at 13 35 41" src="https://github.com/user-attachments/assets/192402e3-30a8-47df-9fc8-a084c5696e78" />
+<img width="720" height="528" alt="Image" src="https://github.com/user-attachments/assets/f697a273-141e-4f02-8c15-37143aa7ec0e" />
 
 ## Features
 
@@ -22,6 +22,26 @@ A conversational AI CLI tool powered by Grok with intelligent text editor capabi
 - GROK API key from X.AI
 - (Optional, Recommended) Morph API key for Fast Apply editing
 
+### System Dependencies
+
+zai-cli requires the following system tools for certain features:
+
+- **ripgrep** (required for search functionality)
+  - macOS: `brew install ripgrep`
+  - Ubuntu/Debian: `apt install ripgrep`
+  - Windows: `choco install ripgrep` or download from [releases](https://github.com/BurntSushi/ripgrep/releases)
+  - Other platforms: See [ripgrep installation guide](https://github.com/BurntSushi/ripgrep#installation)
+
+- **Python 3 with openpyxl** (optional, required for XLSX file reading)
+  - Install: `pip3 install openpyxl` or `python3 -m pip install openpyxl`
+  - Most systems already have Python 3 installed
+
+- **exiftool** (optional, required for PNG metadata extraction)
+  - macOS: `brew install exiftool`
+  - Ubuntu/Debian: `apt install libimage-exiftool-perl`
+  - Windows: Download from [exiftool.org](https://exiftool.org/)
+  - Other platforms: See [exiftool installation guide](https://exiftool.org/install.html)
+
 ### Global Installation (Recommended)
 
 ```sh
@@ -49,52 +69,52 @@ bun link
 1. Get your GROK API key from [X.AI](https://x.ai)
 
 2. Set up your API key (choose one method):
-
-**Method 1: Environment Variable**
-
-```sh
-export GROK_API_KEY=your_api_key_here
-```
-
-**Method 2: .env File**
-
-```sh
-cp .env.example .env
-# Edit .env and add your API key
-```
-
-**Method 3: Command Line Flag**
-
-```sh
-zai-cli --api-key your_api_key_here
-```
-
-**Method 4: User Settings File**
-
-Create `~/.grok/user-settings.json`:
-
-```json
-{
-  "apiKey": "your_api_key_here"
-}
-```
+    
+    **Method 1: Environment Variable**
+    
+    ```sh
+    export GROK_API_KEY=your_api_key_here
+    ```
+    
+    **Method 2: .env File**
+    
+    ```sh
+    cp .env.example .env
+    # Edit .env and add your API key
+    ```
+    
+    **Method 3: Command Line Flag**
+    
+    ```sh
+    zai-cli --api-key your_api_key_here
+    ```
+    
+    **Method 4: User Settings File**
+    
+    Create `~/.grok/user-settings.json`:
+    
+    ```json
+    {
+      "apiKey": "your_api_key_here"
+    }
+    ```
 
 3. (Optional, Recommended) Get your Morph API key from [Morph Dashboard](https://morphllm.com/dashboard/api-keys)
 
 4. Set up your Morph API key for Fast Apply editing (choose one method):
 
-**Method 1: Environment Variable**
-
-```sh
-export MORPH_API_KEY=your_morph_api_key_here
-```
-
-**Method 2: .env File**
-
-```sh
-# Add to your .env file
-MORPH_API_KEY=your_morph_api_key_here
-```
+    **Method 1: Environment Variable**
+    
+    ```sh
+    export MORPH_API_KEY=your_morph_api_key_here
+    ```
+    
+    **Method 2: .env File**
+    
+    ```sh
+    # Add to your .env file
+    MORPH_API_KEY=your_morph_api_key_here
+    ```
 
 ### Custom Base URL (Optional)
 

package/dist/agent/grok-agent.d.ts

@@ -61,7 +61,7 @@ export declare class GrokAgent extends EventEmitter {
     private activeTaskAction;
     private activeTaskColor;
     private apiKeyEnvVar;
-    private pendingContextEdit;
+    private pendingContextEditSession;
     constructor(apiKey: string, baseURL?: string, model?: string, maxToolRounds?: number, debugLogFile?: string, startupHookOutput?: string, temperature?: number, maxTokens?: number);
     private startupHookOutput?;
     private systemPrompt;
@@ -119,12 +119,12 @@ export declare class GrokAgent extends EventEmitter {
     getActiveTask(): string;
     getActiveTaskAction(): string;
     getActiveTaskColor(): string;
-    setPendingContextEdit(tmpJsonPath: string, contextFilePath: string): void;
-    getPendingContextEdit(): {
+    setPendingContextEditSession(tmpJsonPath: string, contextFilePath: string): void;
+    getPendingContextEditSession(): {
         tmpJsonPath: string;
         contextFilePath: string;
     } | null;
-    clearPendingContextEdit(): void;
+    clearPendingContextEditSession(): void;
     setPersona(persona: string, color?: string): Promise<{
         success: boolean;
         error?: string;

package/dist/agent/grok-agent.js

@@ -9,6 +9,67 @@ import { EventEmitter } from "events";
 import { createTokenCounter } from "../utils/token-counter.js";
 import { getSettingsManager } from "../utils/settings-manager.js";
 import { executeOperationHook, executeToolApprovalHook, applyHookCommands } from "../utils/hook-executor.js";
+// Interval (ms) between token count updates when streaming
+const TOKEN_UPDATE_INTERVAL_MS = 250;
+// Minimum delay (in ms) applied when stopping a task to ensure smooth UI/UX.
+const MINIMUM_STOP_TASK_DELAY_MS = 3000;
+// Maximum number of attempts to parse nested JSON strings in executeTool
+const MAX_JSON_PARSE_ATTEMPTS = 5;
+/**
+ * Threshold used to determine whether an AI response is "substantial" (in characters).
+ */
+const SUBSTANTIAL_RESPONSE_THRESHOLD = 50;
+/**
+ * Extracts the first complete JSON object from a string.
+ * Handles duplicate/concatenated JSON objects (LLM bug) like: {"key":"val"}{"key":"val"}
+ * @param jsonString The string potentially containing concatenated JSON objects
+ * @returns The first complete JSON object, or the original string if no duplicates found
+ */
+function extractFirstJsonObject(jsonString) {
+    if (!jsonString.includes('}{'))
+        return jsonString;
+    try {
+        // Find the end of the first complete JSON object
+        let depth = 0;
+        let firstObjEnd = -1;
+        for (let i = 0; i < jsonString.length; i++) {
+            if (jsonString[i] === "{")
+                depth++;
+            if (jsonString[i] === "}") {
+                depth--;
+                if (depth === 0) {
+                    firstObjEnd = i + 1;
+                    break;
+                }
+            }
+        }
+        if (firstObjEnd > 0 && firstObjEnd < jsonString.length) {
+            // Extract and validate first object
+            const firstObj = jsonString.substring(0, firstObjEnd);
+            JSON.parse(firstObj); // Validate it's valid JSON
+            return firstObj;
+        }
+    }
+    catch {
+        // If extraction fails, return the original string
+    }
+    return jsonString;
+}
+/**
+ * Cleans up LLM-generated JSON argument strings for tool calls.
+ * Removes duplicate/concatenated JSON objects and trims.
+ * @param args The raw arguments string from the tool call
+ * @returns Cleaned and sanitized argument string
+ */
+function sanitizeToolArguments(args) {
+    let argsString = args?.trim() || "{}";
+    // Handle duplicate/concatenated JSON objects (LLM bug)
+    const extractedArgsString = extractFirstJsonObject(argsString);
+    if (extractedArgsString !== argsString) {
+        argsString = extractedArgsString;
+    }
+    return argsString;
+}
 export class GrokAgent extends EventEmitter {
     grokClient;
     textEditor;
@@ -44,7 +105,7 @@ export class GrokAgent extends EventEmitter {
     activeTaskAction = "";
     activeTaskColor = "white";
     apiKeyEnvVar = "GROK_API_KEY";
-    pendingContextEdit = null;
+    pendingContextEditSession = null;
     constructor(apiKey, baseURL, model, maxToolRounds, debugLogFile, startupHookOutput, temperature, maxTokens) {
         super();
         const manager = getSettingsManager();
@@ -350,33 +411,7 @@ Current working directory: ${process.cwd()}`;
                     // Clean up tool call arguments before adding to conversation history
                     // This prevents Ollama from rejecting malformed tool calls on subsequent API calls
                     const cleanedToolCalls = assistantMessage.tool_calls.map(toolCall => {
-                        let argsString = toolCall.function.arguments?.trim() || "{}";
-                        // Handle duplicate/concatenated JSON objects (LLM bug)
-                        if (argsString.includes('}{')) {
-                            try {
-                                let depth = 0;
-                                let firstObjEnd = -1;
-                                for (let i = 0; i < argsString.length; i++) {
-                                    if (argsString[i] === '{')
-                                        depth++;
-                                    if (argsString[i] === '}') {
-                                        depth--;
-                                        if (depth === 0) {
-                                            firstObjEnd = i + 1;
-                                            break;
-                                        }
-                                    }
-                                }
-                                if (firstObjEnd > 0 && firstObjEnd < argsString.length) {
-                                    const firstObj = argsString.substring(0, firstObjEnd);
-                                    JSON.parse(firstObj); // Validate
-                                    argsString = firstObj; // Use cleaned version
-                                }
-                            }
-                            catch (e) {
-                                // Keep original if cleaning fails
-                            }
-                        }
+                        let argsString = sanitizeToolArguments(toolCall.function.arguments);
                         return {
                             ...toolCall,
                             function: {
@@ -546,8 +581,8 @@ Current working directory: ${process.cwd()}`;
                     // - A structured response format that explicitly marks completion
                     // For now, we break immediately after a substantial response to avoid
                     // the cascade of duplicate responses caused by "give it one more chance" logic.
-                    // If the AI provided a substantial response (>50 chars), task is complete
-                    if (assistantMessage.content && assistantMessage.content.trim().length > 50) {
+                    // If the AI provided a substantial response (>SUBSTANTIAL_RESPONSE_THRESHOLD chars), task is complete
+                    if (assistantMessage.content && assistantMessage.content.trim().length > SUBSTANTIAL_RESPONSE_THRESHOLD) {
                         break; // Task complete - bot gave a full response
                     }
                     // Short/empty response, give AI another chance
@@ -847,7 +882,7 @@ Current working directory: ${process.cwd()}`;
                             };
                             // Emit token count update
                             const now = Date.now();
-                            if (now - lastTokenUpdate > 250) {
+                            if (now - lastTokenUpdate > TOKEN_UPDATE_INTERVAL_MS) {
                                 lastTokenUpdate = now;
                                 yield {
                                     type: "token_count",
@@ -875,33 +910,7 @@ Current working directory: ${process.cwd()}`;
                 // Clean up tool call arguments before adding to conversation history
                 // This prevents Ollama from rejecting malformed tool calls on subsequent API calls
                 const cleanedToolCalls = accumulatedMessage.tool_calls?.map(toolCall => {
-                    let argsString = toolCall.function.arguments?.trim() || "{}";
-                    // Handle duplicate/concatenated JSON objects (LLM bug)
-                    if (argsString.includes('}{')) {
-                        try {
-                            let depth = 0;
-                            let firstObjEnd = -1;
-                            for (let i = 0; i < argsString.length; i++) {
-                                if (argsString[i] === '{')
-                                    depth++;
-                                if (argsString[i] === '}') {
-                                    depth--;
-                                    if (depth === 0) {
-                                        firstObjEnd = i + 1;
-                                        break;
-                                    }
-                                }
-                            }
-                            if (firstObjEnd > 0 && firstObjEnd < argsString.length) {
-                                const firstObj = argsString.substring(0, firstObjEnd);
-                                JSON.parse(firstObj); // Validate
-                                argsString = firstObj; // Use cleaned version
-                            }
-                        }
-                        catch (e) {
-                            // Keep original if cleaning fails
-                        }
-                    }
+                    let argsString = sanitizeToolArguments(toolCall.function.arguments);
                     return {
                         ...toolCall,
                         function: {
@@ -1178,41 +1187,16 @@ Current working directory: ${process.cwd()}`;
             // Handle duplicate/concatenated JSON objects (LLM bug)
             // Pattern: {"key":"val"}{"key":"val"}
             let hadDuplicateJson = false;
-            if (argsString.includes('}{')) {
-                try {
-                    // Find the end of the first complete JSON object
-                    let depth = 0;
-                    let firstObjEnd = -1;
-                    for (let i = 0; i < argsString.length; i++) {
-                        if (argsString[i] === '{')
-                            depth++;
-                        if (argsString[i] === '}') {
-                            depth--;
-                            if (depth === 0) {
-                                firstObjEnd = i + 1;
-                                break;
-                            }
-                        }
-                    }
-                    if (firstObjEnd > 0 && firstObjEnd < argsString.length) {
-                        // Extract and validate first object
-                        const firstObj = argsString.substring(0, firstObjEnd);
-                        JSON.parse(firstObj); // Validate it's valid JSON
-                        // Use only the first object
-                        hadDuplicateJson = true;
-                        argsString = firstObj;
-                    }
-                }
-                catch (e) {
-                    // If extraction fails, continue with original string
-                    // The error will be caught by the main JSON.parse below
-                }
+            const extractedArgsString = extractFirstJsonObject(argsString);
+            if (extractedArgsString !== argsString) {
+                hadDuplicateJson = true;
+                argsString = extractedArgsString;
             }
             let args = JSON.parse(argsString);
             // Handle multiple layers of JSON encoding (API bug)
             // Keep parsing until we get an object, not a string
             let parseCount = 0;
-            while (typeof args === 'string' && parseCount < 5) {
+            while (typeof args === 'string' && parseCount < MAX_JSON_PARSE_ATTEMPTS) {
                 parseCount++;
                 try {
                     args = JSON.parse(args);
@@ -1561,14 +1545,14 @@ Current working directory: ${process.cwd()}`;
     getActiveTaskColor() {
         return this.activeTaskColor;
     }
-    setPendingContextEdit(tmpJsonPath, contextFilePath) {
-        this.pendingContextEdit = { tmpJsonPath, contextFilePath };
+    setPendingContextEditSession(tmpJsonPath, contextFilePath) {
+        this.pendingContextEditSession = { tmpJsonPath, contextFilePath };
     }
-    getPendingContextEdit() {
-        return this.pendingContextEdit;
+    getPendingContextEditSession() {
+        return this.pendingContextEditSession;
     }
-    clearPendingContextEdit() {
-        this.pendingContextEdit = null;
+    clearPendingContextEditSession() {
+        this.pendingContextEditSession = null;
     }
     async setPersona(persona, color) {
         // Execute hook if configured
@@ -1908,7 +1892,7 @@ Current working directory: ${process.cwd()}`;
         }
         // Calculate remaining time to meet 3-second minimum
         const elapsed = Date.now() - startTime;
-        const minimumDelay = 3000;
+        const minimumDelay = MINIMUM_STOP_TASK_DELAY_MS;
         const remainingDelay = Math.max(0, minimumDelay - elapsed);
         // Wait for remaining time if needed
         if (remainingDelay > 0) {
@@ -2410,7 +2394,7 @@ Current working directory: ${process.cwd()}`;
                     this.emit('modelChange', { model });
                 }
                 else {
-                    console.warn(`Failed to restore backend: API key not found in environment variable ${state.apiKeyEnvVar}`);
+                    console.warn("Failed to restore backend: API key not found in environment.");
                 }
             }
             catch (error) {