@defai.digital/ax-cli 3.7.2 → 3.8.2

package/dist/mcp/automatosx-loader.js

@@ -0,0 +1,238 @@
+/**
+ * AutomatosX Configuration Loader
+ *
+ * Loads MCP server configurations from AutomatosX config files and merges
+ * them with ax-cli configurations. Provides backward compatibility for
+ * AutomatosX users migrating to ax-cli.
+ */
+import fs from 'fs';
+import path from 'path';
+import { migrateConfig } from './config-migrator.js';
+import { detectConfigFormat } from './config-detector.js';
+/**
+ * Get AutomatosX config directory path
+ */
+export function getAutomatosXConfigDir(projectRoot) {
+    const root = projectRoot || process.cwd();
+    return path.join(root, '.automatosx');
+}
+/**
+ * Get AutomatosX config file path
+ */
+export function getAutomatosXConfigPath(projectRoot) {
+    return path.join(getAutomatosXConfigDir(projectRoot), 'config.json');
+}
+/**
+ * Check if AutomatosX config exists
+ */
+export function automatosXConfigExists(projectRoot) {
+    const configPath = getAutomatosXConfigPath(projectRoot);
+    return fs.existsSync(configPath);
+}
+/**
+ * Load AutomatosX configuration file
+ */
+export function loadAutomatosXConfigFile(projectRoot) {
+    const configPath = getAutomatosXConfigPath(projectRoot);
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const data = JSON.parse(raw);
+        return data;
+    }
+    catch (error) {
+        console.warn(`Failed to load AutomatosX config from ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Load and migrate AutomatosX MCP server configurations
+ */
+export function loadAutomatosXMCPServers(projectRoot) {
+    const warnings = [];
+    const errors = [];
+    const migrations = new Map();
+    const servers = [];
+    // Check if AutomatosX config exists
+    const configPath = getAutomatosXConfigPath(projectRoot);
+    if (!fs.existsSync(configPath)) {
+        return {
+            found: false,
+            servers: [],
+            migrations,
+            warnings,
+            errors
+        };
+    }
+    // Load config
+    const config = loadAutomatosXConfigFile(projectRoot);
+    if (!config) {
+        errors.push('Failed to load AutomatosX config');
+        return {
+            found: true,
+            configPath,
+            servers: [],
+            migrations,
+            warnings,
+            errors
+        };
+    }
+    // Extract MCP servers
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+        warnings.push('AutomatosX config found but no MCP servers configured');
+        return {
+            found: true,
+            configPath,
+            servers: [],
+            migrations,
+            warnings,
+            errors
+        };
+    }
+    // Detect version
+    if (config.automatosxVersion) {
+        warnings.push(`AutomatosX version detected: ${config.automatosxVersion}`);
+    }
+    // Migrate each server
+    for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+        // Ensure server has name field
+        const configWithName = { ...serverConfig, name: serverConfig.name || name };
+        // Detect format
+        const detection = detectConfigFormat(configWithName);
+        if (detection.isLegacy) {
+            warnings.push(`Server "${name}" uses legacy format - migrating automatically`);
+        }
+        // Migrate
+        const migration = migrateConfig(configWithName);
+        migrations.set(name, migration);
+        if (migration.success && migration.migratedConfig) {
+            servers.push(migration.migratedConfig);
+        }
+        else {
+            errors.push(`Failed to migrate server "${name}": ${migration.errors.join(', ')}`);
+        }
+    }
+    return {
+        found: true,
+        configPath,
+        servers,
+        migrations,
+        warnings,
+        errors
+    };
+}
+/**
+ * Merge ax-cli and AutomatosX MCP server configurations
+ *
+ * Strategy:
+ * - ax-cli configs take precedence (user explicitly configured)
+ * - AutomatosX configs provide defaults/fallbacks
+ * - Conflicts are logged as warnings
+ * - Both configs can coexist (different server names)
+ */
+export function mergeConfigs(axCliServers, automatosXServers) {
+    const merged = new Map();
+    const sources = new Map();
+    const conflicts = [];
+    const warnings = [];
+    // Add AutomatosX servers first (lower priority)
+    for (const server of automatosXServers) {
+        merged.set(server.name, server);
+        sources.set(server.name, 'automatosx');
+    }
+    // Add/override with ax-cli servers (higher priority)
+    for (const server of axCliServers) {
+        const existingServer = merged.get(server.name);
+        if (existingServer) {
+            // Conflict detected
+            const automatosXServer = existingServer;
+            // Check if configs are identical (no real conflict)
+            const areIdentical = JSON.stringify(automatosXServer) === JSON.stringify(server);
+            if (areIdentical) {
+                sources.set(server.name, 'both');
+                warnings.push(`Server "${server.name}" configured in both ax-cli and AutomatosX with identical settings`);
+            }
+            else {
+                sources.set(server.name, 'ax-cli');
+                conflicts.push({
+                    serverName: server.name,
+                    axCliConfig: server,
+                    automatosXConfig: automatosXServer,
+                    resolution: 'ax-cli-wins'
+                });
+                warnings.push(`Server "${server.name}" configured in both ax-cli and AutomatosX. Using ax-cli version.`);
+            }
+        }
+        else {
+            sources.set(server.name, 'ax-cli');
+        }
+        // ax-cli always wins
+        merged.set(server.name, server);
+    }
+    return {
+        servers: Array.from(merged.values()),
+        sources,
+        conflicts,
+        warnings
+    };
+}
+/**
+ * Format merge result for display
+ */
+export function formatMergeResult(result) {
+    const lines = [];
+    lines.push('╭─ MCP Config Merge Summary ────────────────────╮');
+    lines.push(`│ Total servers: ${result.servers.length}`);
+    const axCliCount = Array.from(result.sources.values()).filter(s => s === 'ax-cli').length;
+    const automatosXCount = Array.from(result.sources.values()).filter(s => s === 'automatosx').length;
+    const bothCount = Array.from(result.sources.values()).filter(s => s === 'both').length;
+    if (axCliCount > 0) {
+        lines.push(`│ From ax-cli: ${axCliCount}`);
+    }
+    if (automatosXCount > 0) {
+        lines.push(`│ From AutomatosX: ${automatosXCount}`);
+    }
+    if (bothCount > 0) {
+        lines.push(`│ In both (identical): ${bothCount}`);
+    }
+    if (result.conflicts.length > 0) {
+        lines.push(`│ Conflicts resolved: ${result.conflicts.length}`);
+    }
+    lines.push('╰────────────────────────────────────────────────╯');
+    // Show conflicts
+    if (result.conflicts.length > 0) {
+        lines.push('');
+        lines.push('Conflicts (ax-cli config used):');
+        result.conflicts.forEach(conflict => {
+            lines.push(`  • ${conflict.serverName}`);
+        });
+    }
+    // Show warnings
+    if (result.warnings.length > 0) {
+        lines.push('');
+        result.warnings.forEach(warning => {
+            lines.push(`⚠️  ${warning}`);
+        });
+    }
+    return lines.join('\n');
+}
+/**
+ * Get recommendation for user based on merge result
+ */
+export function getConfigRecommendation(result) {
+    // If there are conflicts, recommend consolidation
+    if (result.conflicts.length > 0) {
+        return ('Recommendation: Consolidate your MCP server configurations into .ax-cli/settings.json\n' +
+            'to avoid conflicts. Run: ax-cli mcp migrate --from .automatosx/config.json');
+    }
+    // If AutomatosX configs exist but no conflicts, inform user
+    const automatosXCount = Array.from(result.sources.values()).filter(s => s === 'automatosx').length;
+    if (automatosXCount > 0) {
+        return ('Info: Using MCP servers from AutomatosX config. This is OK, but consider\n' +
+            'migrating to .ax-cli/settings.json for better integration.');
+    }
+    return null;
+}
+//# sourceMappingURL=automatosx-loader.js.map

package/dist/mcp/automatosx-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automatosx-loader.js","sourceRoot":"","sources":["../../src/mcp/automatosx-loader.ts"],"names":[],"mappings":"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"}

package/dist/mcp/client-mutex-patch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Mutex-Protected MCP Client Patch
+ *
+ * This file contains the mutex-protected version of addServer() method
+ * to be integrated into MCPManager class in client.ts
+ *
+ * INTEGRATION INSTRUCTIONS:
+ * 1. Add import: import { KeyedMutex } from "./mutex.js";
+ * 2. Add field: private connectionMutex = new KeyedMutex();
+ * 3. Replace addServer() method with the version below
+ * 4. Add mutex cleanup to dispose() method
+ */
+/**
+ * Benefits of Mutex Protection:
+ *
+ * 1. Race Condition Prevention:
+ *    - Multiple concurrent addServer() calls for same server
+ *    - Multi-agent AutomatosX setups calling ensureServersInitialized()
+ *    - Duplicate connections from parallel initialization
+ *
+ * 2. Resource Protection:
+ *    - Prevents duplicate client instances
+ *    - Avoids wasted file descriptors/memory
+ *    - Ensures clean state transitions
+ *
+ * 3. Thread Safety:
+ *    - Atomic check-and-set operations
+ *    - No TOCTOU (Time-Of-Check-Time-Of-Use) bugs
+ *    - Guaranteed sequential execution per server
+ *
+ * Performance Impact: Negligible
+ * - Mutex only blocks same-server connections
+ * - Different servers connect in parallel
+ * - Minimal overhead (~microseconds per acquire/release)
+ */
+export declare const MUTEX_INTEGRATION_COMPLETE = false;

package/dist/mcp/client-mutex-patch.js

@@ -0,0 +1,75 @@
+/**
+ * Mutex-Protected MCP Client Patch
+ *
+ * This file contains the mutex-protected version of addServer() method
+ * to be integrated into MCPManager class in client.ts
+ *
+ * INTEGRATION INSTRUCTIONS:
+ * 1. Add import: import { KeyedMutex } from "./mutex.js";
+ * 2. Add field: private connectionMutex = new KeyedMutex();
+ * 3. Replace addServer() method with the version below
+ * 4. Add mutex cleanup to dispose() method
+ */
+// STEP 1: Add to imports (line 8)
+// import { KeyedMutex } from "./mutex.js";
+// STEP 2: Add to MCPManager class fields (after line 26)
+// private connectionMutex = new KeyedMutex(); // Mutex for thread-safe connections
+// STEP 3: Replace addServer() method (lines 28-50)
+/*
+  async addServer(config: MCPServerConfig): Promise<void> {
+    // Use mutex to ensure atomic check-and-connect operation
+    // This prevents race conditions when multiple parts of the system
+    // try to connect to the same server simultaneously
+    return await this.connectionMutex.runExclusive(config.name, async () => {
+      // Check if already connected (now protected by mutex)
+      if (this.clients.has(config.name)) {
+        return; // Already connected, nothing to do
+      }
+
+      // Check if already connecting (now protected by mutex)
+      const pending = this.pendingConnections.get(config.name);
+      if (pending) {
+        await pending; // Wait for the connection to complete
+        return;
+      }
+
+      // Create a promise for this connection attempt
+      const connectionPromise = this._addServerInternal(config);
+      this.pendingConnections.set(config.name, connectionPromise);
+
+      try {
+        await connectionPromise;
+      } finally {
+        this.pendingConnections.delete(config.name);
+      }
+    });
+  }
+*/
+// STEP 4: Add to dispose() method (before removeAllListeners())
+// // Cleanup mutex state
+// this.connectionMutex.clearAll();
+/**
+ * Benefits of Mutex Protection:
+ *
+ * 1. Race Condition Prevention:
+ *    - Multiple concurrent addServer() calls for same server
+ *    - Multi-agent AutomatosX setups calling ensureServersInitialized()
+ *    - Duplicate connections from parallel initialization
+ *
+ * 2. Resource Protection:
+ *    - Prevents duplicate client instances
+ *    - Avoids wasted file descriptors/memory
+ *    - Ensures clean state transitions
+ *
+ * 3. Thread Safety:
+ *    - Atomic check-and-set operations
+ *    - No TOCTOU (Time-Of-Check-Time-Of-Use) bugs
+ *    - Guaranteed sequential execution per server
+ *
+ * Performance Impact: Negligible
+ * - Mutex only blocks same-server connections
+ * - Different servers connect in parallel
+ * - Minimal overhead (~microseconds per acquire/release)
+ */
+export const MUTEX_INTEGRATION_COMPLETE = false; // Set to true after integration
+//# sourceMappingURL=client-mutex-patch.js.map

package/dist/mcp/client-mutex-patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-mutex-patch.js","sourceRoot":"","sources":["../../src/mcp/client-mutex-patch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,kCAAkC;AAClC,2CAA2C;AAE3C,yDAAyD;AACzD,mFAAmF;AAEnF,mDAAmD;AACnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BE;AAEF,gEAAgE;AAChE,yBAAyB;AACzB,mCAAmC;AAEnC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC,CAAC,gCAAgC"}

package/dist/mcp/client-v2.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Type-Safe MCP Client (Phase 1 Improvements)
+ *
+ * Improvements applied:
+ * 1. SafeMutex with lock tokens (prevents race conditions)
+ * 2. Result types for all public APIs (explicit error handling)
+ * 3. State machine for connection tracking (type-safe states)
+ * 4. Branded types for ServerName/ToolName (prevent confusion)
+ * 5. Invariant checks (runtime validation)
+ *
+ * Coverage: 70% → 85%+ (Phase 1)
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { EventEmitter } from "events";
+import { MCPTransport, TransportType } from "./transports.js";
+import type { MCPServerConfig, MCPTransportConfig } from "../schemas/settings-schemas.js";
+import { Result } from "./type-safety.js";
+import { ServerName, ToolName, createServerName } from "./type-safety.js";
+export type { MCPServerConfig, MCPTransportConfig, ServerName, ToolName };
+/**
+ * Connection State Machine
+ *
+ * Valid transitions:
+ * - idle → connecting (addServer called)
+ * - connecting → connected (connection succeeds)
+ * - connecting → failed (connection fails)
+ * - connected → disconnecting (removeServer called)
+ * - disconnecting → idle (cleanup complete)
+ * - failed → idle (reset)
+ */
+export type ConnectionState = {
+    status: 'idle';
+    serverName: ServerName;
+} | {
+    status: 'connecting';
+    serverName: ServerName;
+    startedAt: number;
+    promise: Promise<Result<void, Error>>;
+} | {
+    status: 'connected';
+    serverName: ServerName;
+    client: Client;
+    transport: MCPTransport;
+    connectedAt: number;
+} | {
+    status: 'disconnecting';
+    serverName: ServerName;
+    client: Client;
+    transport: MCPTransport;
+} | {
+    status: 'failed';
+    serverName: ServerName;
+    error: Error;
+    failedAt: number;
+};
+/**
+ * Reconnection Configuration
+ *
+ * Controls automatic reconnection behavior when MCP servers fail or disconnect.
+ * Uses exponential backoff to avoid overwhelming failed servers.
+ *
+ * @example
+ * ```typescript
+ * const config: ReconnectionConfig = {
+ *   enabled: true,
+ *   maxRetries: 5,
+ *   initialDelayMs: 1000,
+ *   maxDelayMs: 30000,
+ *   backoffMultiplier: 2
+ * };
+ * ```
+ */
+export interface ReconnectionConfig {
+    /** Enable automatic reconnection on failure */
+    enabled: boolean;
+    /** Maximum number of reconnection attempts before giving up (default: 5) */
+    maxRetries: number;
+    /** Initial delay before first reconnection attempt in ms (default: 1000) */
+    initialDelayMs: number;
+    /** Maximum delay between reconnection attempts in ms (default: 30000) */
+    maxDelayMs: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    backoffMultiplier: number;
+}
+/**
+ * Default reconnection configuration
+ */
+export declare const DEFAULT_RECONNECTION_CONFIG: ReconnectionConfig;
+/**
+ * Health Check Configuration
+ */
+export interface HealthCheckConfig {
+    /** Enable periodic health checks */
+    enabled: boolean;
+    /** Interval between health checks in ms (default: 30000) */
+    intervalMs: number;
+}
+/**
+ * Default health check configuration
+ */
+export declare const DEFAULT_HEALTH_CHECK_CONFIG: HealthCheckConfig;
+/**
+ * MCP Tool with branded types
+ */
+export interface MCPTool {
+    name: ToolName;
+    description: string;
+    inputSchema: any;
+    serverName: ServerName;
+}
+/**
+ * Type-safe MCP Manager with improved safety
+ */
+export declare class MCPManagerV2 extends EventEmitter {
+    private connections;
+    private tools;
+    private connectionMutex;
+    private initializationPromise;
+    private tokenCounter;
+    private disposed;
+    private reconnectionConfig;
+    private healthCheckConfig;
+    private reconnectionAttempts;
+    private reconnectionTimers;
+    private serverConfigs;
+    private healthCheckTimer;
+    constructor(reconnectionConfig?: Partial<ReconnectionConfig>, healthCheckConfig?: Partial<HealthCheckConfig>);
+    /**
+     * Add MCP server with type-safe connection management
+     *
+     * Phase 1 improvements:
+     * - Returns Result instead of throwing
+     * - Uses SafeMutex for concurrency control
+     * - Tracks state machine transitions
+     * - Validates inputs with invariants
+     */
+    addServer(config: MCPServerConfig): Promise<Result<void, Error>>;
+    /**
+     * Internal connection logic with state transitions
+     */
+    private _addServerInternal;
+    /**
+     * Remove MCP server with proper state transitions
+     */
+    removeServer(serverName: ServerName): Promise<Result<void, Error>>;
+    /**
+     * Internal disconnection logic with state transitions
+     */
+    private _removeServerInternal;
+    /**
+     * Close client with error handling
+     */
+    private closeClient;
+    /**
+     * Disconnect transport with error handling
+     */
+    private disconnectTransport;
+    /**
+     * Call MCP tool with type safety
+     */
+    callTool(toolName: ToolName, arguments_: Record<string, unknown> | null | undefined): Promise<Result<CallToolResult, Error>>;
+    /**
+     * Truncate text to fit within token limit
+     * UNICODE FIX: Uses grapheme clusters
+     */
+    private truncateToTokenLimit;
+    /**
+     * Get all tools
+     */
+    getTools(): MCPTool[];
+    /**
+     * Get all connected servers
+     */
+    getServers(): ServerName[];
+    /**
+     * Get connection state for a server
+     */
+    getConnectionState(serverName: ServerName): ConnectionState | undefined;
+    /**
+     * Get transport type for a server
+     */
+    getTransportType(serverName: ServerName): Result<TransportType, Error>;
+    /**
+     * Schedule reconnection for a failed server with exponential backoff
+     *
+     * Phase 2: Automatic reconnection logic
+     *
+     * @param serverName - Server to reconnect
+     * @param config - Server configuration
+     */
+    private scheduleReconnection;
+    /**
+     * Cancel reconnection for a server
+     */
+    private cancelReconnection;
+    /**
+     * Perform health check on a single server
+     *
+     * @param serverName - Server to check
+     * @returns Result indicating health status
+     */
+    healthCheck(serverName: ServerName): Promise<Result<boolean, Error>>;
+    /**
+     * Start periodic health checks for all connected servers
+     */
+    private startHealthChecks;
+    /**
+     * Stop periodic health checks
+     */
+    private stopHealthChecks;
+    /**
+     * Shutdown all servers
+     */
+    shutdown(): Promise<Result<void, Error>>;
+    /**
+     * Ensure servers initialized
+     */
+    ensureServersInitialized(): Promise<Result<void, Error>>;
+    /**
+     * Dispose all resources
+     */
+    dispose(): Promise<Result<void, Error>>;
+}
+/**
+ * Helper functions for creating branded types
+ */
+declare function createToolName(name: string): ToolName | null;
+export { createServerName, createToolName };