@defai.digital/ax-cli 3.6.1 → 3.7.1

package/README.md

@@ -1,7 +1,7 @@
 # AX CLI - Enterprise-Class CLI for GenAI coding
 
 [![npm](https://img.shields.io/npm/dt/@defai.digital/ax-cli?style=flat-square&logo=npm&label=downloads)](https://npm-stat.com/charts.html?package=%40defai.digital%2Fax-cli)
-[![Tests](https://img.shields.io/badge/tests-1381%20passing-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli/actions/workflows/test.yml)
+[![Tests](https://img.shields.io/badge/tests-1497%20passing-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli/actions/workflows/test.yml)
 [![Coverage](https://img.shields.io/badge/coverage-98%2B%25-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9%2B-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D24.0.0-blue?style=flat-square)](https://nodejs.org/)
@@ -44,7 +44,7 @@ ax-cli
   - 200K context window, 128K max output capability
   - 30% more token efficient than GLM 4.5
   - Optimized for complex code generation and refactoring
-- **🎯 Multi-Phase Task Planner** (NEW in v3.0.0): Intelligent task decomposition for complex requests
+- **🎯 Multi-Phase Task Planner**: Intelligent task decomposition for complex requests
   - Automatic complexity detection (57 keyword patterns)
   - LLM-based plan generation with phases and dependencies
   - Phase-by-phase execution with progress tracking
@@ -64,18 +64,24 @@ ax-cli
 - **✅ Production-Ready**: 98%+ test coverage, TypeScript strict mode, Zod validation
 - **🎯 Interactive & Headless**: Chat interface or one-shot commands
 - **📝 Smart Project Init**: Automatic project analysis and custom instructions
-- **🧠 Project Memory** (NEW): Intelligent context caching for z.ai GLM-4.6
+- **🧠 Project Memory**: Intelligent context caching for z.ai GLM-4.6
   - Automatic project scanning and context generation
   - z.ai implicit caching support (50% token savings on repeated context)
   - Cache statistics tracking and efficiency monitoring
-- **🏥 Health Check** (NEW): Comprehensive diagnostics with `ax-cli doctor`
+- **🏥 Health Check**: Comprehensive diagnostics with `ax-cli doctor`
   - Verify configuration, API connectivity, and dependencies
   - Detailed error messages with actionable suggestions
-- **💬 Dual-Model Mode** (NEW): Use different models for chat vs coding
+- **🎨 Smart Verbosity Control**: Multi-level output for optimal UX
+  - **Quiet mode** (default): Groups tool operations → 85% less noise
+  - **Concise mode**: One line per tool execution
+  - **Verbose mode**: Full details for debugging
+  - Press `Ctrl+O` to cycle between levels
+  - Auto-expands errors with full details
+- **💬 Dual-Model Mode**: Use different models for chat vs coding
   - Configure chat and coding models separately
   - Manual model switching with `--chat-mode` flag
   - Optimize cost and performance for different task types
-- **🌐 Web Search** (NEW in v3.4.0): Real-time package search capabilities
+- **🌐 Web Search**: Real-time package search capabilities
   - **Works out-of-the-box**: npm, PyPI, and crates.io package search (no API keys required)
   - **Intelligent routing**: Automatically selects the best engine based on query intent
     - JavaScript/Node.js packages → npm registry search
@@ -85,7 +91,7 @@ ax-cli
   - Support for package discovery, dependency research, and version information
   - Session-based context for iterative package exploration
 - **🔄 Auto-Update**: Built-in update checker and installer
-- **🔒 Enterprise-Grade Security** (NEW in v3.6.0): **FREE & Open Source**
+- **🔒 Enterprise-Grade Security**: **FREE & Open Source**
   - **Command Injection Protection**: CVSS 9.8 CRITICAL fix - Safe command execution with whitelisting
   - **Path Traversal Hardening**: CVSS 8.6 HIGH fix - Prevent unauthorized file system access
   - **SSRF Attack Prevention**: CVSS 7.5 HIGH fix - Validate MCP transport URLs and block private IPs
@@ -107,7 +113,7 @@ ax-cli
   - **SSO/SAML Integration**: Enterprise identity provider support
   - **Priority Support**: 24-hour SLA email support
   - 📧 **Contact sales@defai.digital** for enterprise licensing and pricing
-- **📊 Advanced Code Analysis** (NEW in v2.4.0): Professional-grade static analysis tools
+- **📊 Advanced Code Analysis**: Professional-grade static analysis tools
   - **Dependency Analyzer**: Detect circular dependencies, calculate coupling metrics, identify orphan and hub files
   - **Code Smell Detector**: Find 10+ anti-patterns (long methods, large classes, duplicates, dead code, etc.)
   - **Hotspot Analyzer**: Identify frequently changing, complex code using git history analysis
@@ -135,6 +141,71 @@ AX CLI uses **industry-standard max tokens** based on research of leading AI cod
 
 [View all features →](docs/features.md)
 
+## 🎉 What's New in v3.7.0
+
+**SDK Best Practices & Developer Experience** - Major improvements to the programmatic SDK API:
+
+### ✨ New Features
+
+- **🔒 Structured Error System**: Programmatic error handling with `SDKError` and error codes
+  ```typescript
+  try {
+    const agent = await createAgent();
+  } catch (error) {
+    if (SDKError.isSDKError(error)) {
+      switch (error.code) {
+        case SDKErrorCode.SETUP_NOT_RUN:
+          console.log('Run: ax-cli setup');
+          break;
+      }
+    }
+  }
+  ```
+
+- **✅ Input Validation**: Zod schema validation prevents invalid configurations
+  - Validates `maxToolRounds` (1-1000, must be integer)
+  - Rejects NaN, negative values, unknown properties
+  - Clear validation error messages
+
+- **🧪 Testing Utilities**: Built-in mocks for easier testing
+  ```typescript
+  import { createMockAgent } from '@defai.digital/ax-cli/sdk/testing';
+
+  const agent = createMockAgent(['Response 1', 'Response 2']);
+  const result = await agent.processUserMessage('Test');
+  ```
+
+- **🛡️ Disposal Protection**: Prevents use-after-disposal bugs
+  - Throws `AGENT_DISPOSED` error if agent used after `dispose()`
+  - Idempotent disposal (safe to call multiple times)
+
+- **📊 SDK Version Tracking**: Version info for debugging and compatibility
+  ```typescript
+  import { SDK_VERSION, getSDKInfo } from '@defai.digital/ax-cli/sdk';
+
+  console.log('SDK Version:', SDK_VERSION); // "3.7.0"
+  ```
+
+- **🐛 Debug Mode**: Verbose logging for troubleshooting
+  ```typescript
+  const agent = await createAgent({
+    maxToolRounds: 50,
+    debug: true  // Logs agent creation, tool calls, results
+  });
+  ```
+
+### 🔧 Improvements
+
+- **Enhanced Disposal**: Comprehensive cleanup of listeners, caches, and history
+- **Better Documentation**: Fixed outdated examples, added error handling patterns
+- **Type Safety**: Full TypeScript support with proper type exports
+
+### 📦 Breaking Changes
+
+**None!** All changes are backward compatible.
+
+---
+
 ## 📦 Installation
 
 ### Supported Platforms
@@ -228,7 +299,7 @@ ax-cli -c
 /commit-and-push   # AI-powered git commit
 /exit              # Exit application
 
-# Multi-Phase Planner commands (NEW in v3.0.0):
+# Multi-Phase Planner commands:
 /plans             # List all execution plans
 /plan              # Show current plan details
 /phases            # Show phase progress
@@ -244,7 +315,7 @@ AX CLI supports powerful keyboard shortcuts for enhanced productivity:
 
 | Shortcut | Action | Description |
 |----------|--------|-------------|
-| **Ctrl+O** | Toggle verbose mode | Default: concise single-line output. Verbose: full details, diffs, file contents |
+| **Ctrl+O** | Cycle verbosity | Quiet (grouped) → Concise (per-tool) → Verbose (full details) → Quiet |
 | **Ctrl+B** | Background mode | Move running command to background, or toggle "always background" mode |
 | **Ctrl+K** | Quick actions | Open quick actions menu |
 | **Shift+Tab** | Auto-edit mode | Toggle automatic approval for all operations |
@@ -253,6 +324,11 @@ AX CLI supports powerful keyboard shortcuts for enhanced productivity:
 | **Ctrl+A/E** | Cursor | Move to line start/end |
 | **Ctrl+W** | Delete word | Delete word before cursor |
 
+**Verbosity Levels** (Ctrl+O to cycle):
+- **Quiet** (default): Groups operations → `⏺ Working on app.ts (3 edits, 5 reads) ✓ 2.3s`
+- **Concise**: One line per tool → `⏺ Read (app.ts) ✓ 22 lines`
+- **Verbose**: Full details → Shows args, outputs, diffs, timings
+
 ### 🔄 Background Tasks
 
 Run long-running commands in the background (like Claude Code's Ctrl+B):
@@ -285,7 +361,7 @@ ax-cli -p "write tests for utils/" --max-tool-rounds 50
 ax-cli -p "refactor" --model glm-4.6
 ```
 
-### 🔌 VSCode Integration (NEW!)
+### 🔌 VSCode Integration
 
 AX CLI integrates seamlessly with Visual Studio Code via tasks and keyboard shortcuts:
 
@@ -479,7 +555,7 @@ The interactive terminal shows a character counter `[count/2000]` with color-cod
 | **Yellow** | 1600-1999 | ⚠️ Consider using files |
 | **Red** | 2000+ | ❌ Use file-based workflow |
 
-## 🏥 Health Check & Diagnostics (NEW)
+## 🏥 Health Check & Diagnostics
 
 Run comprehensive diagnostics to verify your AX CLI configuration:
 
@@ -503,7 +579,7 @@ The `doctor` command checks:
 - ✓ MCP server configuration
 - ✓ Dependencies (ripgrep, git)
 
-## 💬 Dual-Model Mode (NEW)
+## 💬 Dual-Model Mode
 
 Use different models for chat vs coding tasks to optimize performance and cost:
 
@@ -554,7 +630,7 @@ ax-cli --chat-mode
 - ⚡ **Better performance**: Match model capability to task complexity
 - 🎯 **Manual control**: You decide when to use each model
 
-## 🌐 Web Search (NEW)
+## 🌐 Web Search
 
 Search package registries for JavaScript, Python, and Rust packages with intelligent language detection and cross-registry comparison.
 
@@ -888,7 +964,7 @@ ax-cli mcp remove linear
 
 [MCP Integration Guide →](docs/mcp.md)
 
-## 🧠 Project Memory (NEW)
+## 🧠 Project Memory
 
 Project Memory enables intelligent context caching for z.ai GLM-4.6, reducing token costs and improving response consistency:
 
@@ -1102,6 +1178,43 @@ AX CLI implements enterprise-grade architecture with:
 - Eliminated false confidence from placeholder tests
 - Maintained 98%+ test coverage with genuine validation
 
+### v3.7.1 (2025-11-22)
+
+**Bug Fixes - Critical Stability Improvements:**
+- Fixed crash on malformed LLM responses: Added try-catch to `parseToolArgumentsCached` in LLMAgent
+  - Prevents agent crash when LLM sends invalid JSON in tool arguments
+  - Returns empty object instead of throwing, allowing session to continue
+  - Affects ~1 in 1000 tool calls based on observed LLM behavior
+- Fixed memory leak in BashTool: Added dispose() method
+  - Properly terminates running bash processes on cleanup
+  - Removes all event listeners to prevent accumulation
+  - Fixes resource leak from orphaned process handles
+- Fixed agent disposal: Added tool cleanup cascade
+  - Agent now calls bash.dispose() during cleanup
+  - Ensures all tool resources are properly released
+
+**Bug Fixes - Performance & Memory:**
+- Fixed unbounded cache growth in `toolCallArgsCache`
+  - Limited to 500 entries with LRU eviction (oldest 100)
+  - Prevents 5+ MB memory leak per 10,000 tool calls
+  - Applied to both LLMAgent and Subagent classes
+- Fixed resource leak in bash abort handler
+  - Cleanup listener now called even when moveToBackground() fails
+  - Prevents event listener memory leaks
+- Updated MCPManager to use singleton TokenCounter
+  - Saves 100-200ms initialization time
+  - Shares tiktoken encoder instance across MCP operations
+
+**Test Results:**
+- All 1,497 tests passing (9 skipped)
+- 98.29% test coverage maintained
+- Zero breaking changes
+
+**Combined Performance Gains:**
+- Startup: 245-495ms faster (30-50% improvement)
+- Runtime: 70-150ms faster per session
+- Memory: Bounded, predictable usage with no leaks
+
 ### v3.5.2 (2025-11-22)
 
 **Bug Fixes - Resource Leak Prevention:**
@@ -1138,5 +1251,5 @@ Built with **AutomatosX** multi-agent orchestration to achieve enterprise-class
 ---
 
 <p align="center">
-  Made with ❤️ by <a href="https://github.com/defai-digital">DefAI Digital</a>
+  Made with ❤️ by <a href="https://github.com/defai-digital">DEFAI Digital</a>
 </p>

package/config-defaults/settings.yaml

@@ -58,6 +58,30 @@ ui:
   status_update_interval: 2000  # 2 seconds
   processing_timer_interval: 1000  # 1 second
 
+  # Verbosity Level Configuration
+  # Controls how much detail is shown for tool executions
+  #
+  # Levels:
+  # - quiet (0): Group consecutive operations, show summaries only
+  #   Example: "Working on app.ts (3 edits, 5 reads) ✓ 2.3s"
+  #   Best for: Regular coding work, focusing on results
+  #
+  # - concise (1): One line per tool execution
+  #   Example: "⏺ Read (app.ts) ✓ 22 lines read"
+  #   Best for: Debugging tool execution order
+  #
+  # - verbose (2): Full details with arguments and outputs
+  #   Example: Full args, outputs, diffs, execution timings
+  #   Best for: Deep debugging, understanding AI behavior
+  #
+  # Default: quiet (best user experience, minimal noise)
+  verbosity_level: quiet  # Options: quiet | concise | verbose
+
+  # Tool Grouping Settings (applies to quiet mode)
+  group_tool_calls: true  # Enable/disable tool call grouping
+  max_group_size: 20  # Max operations per group before splitting
+  group_time_window: 500  # Max milliseconds between operations to group
+
 token:
   tokens_per_message: 3
   tokens_for_reply_priming: 3

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

@@ -48,8 +48,8 @@ export declare class LLMAgent extends EventEmitter {
     private todoTool;
     private search;
     private webSearch;
-    private architectureTool;
-    private validationTool;
+    private _architectureTool?;
+    private _validationTool?;
     private chatHistory;
     private messages;
     private tokenCounter;
@@ -68,6 +68,8 @@ export declare class LLMAgent extends EventEmitter {
     private samplingConfig;
     /** Thinking/reasoning mode configuration */
     private thinkingConfig;
+    /** Track if agent has been disposed */
+    private disposed;
     constructor(apiKey: string, baseURL?: string, model?: string, maxToolRounds?: number);
     private initializeCheckpointManager;
     private initializeMCP;
@@ -94,6 +96,11 @@ export declare class LLMAgent extends EventEmitter {
      * Get current sampling configuration
      */
     getSamplingConfig(): SamplingConfig | undefined;
+    /**
+     * Apply context pruning to both messages and chatHistory
+     * BUGFIX: Prevents chatHistory from growing unbounded
+     */
+    private applyContextPruning;
     /**
      * Check if agent is running in deterministic mode
      */
@@ -104,6 +111,16 @@ export declare class LLMAgent extends EventEmitter {
      * Used specifically for isRepetitiveToolCall to avoid redundant parsing
      */
     private parseToolArgumentsCached;
+    /**
+     * Lazy-loaded getter for ArchitectureTool
+     * Only instantiates when first accessed to reduce startup time
+     */
+    private get architectureTool();
+    /**
+     * Lazy-loaded getter for ValidationTool
+     * Only instantiates when first accessed to reduce startup time
+     */
+    private get validationTool();
     /**
      * Detect if a tool call is repetitive (likely causing a loop)
      * Returns true if the same tool with similar arguments was called multiple times recently
@@ -281,9 +298,37 @@ export declare class LLMAgent extends EventEmitter {
         filesCreated?: string[];
         error?: string;
     }>>;
+    /**
+     * Check if agent has been disposed
+     * @internal
+     */
+    private checkDisposed;
     /**
      * Dispose of resources and remove event listeners
-     * Call this when the agent is no longer needed
+     *
+     * This method should be called when the agent is no longer needed to prevent
+     * memory leaks and properly close all connections.
+     *
+     * After calling dispose(), the agent cannot be used anymore. Any method calls
+     * will throw an AGENT_DISPOSED error.
+     *
+     * Cleans up:
+     * - Event listeners
+     * - In-memory caches (tool calls, arguments)
+     * - Token counter and context manager
+     * - Aborts in-flight requests
+     * - Terminates subagents
+     * - Clears conversation history
+     *
+     * @example
+     * ```typescript
+     * const agent = await createAgent();
+     * try {
+     *   await agent.processUserMessage('task');
+     * } finally {
+     *   agent.dispose();  // Always cleanup
+     * }
+     * ```
      */
     dispose(): void;
 }