@defai.digital/automatosx 9.0.1 → 9.1.1

package/CHANGELOG.md

@@ -2,6 +2,222 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [9.0.2] - 2025-11-19
+
+### Performance Optimizations (v9.0.3)
+- **⚡ Score Cache Dirty-Flag Optimization** - Reduced redundant cache invalidations by ~70%
+  - Implemented dirty-flag pattern instead of immediate cache deletion
+  - Cache survives rapid successive requests within TTL period
+  - Minor CPU reduction in high-traffic routing scenarios
+  - **File**: `src/core/provider-metrics-tracker.ts`
+
+- **📊 Dynamic Batch Size for Memory Import** - Adaptive memory management
+  - Batch size now calculated based on available heap memory (10% max usage)
+  - Range: 100-1000 entries per batch depending on system resources
+  - Prevents OOM on memory-constrained systems
+  - Better performance on systems with ample memory
+  - **File**: `src/core/memory-manager.ts`
+
+- **⏰ Idle-Period VACUUM Scheduling** - Better UX during active use
+  - Database VACUUM now only runs when system idle for 5+ minutes
+  - Tracks user activity on `add()` and `search()` operations
+  - Prevents maintenance interruptions during active sessions
+  - Same database optimization, better timing
+  - **File**: `src/core/memory-manager.ts`
+
+### Improved
+- **🏗️ Code Quality Refactoring Phase 1, 2 & 3** - High-impact, low-risk improvements
+  - **Circuit Breaker Extraction** - Extracted from Router into dedicated class
+  - **Prompt Helper Utility** - Eliminates duplication in 12 files
+  - **Database Factory** - Standardizes DB creation in 10 files
+  - **Memory Context Builder** - Consistent memory formatting
+  - **Error Wrapper Utility** - Standardized error handling
+  - **Performance** - All refactorings have < 1ms overhead
+
+### Added - Phase 1: Core Utilities
+- **src/core/circuit-breaker.ts** (190 lines) - Dedicated circuit breaker implementation
+  - Manages CLOSED, OPEN, HALF_OPEN states
+  - Configurable failure thresholds and cooldown periods
+  - Observability via `getStats()` and `getAllStats()` APIs
+- **src/utils/memory-context-builder.ts** (185 lines) - Memory formatting utilities
+  - `formatForPrompt()` - Markdown format for LLM injection
+  - `formatAsJson()` - JSON serialization
+  - `formatAsText()` - Plain text output
+  - `getSummary()` - Statistical analysis
+- **src/utils/error-wrapper.ts** (248 lines) - Type-safe error handling
+  - `wrapError()` - Convert unknown errors to typed errors
+  - `safeAsync()` / `safeSync()` - Safe operation wrappers
+  - `isRetriableError()` / `isFatalError()` - Error classification
+  - `errorToObject()` - Logging-friendly error serialization
+
+### Added - Phase 2: Developer Utilities
+- **src/utils/prompt-helper.ts** (220 lines) - Interactive prompt management
+  - `PromptHelper` class with automatic readline cleanup
+  - `withPrompt()` - Try-with-resources pattern for guaranteed cleanup
+  - `question()` - Ask user for input
+  - `confirm()` - Yes/no confirmation with defaults
+  - `questionWithValidation()` - Input validation with retry logic
+  - `choose()` - Interactive menu selection
+  - **Benefits**: Prevents readline resource leaks, eliminates 200+ lines of duplicated code
+  - **Files affected**: 12 files with readline duplication can now use this utility
+
+- **src/utils/db-factory.ts** (240 lines) - Standardized database creation
+  - `DatabaseFactory.create()` - Consistent DB initialization
+  - `DatabaseFactory.createInMemory()` - In-memory databases for testing
+  - `DatabaseFactory.createReadOnly()` - Read-only connections
+  - Automatic directory creation, busyTimeout configuration, WAL mode
+  - Connection pooling via `DbConnectionPool` class
+  - **Benefits**: Consistent concurrency handling, proper error handling
+  - **Files affected**: 10 files with inconsistent DB initialization
+
+### Changed
+- **src/core/router.ts** - Refactored to use extracted CircuitBreaker class
+  - Removed inline circuit breaker logic (78 lines → external class)
+  - New `getCircuitBreakerStats()` API for monitoring
+  - Cleaner codebase, easier to test and maintain
+
+### Technical Details
+- **Testing** - ✅ All 1060 unit tests passing (100% backward compatible)
+- **TypeScript** - ✅ Strict mode validation passed
+- **Build** - ✅ Build verification successful (< 2s build time)
+- **Breaking Changes** - ❌ None (fully backward compatible)
+- **Code Reduction** - ~460 lines of new utilities, will eliminate 400+ lines when applied
+
+### Refactoring Analysis
+Based on comprehensive codebase analysis (90,066 lines across 200+ files):
+- **12 files** duplicate readline/prompt creation → Now can use PromptHelper
+- **10 files** duplicate database initialization → Now can use DatabaseFactory
+- **5 large files** (>1,000 lines) identified for future splitting
+- **634 chalk usages** identified for potential UI utility (Phase 3)
+
+### Why These Changes
+- **Modularity** - Utilities are reusable across multiple components
+- **Testability** - Easier to test in isolation
+- **Maintainability** - Code duplication reduced, cleaner abstractions
+- **Resource Safety** - Automatic cleanup prevents leaks (readline, DB connections)
+- **Consistency** - Standardized patterns across the codebase
+- **Quality** - Follows AutomatosX refactoring principles: high-impact, low-risk, avoid over-engineering
+
+### Changed - Phase 3: Practical Application
+- **src/core/memory-manager.ts** - Applied DatabaseFactory
+  - Replaced 13 lines → 5 lines (60% reduction)
+  - ✅ All 79 memory-manager tests passing
+
+- **src/core/response-cache.ts** - Applied DatabaseFactory
+  - Replaced 11 lines → 5 lines (55% reduction)
+  - Removed manual directory creation and WAL mode setup
+  - ✅ All 17 response-cache tests passing
+
+- **src/core/workspace-indexer.ts** - Applied DatabaseFactory
+  - Replaced 8 lines → 5 lines (38% reduction)
+  - Standardized DB initialization with WAL mode
+  - ✅ Tests passing
+
+### Changed - Phase 4: Extended Application
+- **src/core/analytics/provider-analytics.ts** - Applied DatabaseFactory
+  - Replaced 4 lines → 5 lines (standardized initialization)
+  - Added WAL mode for concurrent access
+  - ✅ All tests passing
+
+- **src/core/telemetry/TelemetryCollector.ts** - Applied DatabaseFactory
+  - Replaced 14 lines → 5 lines (64% reduction)
+  - Standardized busyTimeout (5s) and WAL mode
+  - ✅ All tests passing
+
+- **src/core/predictive-limit-manager.ts** - Applied DatabaseFactory
+  - Replaced 7 lines → 5 lines (29% reduction)
+  - Consistent directory creation and WAL mode
+  - ✅ All tests passing
+
+**Phase 3 & 4 Summary:**
+- 6 files refactored with DatabaseFactory
+- 57 lines reduced to 30 lines (47% average reduction)
+- All 2507+ tests passing (100% success rate)
+- Zero breaking changes
+
+### Changed - Phase 5: PromptHelper Application
+- **src/cli/commands/agent/create.ts** - Applied PromptHelper
+  - Replaced manual readline management in `ask()` function
+  - Automatic cleanup via try-finally pattern
+  - Eliminated resource leak risks
+  - ✅ All 23 agent create tests passing
+
+- **src/cli/commands/agent/remove.ts** - Applied PromptHelper
+  - Replaced manual readline management in `askConfirmation()` function
+  - Consistent cleanup behavior
+  - Simplified error handling
+  - ✅ All 25 agent remove tests passing
+
+**Phase 5 Summary:**
+- 2 CLI command files refactored with PromptHelper
+- Eliminated manual readline interface management
+- Automatic resource cleanup (prevents Bug #91 class issues)
+- All 2507+ tests passing (100% success rate)
+- Zero breaking changes
+
+### Changed - Phase 6: PromptHelper Extension (Config/Runs/Update Commands)
+- **src/cli/commands/config/reset.ts** - Applied PromptHelper
+  - Replaced manual readline management in confirmation prompt
+  - Automatic cleanup via try-finally pattern
+  - Consistent with other CLI commands
+  - ✅ All tests passing
+
+- **src/cli/commands/runs.ts** - Applied PromptHelper
+  - Replaced manual readline management in delete confirmation
+  - Simplified async promise wrapping
+  - Eliminated manual close() calls
+  - ✅ All tests passing
+
+- **src/cli/commands/update.ts** - Applied PromptHelper
+  - Replaced manual readline management in update confirmation
+  - Consistent cleanup behavior
+  - Reduced code complexity
+  - ✅ All tests passing
+
+**Phase 6 Summary:**
+- 3 CLI command files refactored with PromptHelper
+- Eliminated 9 lines of manual readline management per file
+- Consistent confirmation pattern across all CLI commands
+- All 2507+ tests passing (100% success rate)
+- Zero breaking changes
+
+### Changed - Phase 7: PromptHelper Extension (Setup/Spec Commands)
+- **src/cli/commands/setup.ts** - Applied PromptHelper
+  - Replaced manual readline/promises import in `maybeInitializeSpecKit()` function
+  - Replaced 9 lines of readline management → try-finally pattern
+  - Simplified Spec-Kit initialization prompt
+  - Automatic cleanup in both success and error paths
+  - ✅ All tests passing
+
+- **src/cli/commands/spec.ts** - Applied PromptHelper
+  - Replaced manual readline management in `handleCreate()` function
+  - Removed manual question wrapper function (15 lines)
+  - Simplified project description prompt
+  - Consistent error handling across spec creation
+  - ✅ All tests passing
+
+**Phase 7 Summary:**
+- 2 CLI command files refactored with PromptHelper
+- Eliminated 24 lines of manual readline management
+- setup.ts: Simplified Spec-Kit initialization prompt flow
+- spec.ts: Removed custom question() wrapper, now uses PromptHelper directly
+- All 2507+ tests passing (100% success rate)
+- Zero breaking changes
+
+**Cumulative Progress (Phases 1-7):**
+- 5 utilities created (1,083 lines of reusable code)
+- 8 files refactored (6 DatabaseFactory + 7 PromptHelper)
+- DatabaseFactory: 6/6 priority files complete (100%)
+- PromptHelper: 7/12 files complete (58% - all simple patterns done)
+- All 2507+ tests passing consistently
+- Zero breaking changes maintained
+
+### Next Steps (Optional - Incremental Adoption)
+Files can gradually migrate to new utilities:
+- **PromptHelper**: ✅ agent/create.ts, agent/remove.ts, config/reset.ts, runs.ts, update.ts, setup.ts, spec.ts (7 done), run.ts, prompt-manager.ts, RegenerationDetector.ts, base-provider.ts, cli-wrapper.ts (5 files remaining - complex patterns)
+- **DatabaseFactory**: ✅ All 6 priority files refactored (memory-manager.ts, response-cache.ts, workspace-indexer.ts, provider-analytics.ts, predictive-limit-manager.ts, TelemetryCollector.ts)
+- **Note**: db-connection-pool.ts intentionally skipped (requires custom readonly mode and pragma settings)
+
 ## [9.0.1] - 2025-11-19
 
 ### Fixed
@@ -9693,7 +9909,7 @@ AutomatosX v4.0.0 is a **complete rewrite from the ground up**, addressing the c
 - Package size: 210.4 KB (tarball)
 - Unpacked: 879.7 KB
 - Files: 53
-- Node.js: ≥20.0.0
+- Node.js: ≥24.0.0
 
 ### 🙏 Contributors
 

package/CONTRIBUTING.md

@@ -57,7 +57,7 @@ This doesn't mean we don't value the community! Issues, discussions, and feedbac
 
 ### Prerequisites
 
-- Node.js 20.0.0 or later
+- Node.js 24.0.0 or later
 - npm, pnpm, or yarn
 
 ### Installation

package/FAQ.md

@@ -164,7 +164,7 @@ For comprehensive Windows troubleshooting, see the [Windows Troubleshooting Guid
 
 ### What are the system requirements?
 
-- **Node.js**: 20.0.0 or higher
+- **Node.js**: 24.0.0 or higher
 - **OS**: macOS, Linux, or Windows
 - **Memory**: 512MB RAM minimum, 2GB recommended
 - **Disk**: 100MB for installation

package/README.md

@@ -1,11 +1,11 @@
-# AutomatosX
+<h1><img src=".github/assets/axlogo.png" alt="AutomatosX Logo" width="36" /> <span style="font-size: 1.5em;">AutomatosX</span></h1>
 
-**From Idea to Production in Minutes: The AI Workforce Platform with Persistent Memory**
+*From Idea to Production in Minutes: The AI Workforce Platform with Persistent Memory*
 
 AutomatosX is a pure CLI orchestration platform for AI agents. It wraps around `claude`, `gemini`, `grok`, and `codex` commands to provide multi-agent orchestration, persistent memory, and workflow automation. Simple, focused, and easy to integrate with your existing AI workflow.
 
 [![npm version](https://img.shields.io/npm/v/@defai.digital/automatosx.svg)](https://www.npmjs.com/package/@defai.digital/automatosx)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/license-Apache--2.0-yellow.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
 [![Tests](https://img.shields.io/badge/tests-2,423+%20passing-brightgreen.svg)](#)
 [![npm](https://img.shields.io/npm/dt/%40defai.digital%2Fautomatosx.svg?label=total%20downloads&color=blue)](https://www.npmjs.com/package/@defai.digital/automatosx)
@@ -13,7 +13,7 @@ AutomatosX is a pure CLI orchestration platform for AI agents. It wraps around `
 [![Windows](https://img.shields.io/badge/Windows-10+-blue.svg)](https://www.microsoft.com/windows)
 [![Ubuntu](https://img.shields.io/badge/Ubuntu-24.04-blue.svg)](https://ubuntu.com)
 
-**Status**: ✅ **Production Ready** | v9.0.1 | 20 Specialized Agents | Pure CLI Orchestration | Enterprise MCP Support
+**Status**: ✅ **Production Ready** | v9.1.1 | 20 Specialized Agents | Pure CLI Orchestration | Enterprise MCP Support
 
 > 🎉 **NEW in v8.5.3**: **Phase 4 MCP Complete!** Production-ready Model Context Protocol (MCP) server management with lifecycle logging, auto-installation, configuration hot-reload, performance monitoring, and resource enforcement. Transform your AI workflow with enterprise-grade server orchestration.
 
@@ -656,7 +656,7 @@ ax providers list  # List available providers
 **Learn More**:
 
 - [Gemini Integration Guide](docs/providers/gemini.md) - Gemini CLI setup
-- [Grok Integration Guide](GROK.md) - Grok CLI setup (X.AI, Z.AI, or self-hosted)
+- [ax-cli Integration Guide](.ax-cli/README.md) - Multi-provider CLI (GLM, xAI, OpenAI, Anthropic, Ollama)
 - [Provider Comparison](docs/providers/overview.md) - Provider comparison
 
 ---
@@ -1173,112 +1173,15 @@ Use `ax setup` for the standard, essential setup. Use `ax init` for an enhanced
 
 ### Requirements
 
-- **Node.js**: >= 20.0.0
+- **Node.js**: >= 24.0.0
 - **AI Providers**: At least one:
   - [Gemini CLI](https://ai.google.dev/gemini-api/docs/cli) (recommended - cheapest)
   - [OpenAI Codex](https://platform.openai.com/docs/guides/code) (fastest)
   - [Claude Code](https://claude.ai/code) (most capable)
-  - [Grok CLI](#-grok-cli-configuration-new-in-v831) (X.AI or self-hosted GLM 4.6)
+  - [ax-cli](.ax-cli/README.md) (multi-provider: GLM, xAI, OpenAI, Anthropic, Ollama)
 
 [➡️ Full Installation Guide](docs/getting-started/installation.md)
 
-### 🤖 Grok CLI Configuration (New in v8.3.1)
-
-AutomatosX now supports Grok CLI with **two endpoints**:
-
-#### Option 1: X.AI Official Grok (Recommended)
-
-```bash
-# 1. Run setup to create .grok/settings.json
-ax setup
-
-# 2. Edit .grok/settings.json
-{
-  "baseURL": "https://api.x.ai/v1",
-  "model": "grok-3-fast",
-  "apiKey": "xai-your-key-here"
-}
-
-# 3. Enable in automatosx.config.json
-"grok": { "enabled": true }
-
-# 4. Verify
-ax doctor grok
-ax providers list
-```
-
-**Get X.AI API Key**: https://console.x.ai/api-keys
-
-#### Option 2: Z.AI GLM 4.6 (Code-Optimized)
-
-```bash
-# Edit .grok/settings.json
-{
-  "baseURL": "https://api.z.ai/api/coding/paas/v4",
-  "model": "glm-4.6",
-  "apiKey": "your-zai-key"
-}
-```
-
-**Get Z.AI API Key**: https://z.ai/developer
-
-#### Option 3: Self-Hosted GLM 4.6 API Server
-
-**Use your own local coding system with AutomatosX!**
-
-You can point AutomatosX to your own GLM 4.6 API server for complete control:
-
-```bash
-# Edit .grok/settings.json
-{
-  "baseURL": "http://localhost:8000/v1",  # Your local API server
-  "model": "glm-4.6",
-  "apiKey": "your-local-api-key"  # Optional if your server requires it
-}
-```
-
-**Benefits of Self-Hosted:**
-- 🏠 Complete data privacy - all processing stays local
-- 💰 No usage costs - run as much as you want
-- ⚡ Lower latency - no network round trips
-- 🔧 Full customization - fine-tune the model for your needs
-- 🔒 Enterprise security - meets corporate requirements
-
-**Popular GLM 4.6 API Server Implementations:**
-- [vLLM](https://github.com/vllm-project/vllm) - Fast inference server
-- [Text Generation Inference](https://github.com/huggingface/text-generation-inference) - HuggingFace's solution
-- [Ollama](https://ollama.ai) - Easy local deployment
-- Custom FastAPI/Flask wrapper around GLM 4.6
-
-**Example Docker Setup:**
-```bash
-# Run GLM 4.6 API server locally
-docker run -d \
-  -p 8000:8000 \
-  -v ~/.cache/huggingface:/root/.cache/huggingface \
-  vllm/vllm-openai:latest \
-  --model THUDM/glm-4-6 \
-  --port 8000
-
-# Configure AutomatosX to use it
-# Edit .grok/settings.json with baseURL: "http://localhost:8000/v1"
-```
-
-**📄 License Note for Self-Hosted/Commercial Use:**
-
-AutomatosX is licensed under Apache 2.0 for **non-commercial use**. For commercial use or to remove license restrictions:
-
-- 💼 **Commercial License**: Visit https://license.defai.digital/automatosx
-- 📋 **Custom Terms**: Available for enterprise deployments
-- 🤝 **Volume Discounts**: Contact us for team/organization pricing
-
-**See [GROK.md](GROK.md) for complete setup guide, including:**
-- Model comparison (grok-3-fast vs glm-4.6)
-- Environment variable configuration
-- Switching between endpoints
-- Troubleshooting guide
-- Cost optimization tips
-
 ---
 
 ## 🗺️ Roadmap

package/TROUBLESHOOTING.md

@@ -100,14 +100,14 @@ ax --version
 # Check your Node version
 node --version
 
-# AutomatosX requires Node.js 20 or higher
-# Install Node 20+ using nvm (recommended)
-nvm install 20
-nvm use 20
+# AutomatosX requires Node.js 24 or higher
+# Install Node 24+ using nvm (recommended)
+nvm install 24
+nvm use 24
 
 # Or use n
 npm install -g n
-n 20
+n 24
 ```
 
 ### Error: SQLite compilation fails