snow-flow 2.0.3 → 2.0.5

package/README.md

@@ -22,10 +22,51 @@ Every interaction with Snow-Flow provides insights into ServiceNow best practice
 ### **Real Integration, Real Results**
 Unlike mock tools or simulations, Snow-Flow connects directly to your ServiceNow instance through secure OAuth authentication. Every operation is real, every deployment is functional, and every result is production-ready.
 
+## 🔐 ServiceNow API Integration & Security
+
+### **Direct ServiceNow API Connection**
+All 100+ MCP tools use **official ServiceNow REST APIs** exclusively:
+- **No third-party services** - Your data stays between you and ServiceNow
+- **Standard OAuth 2.0** - Industry-standard authentication protocol
+- **ServiceNow ACLs respected** - Only access what your ServiceNow user can access
+- **Real-time operations** - Direct API calls, no data caching or storage
+
+### **How OAuth Authentication Works**
+```bash
+snow-flow auth login
+# 1. Opens ServiceNow OAuth consent screen in your browser
+# 2. You authenticate with YOUR ServiceNow credentials
+# 3. ServiceNow returns OAuth token directly to Snow-Flow
+# 4. Token stored locally in ~/.snow-flow/auth.json (encrypted)
+# 5. All API calls use this token with proper ServiceNow permissions
+```
+
+### **Data Privacy & Security**
+- ✅ **Zero data collection** - Snow-Flow doesn't collect or store your ServiceNow data
+- ✅ **Local processing** - All operations happen on your machine
+- ✅ **No external servers** - Direct ServiceNow ↔ Snow-Flow communication only
+- ✅ **Audit compliance** - All actions logged in ServiceNow audit trails
+- ✅ **Role-based access** - Respects your ServiceNow user permissions exactly
+
+### **Network Architecture**
+```
+┌─────────────┐    OAuth 2.0 + REST APIs    ┌─────────────────┐
+│  Snow-Flow  │ ◄─────────────────────────► │ Your ServiceNow │
+│   (Local)   │      HTTPS Only              │    Instance     │
+└─────────────┘                              └─────────────────┘
+     ▲                                               
+     │ No external connections                       
+     ▼                                               
+┌─────────────┐                                     
+│ Claude Code │ ◄── Local AI processing only        
+│   (Local)   │                                     
+└─────────────┘                                     
+```
+
 ## ✨ Core Capabilities
 
 ### 🤖 **Intelligent Multi-Agent System**
-- **25+ Specialized Agents**: From architects to testers, each agent brings specific expertise
+- **38 Specialized Agents**: From architects to testers, each agent brings specific expertise
 - **Swarm Coordination**: Agents work together using hierarchical, mesh, or adaptive topologies
 - **Shared Memory**: Persistent knowledge base ensures consistency across all operations
 - **Neural Learning**: Pattern recognition improves suggestions and automation over time

package/dist/memory/hierarchical-memory-system.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Hierarchical Memory System for Snow-Flow
+ * Extends base MemorySystem with ServiceNow-specific patterns
+ */
+import { MemorySystem, MemoryOptions } from './memory-system';
+export interface HierarchicalMemoryEntry {
+    key: string;
+    value: any;
+    namespace: string;
+    type: string;
+    metadata?: {
+        created: string;
+        updated: string;
+        version: number;
+        tags: string[];
+        relationships?: Record<string, string[]>;
+        dependencies?: Record<string, string[]>;
+    };
+    ttl?: number;
+}
+export interface MemorySearchOptions {
+    namespace?: string;
+    type?: string;
+    tags?: string[];
+    pattern?: string;
+    limit?: number;
+    includeExpired?: boolean;
+}
+export declare class HierarchicalMemorySystem extends MemorySystem {
+    private namespaceIndex;
+    private typeIndex;
+    private tagIndex;
+    constructor(options: MemoryOptions);
+    /**
+     * Initialize with enhanced tables for hierarchical storage
+     */
+    initialize(): Promise<void>;
+    /**
+     * Create additional tables for hierarchical organization
+     */
+    private createHierarchicalTables;
+    /**
+     * Store with hierarchical organization
+     */
+    storeHierarchical(entry: Partial<HierarchicalMemoryEntry>): Promise<void>;
+    /**
+     * Get with full hierarchical metadata
+     */
+    getHierarchical(key: string): Promise<HierarchicalMemoryEntry | null>;
+    /**
+     * Search with hierarchical patterns
+     */
+    search(options: MemorySearchOptions): Promise<HierarchicalMemoryEntry[]>;
+    /**
+     * Create relationship between entries
+     */
+    createRelationship(sourceKey: string, targetKey: string, relationshipType: string, metadata?: any): Promise<void>;
+    /**
+     * Get related entries
+     */
+    getRelated(key: string, relationshipType?: string): Promise<HierarchicalMemoryEntry[]>;
+    /**
+     * Associate memory with agent
+     */
+    associateWithAgent(agentId: string, memoryKey: string, accessType: 'read' | 'write' | 'owner'): Promise<void>;
+    /**
+     * Get agent's memory entries
+     */
+    getAgentMemory(agentId: string, accessType?: string): Promise<HierarchicalMemoryEntry[]>;
+    /**
+     * Track access pattern for learning
+     */
+    trackAccessPattern(patternType: string, metadata?: any): Promise<void>;
+    /**
+     * Get namespace statistics
+     */
+    getNamespaceStats(): Promise<Record<string, number>>;
+    /**
+     * Helper methods
+     */
+    private updateTags;
+    private getTags;
+    private updateLocalIndexes;
+    private buildIndexes;
+    /**
+     * Cleanup expired entries
+     */
+    cleanupExpired(): Promise<number>;
+}
+//# sourceMappingURL=hierarchical-memory-system.d.ts.map

package/dist/memory/hierarchical-memory-system.js

@@ -0,0 +1,400 @@
+"use strict";
+/**
+ * Hierarchical Memory System for Snow-Flow
+ * Extends base MemorySystem with ServiceNow-specific patterns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HierarchicalMemorySystem = void 0;
+const memory_system_1 = require("./memory-system");
+class HierarchicalMemorySystem extends memory_system_1.MemorySystem {
+    constructor(options) {
+        super(options);
+        this.namespaceIndex = new Map();
+        this.typeIndex = new Map();
+        this.tagIndex = new Map();
+    }
+    /**
+     * Initialize with enhanced tables for hierarchical storage
+     */
+    async initialize() {
+        await super.initialize();
+        await this.createHierarchicalTables();
+        await this.buildIndexes();
+    }
+    /**
+     * Create additional tables for hierarchical organization
+     */
+    async createHierarchicalTables() {
+        const tables = [
+            // Enhanced memory store with namespace and type
+            `CREATE TABLE IF NOT EXISTS hierarchical_memory (
+        key TEXT PRIMARY KEY,
+        namespace TEXT NOT NULL,
+        type TEXT NOT NULL,
+        value TEXT NOT NULL,
+        metadata TEXT,
+        ttl INTEGER,
+        created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),
+        updated_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),
+        expires_at INTEGER,
+        version INTEGER DEFAULT 1
+      )`,
+            // Tag associations
+            `CREATE TABLE IF NOT EXISTS memory_tags (
+        key TEXT NOT NULL,
+        tag TEXT NOT NULL,
+        PRIMARY KEY (key, tag),
+        FOREIGN KEY (key) REFERENCES hierarchical_memory(key) ON DELETE CASCADE
+      )`,
+            // Relationships between memory entries
+            `CREATE TABLE IF NOT EXISTS memory_relationships (
+        source_key TEXT NOT NULL,
+        target_key TEXT NOT NULL,
+        relationship_type TEXT NOT NULL,
+        metadata TEXT,
+        created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),
+        PRIMARY KEY (source_key, target_key, relationship_type),
+        FOREIGN KEY (source_key) REFERENCES hierarchical_memory(key) ON DELETE CASCADE,
+        FOREIGN KEY (target_key) REFERENCES hierarchical_memory(key) ON DELETE CASCADE
+      )`,
+            // Agent memory associations
+            `CREATE TABLE IF NOT EXISTS agent_memory (
+        agent_id TEXT NOT NULL,
+        memory_key TEXT NOT NULL,
+        access_type TEXT NOT NULL, -- 'read', 'write', 'owner'
+        accessed_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),
+        PRIMARY KEY (agent_id, memory_key),
+        FOREIGN KEY (memory_key) REFERENCES hierarchical_memory(key) ON DELETE CASCADE
+      )`,
+            // Memory access patterns for learning
+            `CREATE TABLE IF NOT EXISTS memory_access_patterns (
+        pattern_id TEXT PRIMARY KEY,
+        pattern_type TEXT NOT NULL,
+        frequency INTEGER DEFAULT 1,
+        last_accessed INTEGER DEFAULT (strftime('%s', 'now') * 1000),
+        metadata TEXT
+      )`,
+        ];
+        for (const table of tables) {
+            await this.execute(table);
+        }
+        // Create indexes for performance
+        const indexes = [
+            'CREATE INDEX IF NOT EXISTS idx_namespace ON hierarchical_memory(namespace)',
+            'CREATE INDEX IF NOT EXISTS idx_type ON hierarchical_memory(type)',
+            'CREATE INDEX IF NOT EXISTS idx_expires ON hierarchical_memory(expires_at)',
+            'CREATE INDEX IF NOT EXISTS idx_tags ON memory_tags(tag)',
+            'CREATE INDEX IF NOT EXISTS idx_relationships ON memory_relationships(relationship_type)',
+            'CREATE INDEX IF NOT EXISTS idx_agent_memory ON agent_memory(agent_id)',
+        ];
+        for (const index of indexes) {
+            await this.execute(index);
+        }
+    }
+    /**
+     * Store with hierarchical organization
+     */
+    async storeHierarchical(entry) {
+        if (!entry.key)
+            throw new Error('Key is required');
+        // Extract namespace and type from key pattern
+        const keyParts = entry.key.split('/');
+        const namespace = entry.namespace || keyParts[0] || 'default';
+        const type = entry.type || keyParts[1] || 'general';
+        const metadata = {
+            created: new Date().toISOString(),
+            updated: new Date().toISOString(),
+            version: 1,
+            tags: entry.metadata?.tags || [],
+            relationships: entry.metadata?.relationships || {},
+            dependencies: entry.metadata?.dependencies || {},
+            ...entry.metadata,
+        };
+        const ttl = entry.ttl || 86400000 * 7; // 7 days default
+        const expiresAt = Date.now() + ttl;
+        // Check if exists for versioning
+        const existing = await this.getHierarchical(entry.key);
+        if (existing) {
+            metadata.version = (existing.metadata?.version || 0) + 1;
+            metadata.created = existing.metadata?.created || metadata.created;
+        }
+        // Store in hierarchical table
+        await this.execute(`
+      INSERT OR REPLACE INTO hierarchical_memory 
+      (key, namespace, type, value, metadata, ttl, expires_at, version, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `, [
+            entry.key,
+            namespace,
+            type,
+            JSON.stringify(entry.value),
+            JSON.stringify(metadata),
+            ttl,
+            expiresAt,
+            metadata.version,
+            Date.now()
+        ]);
+        // Update tags
+        if (metadata.tags.length > 0) {
+            await this.updateTags(entry.key, metadata.tags);
+        }
+        // Update indexes
+        this.updateLocalIndexes(entry.key, namespace, type, metadata.tags);
+        // Store in base system for compatibility
+        await super.store(entry.key, entry.value, ttl);
+        this.emit('memory:hierarchical:stored', { key: entry.key, namespace, type });
+    }
+    /**
+     * Get with full hierarchical metadata
+     */
+    async getHierarchical(key) {
+        const result = await this.query(`
+      SELECT * FROM hierarchical_memory 
+      WHERE key = ? AND expires_at > ?
+    `, [key, Date.now()]);
+        if (!result || result.length === 0)
+            return null;
+        const row = result[0];
+        const tags = await this.getTags(key);
+        return {
+            key: row.key,
+            namespace: row.namespace,
+            type: row.type,
+            value: JSON.parse(row.value),
+            metadata: {
+                ...JSON.parse(row.metadata || '{}'),
+                tags,
+            },
+            ttl: row.ttl,
+        };
+    }
+    /**
+     * Search with hierarchical patterns
+     */
+    async search(options) {
+        let sql = 'SELECT DISTINCT h.* FROM hierarchical_memory h';
+        const params = [];
+        const conditions = [];
+        // Join with tags if needed
+        if (options.tags && options.tags.length > 0) {
+            sql += ' INNER JOIN memory_tags t ON h.key = t.key';
+            conditions.push(`t.tag IN (${options.tags.map(() => '?').join(',')})`);
+            params.push(...options.tags);
+        }
+        // Add namespace filter
+        if (options.namespace) {
+            conditions.push('h.namespace = ?');
+            params.push(options.namespace);
+        }
+        // Add type filter
+        if (options.type) {
+            conditions.push('h.type = ?');
+            params.push(options.type);
+        }
+        // Add pattern matching
+        if (options.pattern) {
+            conditions.push('h.key LIKE ?');
+            params.push(`%${options.pattern}%`);
+        }
+        // Add expiration filter
+        if (!options.includeExpired) {
+            conditions.push('h.expires_at > ?');
+            params.push(Date.now());
+        }
+        // Combine conditions
+        if (conditions.length > 0) {
+            sql += ' WHERE ' + conditions.join(' AND ');
+        }
+        // Add ordering and limit
+        sql += ' ORDER BY h.updated_at DESC';
+        if (options.limit) {
+            sql += ' LIMIT ?';
+            params.push(options.limit);
+        }
+        const results = await this.query(sql, params);
+        // Fetch tags and format results
+        const entries = [];
+        for (const row of results) {
+            const tags = await this.getTags(row.key);
+            entries.push({
+                key: row.key,
+                namespace: row.namespace,
+                type: row.type,
+                value: JSON.parse(row.value),
+                metadata: {
+                    ...JSON.parse(row.metadata || '{}'),
+                    tags,
+                },
+                ttl: row.ttl,
+            });
+        }
+        return entries;
+    }
+    /**
+     * Create relationship between entries
+     */
+    async createRelationship(sourceKey, targetKey, relationshipType, metadata) {
+        await this.execute(`
+      INSERT OR REPLACE INTO memory_relationships 
+      (source_key, target_key, relationship_type, metadata)
+      VALUES (?, ?, ?, ?)
+    `, [sourceKey, targetKey, relationshipType, JSON.stringify(metadata || {})]);
+        this.emit('memory:relationship:created', { sourceKey, targetKey, relationshipType });
+    }
+    /**
+     * Get related entries
+     */
+    async getRelated(key, relationshipType) {
+        let sql = `
+      SELECT DISTINCT h.* 
+      FROM hierarchical_memory h
+      INNER JOIN memory_relationships r ON (h.key = r.target_key OR h.key = r.source_key)
+      WHERE (r.source_key = ? OR r.target_key = ?) AND h.key != ?
+    `;
+        const params = [key, key, key];
+        if (relationshipType) {
+            sql += ' AND r.relationship_type = ?';
+            params.push(relationshipType);
+        }
+        const results = await this.query(sql, params);
+        const entries = [];
+        for (const row of results) {
+            const entry = await this.getHierarchical(row.key);
+            if (entry)
+                entries.push(entry);
+        }
+        return entries;
+    }
+    /**
+     * Associate memory with agent
+     */
+    async associateWithAgent(agentId, memoryKey, accessType) {
+        await this.execute(`
+      INSERT OR REPLACE INTO agent_memory (agent_id, memory_key, access_type)
+      VALUES (?, ?, ?)
+    `, [agentId, memoryKey, accessType]);
+    }
+    /**
+     * Get agent's memory entries
+     */
+    async getAgentMemory(agentId, accessType) {
+        let sql = `
+      SELECT h.* FROM hierarchical_memory h
+      INNER JOIN agent_memory a ON h.key = a.memory_key
+      WHERE a.agent_id = ?
+    `;
+        const params = [agentId];
+        if (accessType) {
+            sql += ' AND a.access_type = ?';
+            params.push(accessType);
+        }
+        const results = await this.query(sql, params);
+        const entries = [];
+        for (const row of results) {
+            const entry = await this.getHierarchical(row.key);
+            if (entry)
+                entries.push(entry);
+        }
+        return entries;
+    }
+    /**
+     * Track access pattern for learning
+     */
+    async trackAccessPattern(patternType, metadata) {
+        const patternId = `${patternType}_${Date.now()}`;
+        await this.execute(`
+      INSERT INTO memory_access_patterns (pattern_id, pattern_type, metadata)
+      VALUES (?, ?, ?)
+      ON CONFLICT(pattern_id) DO UPDATE SET
+        frequency = frequency + 1,
+        last_accessed = strftime('%s', 'now') * 1000
+    `, [patternId, patternType, JSON.stringify(metadata || {})]);
+    }
+    /**
+     * Get namespace statistics
+     */
+    async getNamespaceStats() {
+        const results = await this.query(`
+      SELECT namespace, COUNT(*) as count
+      FROM hierarchical_memory
+      WHERE expires_at > ?
+      GROUP BY namespace
+    `, [Date.now()]);
+        const stats = {};
+        for (const row of results) {
+            stats[row.namespace] = row.count;
+        }
+        return stats;
+    }
+    /**
+     * Helper methods
+     */
+    async updateTags(key, tags) {
+        // Remove existing tags
+        await this.execute('DELETE FROM memory_tags WHERE key = ?', [key]);
+        // Insert new tags
+        for (const tag of tags) {
+            await this.execute('INSERT INTO memory_tags (key, tag) VALUES (?, ?)', [key, tag]);
+        }
+    }
+    async getTags(key) {
+        const results = await this.query('SELECT tag FROM memory_tags WHERE key = ?', [key]);
+        return results.map(r => r.tag);
+    }
+    updateLocalIndexes(key, namespace, type, tags) {
+        // Update namespace index
+        if (!this.namespaceIndex.has(namespace)) {
+            this.namespaceIndex.set(namespace, new Set());
+        }
+        this.namespaceIndex.get(namespace).add(key);
+        // Update type index
+        if (!this.typeIndex.has(type)) {
+            this.typeIndex.set(type, new Set());
+        }
+        this.typeIndex.get(type).add(key);
+        // Update tag index
+        for (const tag of tags) {
+            if (!this.tagIndex.has(tag)) {
+                this.tagIndex.set(tag, new Set());
+            }
+            this.tagIndex.get(tag).add(key);
+        }
+    }
+    async buildIndexes() {
+        // Build indexes from existing data
+        const results = await this.query(`
+      SELECT key, namespace, type FROM hierarchical_memory 
+      WHERE expires_at > ?
+    `, [Date.now()]);
+        for (const row of results) {
+            const tags = await this.getTags(row.key);
+            this.updateLocalIndexes(row.key, row.namespace, row.type, tags);
+        }
+    }
+    /**
+     * Cleanup expired entries
+     */
+    async cleanupExpired() {
+        const result = await this.query(`
+      DELETE FROM hierarchical_memory 
+      WHERE expires_at <= ?
+      RETURNING key
+    `, [Date.now()]);
+        // Update local indexes
+        for (const row of result) {
+            // Remove from indexes
+            for (const [namespace, keys] of this.namespaceIndex) {
+                keys.delete(row.key);
+            }
+            for (const [type, keys] of this.typeIndex) {
+                keys.delete(row.key);
+            }
+            for (const [tag, keys] of this.tagIndex) {
+                keys.delete(row.key);
+            }
+        }
+        return result.length;
+    }
+}
+exports.HierarchicalMemorySystem = HierarchicalMemorySystem;
+//# sourceMappingURL=hierarchical-memory-system.js.map

package/dist/memory/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Snow-Flow Memory System Exports
+ * Centralized exports for the SQLite memory system
+ */
+export { SwarmMemory, SwarmMemoryConfig, AgentCoordination, ServiceNowArtifactRecord, AgentMessage, SharedContext, DeploymentHistory, AgentDependency, PerformanceMetric } from './swarm-memory.js';
+export { MemoryOperations, AgentCoordinationUpdate, ArtifactSearchOptions, MessageSearchOptions, PerformanceQuery } from './memory-operations.js';
+export { MemoryClient, MemoryClientConfig, MemoryStoreOptions, MemoryRetrieveOptions, ArtifactInfo, AgentHandoff, PerformanceTracker } from './memory-client.js';
+export { ServiceNowArtifactIndexer, ServiceNowArtifact, FlowArtifact, WidgetArtifact, IndexedArtifact, ArtifactStructure, ArtifactContext, ArtifactRelationships, ModificationPoint, EditHistory } from './servicenow-artifact-indexer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Snow-Flow Memory System Exports
+ * Centralized exports for the SQLite memory system
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceNowArtifactIndexer = exports.MemoryClient = exports.MemoryOperations = exports.SwarmMemory = void 0;
+// Core memory system
+var swarm_memory_js_1 = require("./swarm-memory.js");
+Object.defineProperty(exports, "SwarmMemory", { enumerable: true, get: function () { return swarm_memory_js_1.SwarmMemory; } });
+// Memory operations
+var memory_operations_js_1 = require("./memory-operations.js");
+Object.defineProperty(exports, "MemoryOperations", { enumerable: true, get: function () { return memory_operations_js_1.MemoryOperations; } });
+// Memory client API
+var memory_client_js_1 = require("./memory-client.js");
+Object.defineProperty(exports, "MemoryClient", { enumerable: true, get: function () { return memory_client_js_1.MemoryClient; } });
+// Existing artifact indexer (for compatibility)
+var servicenow_artifact_indexer_js_1 = require("./servicenow-artifact-indexer.js");
+Object.defineProperty(exports, "ServiceNowArtifactIndexer", { enumerable: true, get: function () { return servicenow_artifact_indexer_js_1.ServiceNowArtifactIndexer; } });
+//# sourceMappingURL=index.js.map

package/dist/memory/mcp-integration-example.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Snow-Flow Memory System MCP Integration Example
+ * Shows how MCP tools integrate with the memory system
+ */
+export {};
+//# sourceMappingURL=mcp-integration-example.d.ts.map