@defai.digital/automatosx 8.2.0 → 8.3.2

package/examples/providers/README.md

@@ -0,0 +1,228 @@
+# Provider Configuration Examples
+
+This directory contains example YAML configurations for AutomatosX providers.
+
+## Available Examples
+
+### Grok Provider
+
+- **`grok-z-ai.yaml`** - Z.AI GLM 4.6 (code-optimized model)
+  - Best for: Development, code generation, technical tasks
+  - Endpoint: `https://api.z.ai/api/coding/paas/v4`
+  - Model: `glm-4.6`
+
+- **`grok-x-ai.yaml`** - X.AI Official Grok Model
+  - Best for: Reasoning, analysis, general chat
+  - Endpoint: `https://api.x.ai/v1`
+  - Model: `grok-beta`
+
+- **`grok-with-mcp.yaml`** - Grok with MCP Tools
+  - Includes: Filesystem, GitHub, Slack, PostgreSQL integrations
+  - Demonstrates: Model Context Protocol (MCP) setup
+  - Requires: MCP server packages installed
+
+### Multi-Provider Setup
+
+- **`multi-provider.yaml`** - Complete multi-provider configuration
+  - Demonstrates: Priority-based routing
+  - Includes: Claude, Gemini, Grok configurations
+  - Shows: Automatic fallback setup
+
+## Quick Start
+
+### 1. Choose a Template
+
+```bash
+# List available examples
+ls examples/providers/
+
+# View example
+cat examples/providers/grok-z-ai.yaml
+```
+
+### 2. Copy to Your Project
+
+```bash
+# Create providers directory
+mkdir -p .automatosx/providers
+
+# Copy template
+cp examples/providers/grok-z-ai.yaml .automatosx/providers/grok.yaml
+```
+
+### 3. Set Environment Variables
+
+```bash
+# For Z.AI
+export GROK_API_KEY="your-z-ai-key"
+
+# For X.AI
+export GROK_API_KEY="xai-your-key"
+
+# For MCP tools (if using)
+export GITHUB_TOKEN="your-github-token"
+```
+
+### 4. Test Configuration
+
+```bash
+# Check provider status
+ax doctor grok
+
+# Test execution
+ax run --provider grok backend "simple task"
+```
+
+## Configuration Priority
+
+When using multiple providers, AutomatosX routes requests based on priority:
+
+```yaml
+# .automatosx/providers/claude.yaml
+provider:
+  priority: 1    # ← Highest priority (tried first)
+
+# .automatosx/providers/gemini.yaml
+provider:
+  priority: 2    # ← Medium priority
+
+# .automatosx/providers/grok.yaml
+provider:
+  priority: 3    # ← Lowest priority (fallback)
+```
+
+**Routing behavior:**
+1. Try highest priority provider (1)
+2. If unavailable/failed → try next (2)
+3. If all fail → try lowest priority (3)
+4. If all exhausted → return error
+
+## Environment Variable Interpolation
+
+All examples use `${VAR_NAME}` syntax for environment variables:
+
+```yaml
+provider:
+  apiKey: ${GROK_API_KEY}           # ← Replaced at runtime
+  baseUrl: https://${API_HOST}/v1    # ← Supports multiple vars
+```
+
+**Benefits:**
+- ✅ Keep secrets out of version control
+- ✅ Easy environment switching (dev/staging/prod)
+- ✅ Works with CI/CD pipelines
+- ✅ Compatible with `.env` files
+
+## Customization
+
+### Adjust Rate Limits
+
+```yaml
+rateLimits:
+  maxRequestsPerMinute: 120        # ← Increase for higher quota
+  maxTokensPerMinute: 200000       # ← Adjust based on plan
+  maxConcurrentRequests: 10        # ← More parallel requests
+```
+
+### Modify Timeouts
+
+```yaml
+provider:
+  timeout: 300000                  # ← 5 minutes for complex tasks
+```
+
+### Add Circuit Breaker
+
+```yaml
+circuitBreaker:
+  failureThreshold: 5              # ← More tolerant
+  resetTimeout: 120000             # ← Longer cooldown
+```
+
+## Advanced Features
+
+### MCP Tools
+
+Enable Model Context Protocol for extended capabilities:
+
+```yaml
+mcp:
+  enabled: true
+  servers:
+    - name: filesystem
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+```
+
+**Available MCP Servers:**
+- `@modelcontextprotocol/server-filesystem` - File operations
+- `@modelcontextprotocol/server-github` - GitHub API
+- `@modelcontextprotocol/server-slack` - Slack integration
+- `@modelcontextprotocol/server-postgres` - Database access
+
+### Custom Morph Agents
+
+Define specialized agents in configuration:
+
+```yaml
+morph:
+  enabled: true
+  agents:
+    - name: security-auditor
+      prompt: "Analyze code for security vulnerabilities"
+      capabilities: ["security", "audit"]
+```
+
+## Troubleshooting
+
+### Provider Not Found
+
+```bash
+# Check file exists
+ls -la .automatosx/providers/grok.yaml
+
+# Verify provider name
+cat .automatosx/providers/grok.yaml | grep "name:"
+# Should show: name: grok
+```
+
+### Environment Variable Not Set
+
+```bash
+# Check variable
+echo $GROK_API_KEY
+
+# Set if missing
+export GROK_API_KEY="your-key"
+
+# Make persistent (add to ~/.bashrc or ~/.zshrc)
+echo 'export GROK_API_KEY="your-key"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### YAML Syntax Error
+
+```bash
+# Validate YAML
+yamllint .automatosx/providers/grok.yaml
+
+# Or use online validator
+# https://www.yamllint.com/
+```
+
+## Documentation
+
+- **Full Documentation**: [docs/providers/grok.md](../../docs/providers/grok.md)
+- **AutomatosX Docs**: [README.md](../../README.md)
+- **Z.AI Docs**: https://docs.z.ai
+- **X.AI Docs**: https://x.ai/api
+
+## Support
+
+- GitHub Issues: https://github.com/defai-digital/automatosx/issues
+- Email: support@defai.digital
+
+---
+
+**Version**: 8.3.0
+**Last Updated**: 2025-11-16

package/examples/providers/grok-with-mcp.yaml

@@ -0,0 +1,86 @@
+# Grok Provider Example - With MCP Tools
+#
+# This example demonstrates using Grok with Model Context Protocol (MCP) tools.
+# MCP enables the model to interact with external systems (filesystem, GitHub, etc.)
+#
+# Usage:
+#   1. Install MCP servers: npm install -g @modelcontextprotocol/server-*
+#   2. Set environment variables: GROK_API_KEY, GITHUB_TOKEN
+#   3. Copy to .automatosx/providers/grok.yaml
+#   4. Run: ax run --provider grok backend "list files in src/"
+
+provider:
+  name: grok
+  enabled: true
+  priority: 2
+  baseUrl: https://api.z.ai/api/coding/paas/v4
+  apiKey: ${GROK_API_KEY}
+  model: glm-4.6
+  timeout: 120000
+  maxRetries: 3
+
+# MCP Tools Configuration
+mcp:
+  enabled: true
+  servers:
+    # Filesystem access (read/write files)
+    - name: filesystem
+      command: npx
+      args:
+        - "-y"
+        - "@modelcontextprotocol/server-filesystem"
+        - "/Users/username/projects"              # Allowed directory
+      env:
+        LOG_LEVEL: info
+
+    # GitHub integration (issues, PRs, repos)
+    - name: github
+      command: npx
+      args:
+        - "-y"
+        - "@modelcontextprotocol/server-github"
+      env:
+        GITHUB_TOKEN: ${GITHUB_TOKEN}           # GitHub personal access token
+        LOG_LEVEL: info
+
+    # Slack integration (optional)
+    # - name: slack
+    #   command: npx
+    #   args:
+    #     - "-y"
+    #     - "@modelcontextprotocol/server-slack"
+    #   env:
+    #     SLACK_TOKEN: ${SLACK_TOKEN}
+    #     LOG_LEVEL: info
+
+    # PostgreSQL database (optional)
+    # - name: postgres
+    #   command: npx
+    #   args:
+    #     - "-y"
+    #     - "@modelcontextprotocol/server-postgres"
+    #   env:
+    #     DATABASE_URL: ${DATABASE_URL}
+    #     LOG_LEVEL: info
+
+# Rate limits
+rateLimits:
+  maxRequestsPerMinute: 60
+  maxTokensPerMinute: 100000
+  maxConcurrentRequests: 5
+
+# Circuit breaker
+circuitBreaker:
+  failureThreshold: 3
+  resetTimeout: 60000
+
+# Metadata
+metadata:
+  version: "1.0.0"
+  description: "Grok with MCP tools for extended capabilities"
+  tags:
+    - grok
+    - mcp
+    - filesystem
+    - github
+  lastUpdated: "2025-11-16T00:00:00Z"

package/examples/providers/grok-x-ai.yaml

@@ -0,0 +1,46 @@
+# Grok Provider Example - X.AI Official Grok Model
+#
+# This example demonstrates using X.AI's official Grok model.
+# Grok is optimized for reasoning, analysis, and general tasks.
+#
+# Usage:
+#   1. Copy to .automatosx/providers/grok.yaml
+#   2. Set GROK_API_KEY environment variable (starts with "xai-")
+#   3. Run: ax doctor grok
+
+provider:
+  # Provider identification
+  name: grok
+  enabled: true
+  priority: 2
+
+  # X.AI endpoint (official Grok model)
+  baseUrl: https://api.x.ai/v1
+  apiKey: ${GROK_API_KEY}                            # X.AI API key (xai-...)
+  model: grok-beta                                    # X.AI Grok model
+
+  # Performance settings (higher timeout for longer context)
+  timeout: 180000                                     # 3 minutes (Grok can be slower)
+  maxRetries: 3
+
+# Rate limiting for X.AI
+rateLimits:
+  maxRequestsPerMinute: 60
+  maxTokensPerMinute: 200000                         # Higher token limit for Grok
+  maxConcurrentRequests: 5
+
+# Circuit breaker
+circuitBreaker:
+  failureThreshold: 3
+  resetTimeout: 60000
+
+# Metadata
+metadata:
+  version: "1.0.0"
+  description: "X.AI Grok configuration for reasoning and analysis"
+  tags:
+    - grok
+    - x-ai
+    - grok-beta
+    - reasoning
+  lastUpdated: "2025-11-16T00:00:00Z"

package/examples/providers/grok-z-ai.yaml

@@ -0,0 +1,50 @@
+# Grok Provider Example - Z.AI GLM 4.6 (Code-Optimized)
+#
+# This example demonstrates using Z.AI's GLM 4.6 model with AutomatosX.
+# GLM 4.6 is optimized for coding tasks and technical work.
+#
+# Usage:
+#   1. Copy to .automatosx/providers/grok.yaml
+#   2. Set GROK_API_KEY environment variable
+#   3. Run: ax doctor grok
+
+provider:
+  # Provider identification
+  name: grok
+  enabled: true
+  priority: 2                                         # 1 = highest priority
+
+  # Z.AI endpoint (code-optimized model)
+  baseUrl: https://api.z.ai/api/coding/paas/v4
+  apiKey: ${GROK_API_KEY}                            # Reference environment variable
+  model: glm-4.6                                      # Code-optimized model
+
+  # Performance settings
+  timeout: 120000                                     # 2 minutes (suitable for most tasks)
+  maxRetries: 3                                       # Retry on transient failures
+
+  # Optional: Custom CLI path (if not in PATH)
+  # customPath: /usr/local/bin/grok
+
+# Rate limiting (recommended for production)
+rateLimits:
+  maxRequestsPerMinute: 60                           # Prevent quota exhaustion
+  maxTokensPerMinute: 100000                         # Token-based limiting
+  maxConcurrentRequests: 5                           # Parallel request limit
+
+# Circuit breaker (prevents cascading failures)
+circuitBreaker:
+  failureThreshold: 3                                # Open circuit after 3 failures
+  resetTimeout: 60000                                # Wait 60s before retry
+  halfOpenTimeout: 30000                             # Test period: 30s
+
+# Metadata (optional, for documentation)
+metadata:
+  version: "1.0.0"
+  description: "Z.AI GLM 4.6 configuration for coding tasks"
+  tags:
+    - grok
+    - z-ai
+    - glm-4.6
+    - code-generation
+  lastUpdated: "2025-11-16T00:00:00Z"

package/examples/providers/grok.yaml

@@ -0,0 +1,120 @@
+# Grok Provider Configuration
+#
+# AutomatosX supports two Grok endpoints:
+# 1. X.AI Official Grok (grok-3-fast) - Default, recommended
+# 2. Z.AI GLM 4.6 (code-optimized) - Alternative for coding tasks
+#
+# Setup Instructions:
+#   1. Choose your endpoint (X.AI or Z.AI) below
+#   2. Set your API key: export GROK_API_KEY="your-key-here"
+#   3. Copy this file to: .automatosx/providers/grok.yaml
+#   4. Enable in automatosx.config.json: "grok": { "enabled": true }
+#   5. Test: ax doctor grok
+
+provider:
+  # Provider identification
+  name: grok
+  enabled: true
+  priority: 4                                         # Priority (1=highest, 4=after Claude/Gemini/OpenAI)
+
+  # ====================================================================
+  # OPTION 1: X.AI Official Grok (grok-3-fast) - DEFAULT
+  # ====================================================================
+  # Fast, efficient model for general reasoning and analysis
+  baseUrl: https://api.x.ai/v1
+  apiKey: ${GROK_API_KEY}                            # Set via: export GROK_API_KEY="xai-..."
+  model: grok-3-fast                                  # Fast model (recommended)
+  # Alternative models:
+  #   - grok-3-fast: Fastest, lowest cost
+  #   - grok-beta: Latest features, higher quality
+  #   - grok-vision-beta: Image understanding
+
+  # ====================================================================
+  # OPTION 2: Z.AI GLM 4.6 (Code-Optimized) - ALTERNATIVE
+  # ====================================================================
+  # Uncomment lines below and comment out X.AI config above to use GLM 4.6
+  # baseUrl: https://api.z.ai/api/coding/paas/v4
+  # apiKey: ${GROK_API_KEY}                          # Set via: export GROK_API_KEY="your-z-ai-key"
+  # model: glm-4.6                                    # Code-optimized model
+
+  # Performance settings
+  timeout: 180000                                     # 3 minutes (adjust based on task complexity)
+  maxRetries: 3                                       # Retry on transient failures
+
+  # Optional: Custom CLI path (if grok not in PATH)
+  # customPath: /usr/local/bin/grok
+
+# Rate limiting (prevents quota exhaustion)
+rateLimits:
+  maxRequestsPerMinute: 60                           # API rate limit
+  maxTokensPerMinute: 200000                         # Token-based limiting (adjust for your plan)
+  maxConcurrentRequests: 5                           # Parallel request limit
+
+# Circuit breaker (prevents cascading failures)
+circuitBreaker:
+  failureThreshold: 3                                # Open circuit after 3 consecutive failures
+  resetTimeout: 60000                                # Wait 60s before retry
+  halfOpenTimeout: 30000                             # Test period: 30s
+
+# Cost tracking (optional)
+costs:
+  # X.AI Grok pricing (as of Nov 2024)
+  promptTokenCost: 0.000005                          # $5 per 1M tokens
+  completionTokenCost: 0.000015                      # $15 per 1M tokens
+  currency: USD
+
+  # Z.AI GLM 4.6 pricing - update based on your plan
+  # promptTokenCost: 0.0
+  # completionTokenCost: 0.0
+
+# Metadata
+metadata:
+  version: "8.3.1"
+  description: "Grok provider with X.AI (grok-3-fast) and Z.AI (glm-4.6) support"
+  tags:
+    - grok
+    - x-ai
+    - z-ai
+    - grok-3-fast
+    - glm-4.6
+    - reasoning
+    - code-generation
+  lastUpdated: "2025-11-17T01:45:00Z"
+
+# ====================================================================
+# Quick Start Guide
+# ====================================================================
+#
+# 1. Get your API key:
+#    - X.AI: https://console.x.ai/api-keys (starts with "xai-")
+#    - Z.AI: https://z.ai/developer (your Z.AI API key)
+#
+# 2. Set environment variable:
+#    export GROK_API_KEY="xai-your-key-here"
+#
+# 3. Copy this file:
+#    cp examples/providers/grok.yaml .automatosx/providers/grok.yaml
+#
+# 4. Enable in config:
+#    Edit automatosx.config.json:
+#    "grok": { "enabled": true, ... }
+#
+# 5. Verify setup:
+#    ax doctor grok
+#    ax providers list
+#
+# 6. Use Grok:
+#    ax run backend "implement auth" --provider grok
+#
+# ====================================================================
+# Switching Between X.AI and Z.AI
+# ====================================================================
+#
+# To switch from X.AI (grok-3-fast) to Z.AI (glm-4.6):
+#   1. Comment out X.AI config (lines 20-27)
+#   2. Uncomment Z.AI config (lines 34-37)
+#   3. Update GROK_API_KEY with Z.AI key
+#   4. Restart AutomatosX: ax doctor grok
+#
+# To switch back: reverse the process
+#

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defai.digital/automatosx",
-  "version": "8.2.0",
+  "version": "8.3.2",
   "description": "AI Agent Orchestration Platform",
   "type": "module",
   "publishConfig": {
@@ -86,7 +86,6 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@defai.digital/automatosx": "^5.8.5",
     "@iarna/toml": "^2.2.5",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
@@ -96,6 +95,7 @@
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
     "cli-table3": "^0.6.5",
+    "effect": "^3.19.3",
     "find-up": "^8.0.0",
     "inquirer": "^12.10.0",
     "js-yaml": "^4.1.0",
@@ -107,7 +107,8 @@
     "p-limit": "^7.2.0",
     "sqlite-vec": "^0.1.7-alpha.2",
     "yaml": "^2.8.1",
-    "yargs": "^18.0.0"
+    "yargs": "^18.0.0",
+    "zod": "^4.1.12"
   },
   "files": [
     "dist",

package/templates/providers/README.md

@@ -0,0 +1,117 @@
+# Provider Configuration Templates
+
+This directory contains YAML templates for configuring AI providers in AutomatosX.
+
+## Available Templates
+
+### Grok Provider
+
+**1. X.AI Official Grok** (`grok.yaml.template`)
+- **Model**: `grok-3-fast`
+- **Endpoint**: `https://api.x.ai/v1`
+- **Best for**: General AI tasks, reasoning, analysis
+- **API Key**: Get from https://x.ai/api
+- **Cost**: Paid API (check X.AI pricing)
+
+**2. Z.AI GLM 4.6** (`grok-zai.yaml.template`)
+- **Model**: `glm-4.6`
+- **Endpoint**: `https://api.z.ai/api/coding/paas/v4`
+- **Best for**: Code generation, Chinese language support
+- **API Key**: Get from https://z.ai
+- **Cost**: Free tier available
+
+## Quick Start
+
+### Using X.AI Grok
+
+```bash
+# 1. Copy template
+cp templates/providers/grok.yaml.template .automatosx/providers/grok.yaml
+
+# 2. Edit the file and add your API key
+# Replace: YOUR_X_AI_API_KEY_HERE
+# With: xai-your-actual-api-key
+
+# 3. Test configuration
+ax doctor grok
+```
+
+### Using Z.AI GLM 4.6
+
+```bash
+# 1. Copy template
+cp templates/providers/grok-zai.yaml.template .automatosx/providers/grok.yaml
+
+# 2. Edit the file and add your API key
+# Replace: YOUR_Z_AI_API_KEY_HERE
+# With: your-actual-z-ai-key
+
+# 3. Test configuration
+ax doctor grok
+```
+
+## Configuration Priority
+
+You can adjust the provider priority to control routing order:
+
+- **Priority 1** - Highest (tried first)
+- **Priority 2** - High
+- **Priority 3** - Medium
+- **Priority 4** - Low (fallback)
+
+Example:
+```yaml
+provider:
+  priority: 2  # Try Grok after OpenAI but before Gemini/Claude
+```
+
+## Environment Variables
+
+Instead of hardcoding API keys, use environment variables:
+
+```yaml
+provider:
+  apiKey: ${GROK_API_KEY}
+  baseUrl: ${GROK_BASE_URL}
+```
+
+Set environment variables:
+```bash
+export GROK_API_KEY="your-key"
+export GROK_BASE_URL="https://api.x.ai/v1"
+```
+
+## Customization
+
+### Adjust Rate Limits
+
+```yaml
+rateLimits:
+  maxRequestsPerMinute: 120  # Increase for higher quota
+  maxTokensPerMinute: 400000
+```
+
+### Modify Timeouts
+
+```yaml
+provider:
+  timeout: 300000  # 5 minutes for complex tasks
+```
+
+### Enable/Disable Provider
+
+```yaml
+provider:
+  enabled: true  # or false to disable
+```
+
+## Support
+
+- **Documentation**: See [docs/providers/grok.md](../../docs/providers/grok.md)
+- **Examples**: See [examples/providers/](../../examples/providers/)
+- **Issues**: https://github.com/defai-digital/automatosx/issues
+
+---
+
+**Version**: 8.3.1
+**Last Updated**: 2025-11-17