snow-flow 2.0.3 → 2.0.5

package/dist/memory/mcp-integration-example.js

@@ -0,0 +1,281 @@
+"use strict";
+/**
+ * Snow-Flow Memory System MCP Integration Example
+ * Shows how MCP tools integrate with the memory system
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const memory_client_js_1 = require("./memory-client.js");
+const logger_js_1 = require("../utils/logger.js");
+const logger = new logger_js_1.Logger('MCPIntegration');
+/**
+ * Example MCP tool that follows the memory integration pattern from MCP_ARCHITECTURE.md
+ */
+class WidgetCreatorMCP {
+    constructor(sessionId, agentId) {
+        this.memory = memory_client_js_1.MemoryClient.forAgent(agentId, 'widget-creator', sessionId);
+    }
+    /**
+     * Widget creation tool with full memory integration
+     */
+    async widget_create_structure(params) {
+        // 1. Read session context (as per MCP_ARCHITECTURE.md pattern)
+        const sessionContext = await this.memory.getSessionData();
+        const requirements = sessionContext.widget_requirements || {};
+        // Check for active agents
+        const activeAgents = await this.memory.getOperations().getActiveAgents(params.session_id);
+        logger.info('Active agents in session', {
+            count: activeAgents.length,
+            agents: activeAgents.map(a => ({ id: a.agent_id, type: a.agent_type, status: a.status }))
+        });
+        // 2. Execute ServiceNow operation (simulated)
+        const widgetResult = {
+            sys_id: `widget_${Date.now()}`,
+            name: params.widget_config.name,
+            title: params.widget_config.title,
+            status: 'created'
+        };
+        // 3. Update artifact tracking
+        if (params.update_memory) {
+            await this.memory.storeArtifact({
+                sys_id: widgetResult.sys_id,
+                type: 'widget',
+                name: params.widget_config.name,
+                description: `Widget created by ${params.agent_id}`,
+                status: 'created',
+                metadata: {
+                    category: params.widget_config.category,
+                    responsive: params.widget_config.responsive,
+                    created_from_requirements: requirements
+                }
+            });
+        }
+        // 4. Notify other agents via shared context
+        await this.memory.store({
+            key: 'widget_template_ready',
+            value: {
+                widget_sys_id: widgetResult.sys_id,
+                template_ready: true,
+                next_agent: 'ui_specialist'
+            }
+        });
+        // 5. Update coordination status
+        await this.memory.updateProgress(100);
+        // 6. Send handoff message
+        await this.memory.handoff({
+            to_agent: 'ui_specialist_001',
+            artifact_reference: widgetResult.sys_id,
+            data: {
+                styling_needed: true,
+                requirements: requirements.styling_requirements || {}
+            }
+        });
+        return widgetResult;
+    }
+    /**
+     * Performance-tracked operation example
+     */
+    async widget_generate_template(params) {
+        // Start performance tracking
+        const tracker = this.memory.trackOperation('generate_widget_template');
+        try {
+            // Simulate template generation
+            await new Promise(resolve => setTimeout(resolve, 50));
+            const template = {
+                html: '<div class="widget-container">...</div>',
+                type: params.template_type,
+                size: 1024
+            };
+            // Complete tracking with success
+            await tracker.complete(true, undefined, {
+                template_size: template.size,
+                template_type: params.template_type
+            });
+            return template;
+        }
+        catch (error) {
+            // Complete tracking with failure
+            await tracker.complete(false, error.message);
+            throw error;
+        }
+    }
+}
+/**
+ * Example Queen Agent coordination with memory
+ */
+class QueenCoordinationMCP {
+    constructor(sessionId) {
+        this.memory = memory_client_js_1.MemoryClient.forAgent('queen_001', 'queen', sessionId);
+    }
+    /**
+     * Monitor swarm progress using memory system
+     */
+    async queen_monitor_swarm(params) {
+        // Get session state from memory
+        const state = await this.memory.getSessionState();
+        // Analyze agent coordination
+        const agentStatus = state.agents.map(agent => ({
+            id: agent.agent_id,
+            type: agent.agent_type,
+            status: agent.status,
+            progress: agent.progress_percentage,
+            current_tool: agent.current_tool,
+            last_activity: agent.last_activity,
+            is_blocked: agent.status === 'blocked',
+            error: agent.error_state
+        }));
+        // Check for blocking issues
+        const blockingIssues = [];
+        // Check blocked agents
+        const blockedAgents = agentStatus.filter(a => a.is_blocked);
+        if (blockedAgents.length > 0) {
+            blockingIssues.push({
+                type: 'blocked_agents',
+                agents: blockedAgents,
+                recommendation: 'Check agent dependencies'
+            });
+        }
+        // Check failed deployments
+        const failedArtifacts = state.artifacts.filter(a => a.deployment_status === 'failed');
+        if (failedArtifacts.length > 0) {
+            blockingIssues.push({
+                type: 'failed_deployments',
+                artifacts: failedArtifacts,
+                recommendation: 'Review deployment errors and retry'
+            });
+        }
+        // Performance analysis
+        let performanceAnalysis = null;
+        if (params.detailed_metrics && state.performanceSummary) {
+            performanceAnalysis = {
+                total_operations: state.performanceSummary.total_operations,
+                avg_duration_ms: state.performanceSummary.avg_duration_ms,
+                success_rate: state.performanceSummary.success_rate,
+                slowest_operation_ms: state.performanceSummary.max_duration_ms,
+                recommendation: state.performanceSummary.avg_duration_ms > 100
+                    ? 'Performance below target (<100ms), consider optimization'
+                    : 'Performance meets requirements'
+            };
+        }
+        return {
+            session_id: params.session_id,
+            swarm_status: {
+                total_agents: state.agents.length,
+                active_agents: agentStatus.filter(a => a.status === 'active').length,
+                completed_agents: agentStatus.filter(a => a.status === 'completed').length,
+                blocked_agents: blockedAgents.length
+            },
+            agent_details: agentStatus,
+            artifacts_created: state.artifacts.length,
+            pending_messages: state.pendingMessages,
+            blocking_issues: blockingIssues,
+            performance_analysis: performanceAnalysis
+        };
+    }
+    /**
+     * Coordinate agent handoffs
+     */
+    async queen_coordinate_handoff(params) {
+        // Send coordination message
+        await this.memory.getOperations().sendMessage(this.memory.getSessionId(), 'queen_001', params.to_agent, 'coordination', {
+            handoff_from: params.from_agent,
+            artifact_type: params.artifact_type,
+            context: params.context_data,
+            coordination_time: new Date().toISOString()
+        });
+        // Update shared context for coordination
+        await this.memory.store({
+            key: `handoff_${params.from_agent}_to_${params.to_agent}`,
+            value: {
+                completed: true,
+                artifact_type: params.artifact_type,
+                timestamp: new Date().toISOString()
+            }
+        });
+    }
+}
+/**
+ * Example usage showing full integration
+ */
+async function demonstrateIntegration() {
+    logger.info('Starting MCP integration demonstration');
+    const sessionId = `demo_session_${Date.now()}`;
+    // Initialize MCPs
+    const widgetMCP = new WidgetCreatorMCP(sessionId, 'widget_creator_001');
+    const queenMCP = new QueenCoordinationMCP(sessionId);
+    try {
+        // Register agents
+        const widgetMemory = memory_client_js_1.MemoryClient.forAgent('widget_creator_001', 'widget-creator', sessionId);
+        const uiMemory = memory_client_js_1.MemoryClient.forAgent('ui_specialist_001', 'ui-specialist', sessionId);
+        await widgetMemory.register(['create_dashboard_widget']);
+        await uiMemory.register(['style_widget']);
+        // Store requirements in memory (simulating earlier analysis)
+        await widgetMemory.store({
+            key: 'widget_requirements',
+            value: {
+                type: 'dashboard',
+                data_sources: ['incident', 'problem'],
+                styling_requirements: {
+                    theme: 'modern',
+                    responsive: true
+                }
+            }
+        });
+        logger.info('Step 1: Widget creation with memory integration');
+        // Create widget using MCP tool
+        const widgetResult = await widgetMCP.widget_create_structure({
+            session_id: sessionId,
+            widget_config: {
+                name: 'incident_dashboard',
+                title: 'Incident Dashboard',
+                category: 'custom',
+                responsive: true
+            },
+            agent_id: 'widget_creator_001',
+            update_memory: true
+        });
+        logger.info('Widget created', widgetResult);
+        logger.info('Step 2: Generate template with performance tracking');
+        // Generate template
+        const template = await widgetMCP.widget_generate_template({
+            requirements: { charts: true, filters: true },
+            template_type: 'dashboard'
+        });
+        logger.info('Template generated', { size: template.size });
+        logger.info('Step 3: Queen monitors swarm progress');
+        // Queen monitors progress
+        const swarmStatus = await queenMCP.queen_monitor_swarm({
+            session_id: sessionId,
+            detailed_metrics: true
+        });
+        logger.info('Swarm status', JSON.stringify(swarmStatus, null, 2));
+        logger.info('Step 4: UI specialist checks for handoffs');
+        // UI specialist checks messages
+        const handoffs = await uiMemory.checkHandoffs();
+        logger.info('UI specialist received handoffs', handoffs);
+        logger.info('Step 5: Check performance metrics');
+        // Get performance stats
+        const perfStats = await widgetMemory.getPerformanceStats('generate_widget_template');
+        logger.info('Performance statistics', perfStats);
+        logger.info('Integration demonstration completed successfully!');
+    }
+    catch (error) {
+        logger.error('Integration demonstration failed', error);
+        throw error;
+    }
+    finally {
+        // Cleanup
+        memory_client_js_1.MemoryClient.shutdown();
+    }
+}
+// Run demonstration if called directly
+if (require.main === module) {
+    demonstrateIntegration()
+        .then(() => {
+        logger.info('MCP integration demonstration completed');
+        process.exit(0);
+    })
+        .catch((error) => {
+        logger.error('MCP integration demonstration failed', error);
+        process.exit(1);
+    });
+}

package/dist/memory/memory-client.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Snow-Flow Memory Client
+ * Simple API for agents to interact with the memory system
+ */
+import { SwarmMemory, SwarmMemoryConfig } from './swarm-memory.js';
+import { MemoryOperations } from './memory-operations.js';
+export interface MemoryClientConfig extends SwarmMemoryConfig {
+    sessionId?: string;
+    agentId?: string;
+    agentType?: string;
+}
+export interface MemoryStoreOptions {
+    key: string;
+    value: any;
+    expires?: Date;
+    permissions?: string[];
+}
+export interface MemoryRetrieveOptions {
+    key: string;
+    defaultValue?: any;
+}
+export interface ArtifactInfo {
+    sys_id: string;
+    type: 'widget' | 'flow' | 'script' | 'business_rule' | 'table' | 'catalog_item';
+    name: string;
+    description?: string;
+    status?: 'created' | 'tested' | 'deployed' | 'verified' | 'failed';
+    update_set_id?: string;
+    dependencies?: string[];
+    metadata?: any;
+}
+export interface AgentHandoff {
+    to_agent: string;
+    artifact_reference?: string;
+    data: any;
+}
+export interface PerformanceTracker {
+    complete(success: boolean, error?: string, metadata?: any): Promise<void>;
+}
+export declare class MemoryClient {
+    private memory;
+    private operations;
+    private logger;
+    private sessionId;
+    private agentId;
+    private agentType;
+    constructor(config?: MemoryClientConfig);
+    /**
+     * Store data in shared context
+     */
+    store(options: MemoryStoreOptions): Promise<void>;
+    /**
+     * Retrieve data from shared context with agent isolation
+     */
+    retrieve(options: MemoryRetrieveOptions): Promise<any>;
+    /**
+     * Retrieve data from truly shared context (no agent isolation)
+     * Use this when agents need to access shared coordination data
+     */
+    retrieveShared(options: MemoryRetrieveOptions): Promise<any>;
+    /**
+     * Store data in truly shared context (no agent isolation)
+     * Use this when you want all agents to access the same data
+     */
+    storeShared(options: MemoryStoreOptions): Promise<void>;
+    /**
+     * Get all context for current session
+     */
+    getSessionData(): Promise<Record<string, any>>;
+    /**
+     * Register current agent
+     */
+    register(assignedTasks?: string[]): Promise<void>;
+    /**
+     * Update agent progress
+     */
+    updateProgress(percentage: number, currentTool?: string): Promise<void>;
+    /**
+     * Mark agent as completed
+     */
+    complete(): Promise<void>;
+    /**
+     * Report agent error
+     */
+    reportError(error: string): Promise<void>;
+    /**
+     * Check if agent should wait for dependencies
+     */
+    checkDependencies(): Promise<boolean>;
+    /**
+     * Store ServiceNow artifact information
+     */
+    storeArtifact(artifact: ArtifactInfo): Promise<void>;
+    /**
+     * Update artifact status
+     */
+    updateArtifactStatus(sys_id: string, status: 'created' | 'tested' | 'deployed' | 'verified' | 'failed'): Promise<void>;
+    /**
+     * Find artifacts created in current session
+     */
+    findSessionArtifacts(type?: ArtifactInfo['type']): Promise<ArtifactInfo[]>;
+    /**
+     * Send handoff to another agent
+     */
+    handoff(handoff: AgentHandoff): Promise<void>;
+    /**
+     * Check for incoming handoffs
+     */
+    checkHandoffs(): Promise<Array<{
+        from: string;
+        data: any;
+        artifact_reference?: string;
+    }>>;
+    /**
+     * Send status update
+     */
+    sendStatus(status: string, details?: any): Promise<void>;
+    /**
+     * Report dependency ready
+     */
+    reportDependencyReady(dependent_agent: string, artifact_reference?: string): Promise<void>;
+    /**
+     * Start tracking an operation
+     */
+    trackOperation(operation: string): PerformanceTracker;
+    /**
+     * Get average performance for an operation
+     */
+    getPerformanceStats(operation: string): Promise<{
+        avgDuration: number;
+        successRate: number;
+        totalOperations: number;
+    } | null>;
+    /**
+     * Record successful deployment
+     */
+    recordDeployment(artifact_sys_id: string, type: 'create' | 'update' | 'test' | 'verify' | 'rollback', success?: boolean, error?: string): Promise<void>;
+    /**
+     * Get deployment history for an artifact
+     */
+    getDeploymentHistory(artifact_sys_id: string): Promise<Array<{
+        type: string;
+        success: boolean;
+        time: Date;
+        agent: string;
+        error?: string;
+    }>>;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Get current agent ID
+     */
+    getAgentId(): string;
+    /**
+     * Get complete session state
+     */
+    getSessionState(): Promise<any>;
+    /**
+     * Clean up current session
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get memory statistics
+     */
+    getStats(): Record<string, any>;
+    /**
+     * Run memory cleanup
+     */
+    runCleanup(): Promise<void>;
+    /**
+     * Get direct access to operations (for advanced use cases)
+     */
+    getOperations(): MemoryOperations;
+    /**
+     * Get direct access to database (for custom queries)
+     */
+    getDatabase(): SwarmMemory;
+    /**
+     * Create a memory client for an agent
+     */
+    static forAgent(agentId: string, agentType: string, sessionId?: string): MemoryClient;
+    /**
+     * Create a memory client for a session
+     */
+    static forSession(sessionId: string): MemoryClient;
+    /**
+     * Close all connections (call when shutting down)
+     */
+    static shutdown(): void;
+    private generateSessionId;
+    /**
+     * COMPATIBILITY FIX: makeRequest method for phantom calls
+     * MemoryClient doesn't use HTTP requests, so this is a no-op fallback
+     */
+    makeRequest(config: any): Promise<any>;
+}
+//# sourceMappingURL=memory-client.d.ts.map