snow-flow 2.10.0 → 3.0.0

package/src/memory/README.md

@@ -0,0 +1,240 @@
+# Snow-Flow Memory System
+
+The Snow-Flow memory system provides SQLite-based persistent storage for agent coordination, artifact tracking, and performance monitoring. It's designed to meet the requirements specified in MCP_ARCHITECTURE.md with fast queries (<100ms), thread-safe operations, and automatic schema migration.
+
+## Architecture
+
+The memory system consists of three main components:
+
+### 1. SwarmMemory (`swarm-memory.ts`)
+- Core SQLite database management
+- Schema creation and migration
+- Performance optimization
+- Thread-safe operations with WAL mode
+
+### 2. MemoryOperations (`memory-operations.ts`)
+- High-level operations for data storage/retrieval
+- Agent coordination management
+- Artifact tracking
+- Performance monitoring
+- Message passing between agents
+
+### 3. MemoryClient (`memory-client.ts`)
+- Simple API for agents
+- Automatic session tracking
+- Performance tracking helpers
+- Simplified context storage
+
+## Database Schema
+
+The system implements all tables specified in MCP_ARCHITECTURE.md:
+
+- **agent_coordination**: Track agent status and progress
+- **servicenow_artifacts**: Store created artifacts
+- **agent_messages**: Inter-agent communication
+- **shared_context**: Session-wide shared data
+- **deployment_history**: Track deployments
+- **agent_dependencies**: Manage agent dependencies
+- **performance_metrics**: Performance monitoring
+
+## Usage
+
+### Basic Agent Usage
+
+```typescript
+import { MemoryClient } from './memory/index.js';
+
+// Create a memory client for an agent
+const memory = MemoryClient.forAgent(
+  'widget_creator_001',  // agent ID
+  'widget-creator',      // agent type
+  'session_123'          // session ID
+);
+
+// Register the agent
+await memory.register(['create_dashboard_widget']);
+
+// Update progress
+await memory.updateProgress(50, 'creating_template');
+
+// Store shared data
+await memory.store({
+  key: 'widget_config',
+  value: {
+    name: 'incident_dashboard',
+    features: ['charts', 'filters']
+  }
+});
+
+// Retrieve shared data
+const config = await memory.retrieve({ key: 'widget_config' });
+
+// Track performance
+const tracker = memory.trackOperation('widget_creation');
+// ... do work ...
+await tracker.complete(true);
+
+// Mark as completed
+await memory.complete();
+```
+
+### Artifact Management
+
+```typescript
+// Store artifact information
+await memory.storeArtifact({
+  sys_id: 'widget_12345',
+  type: 'widget',
+  name: 'Incident Dashboard',
+  status: 'created',
+  metadata: { version: '1.0' }
+});
+
+// Update artifact status
+await memory.updateArtifactStatus('widget_12345', 'deployed');
+
+// Find artifacts
+const widgets = await memory.findSessionArtifacts('widget');
+```
+
+### Agent Communication
+
+```typescript
+// Send handoff to another agent
+await memory.handoff({
+  to_agent: 'ui_specialist_001',
+  artifact_reference: 'widget_12345',
+  data: {
+    template_ready: true,
+    next_steps: ['add_styling', 'test_responsiveness']
+  }
+});
+
+// Check for incoming handoffs
+const handoffs = await memory.checkHandoffs();
+for (const handoff of handoffs) {
+  console.log(`Received from ${handoff.from}:`, handoff.data);
+}
+
+// Report dependency ready
+await memory.reportDependencyReady('test_agent_001', 'widget_12345');
+```
+
+### Performance Monitoring
+
+```typescript
+// Track operation performance
+const tracker = memory.trackOperation('api_call');
+try {
+  // ... perform operation ...
+  await tracker.complete(true, undefined, { 
+    response_time: 150,
+    records_processed: 100 
+  });
+} catch (error) {
+  await tracker.complete(false, error.message);
+}
+
+// Get performance statistics
+const stats = await memory.getPerformanceStats('api_call');
+console.log(`Average duration: ${stats.avgDuration}ms`);
+console.log(`Success rate: ${stats.successRate * 100}%`);
+```
+
+### Session Management
+
+```typescript
+// Get complete session state
+const state = await memory.getSessionState();
+console.log('Active agents:', state.agents);
+console.log('Created artifacts:', state.artifacts);
+console.log('Performance summary:', state.performanceSummary);
+
+// Clean up session when done
+await memory.cleanup();
+```
+
+## Advanced Usage
+
+### Direct Database Access
+
+For custom queries, you can access the underlying database:
+
+```typescript
+const db = memory.getDatabase();
+const results = db.all(`
+  SELECT * FROM servicenow_artifacts 
+  WHERE deployment_status = 'failed'
+  ORDER BY updated_at DESC
+`);
+```
+
+### Custom Operations
+
+Access the operations layer for advanced functionality:
+
+```typescript
+const ops = memory.getOperations();
+
+// Search messages with custom criteria
+const messages = await ops.searchMessages({
+  message_type: 'error',
+  processed: false,
+  limit: 10
+});
+
+// Get deployment history
+const history = await ops.getDeploymentHistory('artifact_123');
+```
+
+## Performance Optimization
+
+The memory system is optimized for performance:
+
+1. **WAL Mode**: Enables concurrent reads
+2. **Indexes**: Fast queries on common fields
+3. **Prepared Statements**: Reusable query plans
+4. **Connection Pooling**: Single shared instance
+5. **Batch Operations**: Transaction support
+
+## Best Practices
+
+1. **Always register agents** before performing operations
+2. **Use transactions** for multiple related operations
+3. **Clean up sessions** when work is complete
+4. **Track performance** for critical operations
+5. **Store minimal data** in shared context
+6. **Use appropriate expiration** for temporary data
+7. **Handle errors gracefully** with try-catch blocks
+
+## Testing
+
+Run the test suite to verify functionality:
+
+```bash
+npm run test:memory
+# or
+node dist/memory/memory-test.js
+```
+
+## Monitoring
+
+Check memory statistics:
+
+```typescript
+const stats = memory.getStats();
+console.log('Database statistics:', stats);
+
+// Run cleanup for old data
+await memory.runCleanup();
+```
+
+## Shutdown
+
+Always shutdown the memory system when done:
+
+```typescript
+MemoryClient.shutdown();
+```
+
+This ensures all connections are properly closed and data is flushed to disk.

package/src/queen/README.md

@@ -0,0 +1,403 @@
+# ServiceNow Queen Agent 🐝
+
+> **Hive-Mind Intelligence for ServiceNow Development**
+> 
+> A single coordination point that spawns specialized agents dynamically, learns from deployments, and orchestrates complex ServiceNow tasks with elegance through simplicity.
+
+## ⚠️ IMPORTANT: Flow Creation Removed in v1.4.38 ⚠️
+
+**Note**: All flow-related functionality has been permanently removed from Snow-Flow. Please use ServiceNow's native Flow Designer interface directly for flow creation. All other agent types and functionality continue to work normally.
+
+## Philosophy: Claude-Flow Principles
+
+The ServiceNow Queen Agent follows snow-flow philosophy:
+
+- **🎯 Single Coordination Point**: All tasks go through the Queen
+- **⚡ Dynamic Agent Spawning**: Creates agents based on task needs, not pre-defined teams  
+- **🧠 Hive-Mind Intelligence**: Coordinates multiple agents seamlessly with shared memory
+- **💾 Simple Memory**: Uses SQLite for persistent learning across sessions
+- **📚 Neural Learning**: Learns from past deployments and adapts patterns
+
+## Architecture
+
+```
+ServiceNow Queen Agent
+├── 🐝 ServiceNowQueen (Main Coordinator)
+├── 🏭 AgentFactory (Dynamic Agent Spawning)  
+├── 💾 QueenMemorySystem (SQLite Persistence)
+├── 🧠 NeuralLearning (Pattern Recognition)
+└── 🔧 Agent Types (8 Specialized Agents)
+```
+
+## Quick Start
+
+```typescript
+import { createServiceNowQueen } from './queen';
+
+// Create Queen with hive-mind intelligence
+const queen = createServiceNowQueen({
+  debugMode: true,
+  maxConcurrentAgents: 5
+});
+
+// Execute any ServiceNow objective - Queen handles everything
+const result = await queen.executeObjective(
+  "create incident dashboard with real-time charts and mobile responsiveness"
+);
+
+console.log('✅ Deployment completed:', result);
+```
+
+## Core Components
+
+### 1. ServiceNow Queen (Main Coordinator)
+
+The central intelligence that:
+- Analyzes objectives using neural learning
+- Spawns optimal agent swarms dynamically
+- Coordinates execution with MCP tools
+- Learns from success/failure patterns
+
+```typescript
+const queen = new ServiceNowQueen({
+  memoryPath: './.snow-flow/queen-memory.db',
+  maxConcurrentAgents: 8,
+  learningRate: 0.1,
+  debugMode: true
+});
+
+// One command does everything
+await queen.executeObjective("create incident dashboard widget with real-time updates");
+```
+
+### 2. Dynamic Agent Factory
+
+Spawns specialized agents on-demand based on task analysis:
+
+```typescript
+// 8 Available Agent Types
+- widget-creator     → HTML, CSS, JS, ServiceNow widgets
+- script-writer      → Business rules, script includes, client scripts
+- app-architect      → System design, table structures, modules
+- integration-specialist → APIs, data sync, external systems
+- catalog-manager    → Service catalog, request items, variables
+- researcher         → Analysis, discovery, best practices  
+- tester            → Quality assurance, mock testing, validation
+```
+
+### 3. Persistent Memory System
+
+Simple SQLite-based learning that persists across sessions:
+
+```sql
+-- Stores successful deployment patterns
+CREATE TABLE patterns (
+  task_type TEXT,
+  success_rate REAL,
+  agent_sequence TEXT,
+  avg_duration INTEGER
+);
+
+-- Remembers created artifacts
+CREATE TABLE artifacts (
+  type TEXT,
+  name TEXT, 
+  sys_id TEXT,
+  dependencies TEXT
+);
+
+-- Learns from experiences
+CREATE TABLE learnings (
+  key TEXT,
+  value TEXT,
+  confidence REAL
+);
+```
+
+### 4. Neural Learning Engine
+
+Pattern recognition that improves over time:
+
+- **Task Classification**: Widget vs Script vs Application
+- **Complexity Estimation**: Based on keyword analysis and learned weights
+- **Agent Selection**: Optimal sequence based on successful patterns
+- **Success/Failure Learning**: Adjusts confidence weights dynamically
+
+## Execution Flow
+
+```mermaid
+graph TD
+    A[Objective Input] --> B[Neural Analysis]
+    B --> C[Task Classification]
+    C --> D[Complexity Estimation]  
+    D --> E[Agent Spawning]
+    E --> F[Swarm Coordination]
+    F --> G[MCP Tool Execution]
+    G --> H[Deployment Result]
+    H --> I[Pattern Learning]
+    I --> J[Memory Storage]
+```
+
+## Usage Examples
+
+### Simple Widget Creation
+
+```typescript
+await queen.executeObjective("create incident dashboard");
+
+// Queen automatically:
+// 1. Classifies as 'widget' task
+// 2. Spawns: widget-creator → tester
+// 3. Generates HTML, CSS, JS code
+// 4. Deploys using snow_deploy MCP tool
+// 5. Learns from success for future widget tasks
+```
+
+### Complex Widget with Integration
+
+```typescript
+await queen.executeObjective(
+  "create equipment request dashboard with external API integration"
+);
+
+// Queen automatically:
+// 1. Classifies as 'widget' task (high complexity)
+// 2. Spawns: researcher → widget-creator → integration-specialist → tester  
+// 3. Coordinates sequential execution with agent communication
+// 4. Uses snow_deploy + snow_create_rest_message
+// 5. Learns optimal agent sequence for similar future tasks
+```
+
+### Application Development
+
+```typescript
+await queen.executeObjective(
+  "build complete ITSM solution with custom tables and workflows"
+);
+
+// Queen automatically:
+// 1. Classifies as 'application' task (very high complexity)
+// 2. Spawns: researcher → app-architect → script-writer → widget-creator → tester
+// 3. Coordinates with shared memory between agents
+// 4. Uses multiple MCP tools in optimal sequence
+// 5. Stores deployment pattern for future application tasks
+```
+
+## Learning & Adaptation
+
+The Queen learns from every deployment:
+
+### Success Patterns
+```typescript
+// Queen remembers successful patterns
+{
+  taskType: 'widget',
+  successRate: 0.92,
+  agentSequence: ['widget-creator', 'tester'],
+  avgDuration: 45000,
+  mcpSequence: ['snow_deploy', 'snow_widget_test']
+}
+```
+
+### Failure Recovery
+```typescript
+// Queen learns from failures and adapts
+queen.learnFromFailure(task, 'Permission denied', ['widget-creator']);
+// Next time: adds 'researcher' to check permissions first
+```
+
+### Neural Weight Adjustment
+```typescript
+// Adjusts confidence in complexity factors
+{
+  factor: 'chart_integration',
+  weight: 0.3,
+  confidence: 0.9  // High confidence after successful chart deployments
+}
+```
+
+## Agent Coordination
+
+### Parallel Execution
+Independent agents (researcher, tester, script-writer) run simultaneously:
+
+```typescript
+// Parallel execution for speed
+const results = await Promise.all([
+  researcherAgent.execute(),
+  testerAgent.execute(),
+  scriptAgent.execute()
+]);
+```
+
+### Sequential Coordination
+Dependent agents execute in optimal sequence:
+
+```typescript
+// Sequential with shared context
+researcher → widget-creator → tester
+//           ↓ shares findings ↓
+//        widget-creator uses research
+//                          ↓ receives widget
+//                       tester validates
+```
+
+### Message Passing
+Agents communicate through the Queen:
+
+```typescript
+// Agent coordination
+this.agentFactory.sendAgentMessage(
+  fromAgent: 'researcher',
+  toAgent: 'widget-creator', 
+  type: 'result',
+  content: { findings: '...', recommendations: '...' }
+);
+```
+
+## Memory Management
+
+### Artifact Tracking
+```typescript
+// Stores all created artifacts
+queen.memory.storeArtifact({
+  type: 'widget',
+  name: 'incident_dashboard_widget', 
+  sys_id: 'abc123...',
+  config: { /* widget config */ },
+  dependencies: ['Chart.js library']
+});
+```
+
+### Pattern Reuse
+```typescript
+// Reuses successful patterns
+const bestPattern = queen.memory.getBestPattern('widget');
+if (bestPattern.successRate > 0.8) {
+  // Use proven agent sequence
+  agents = spawnAgents(bestPattern.agentSequence);
+}
+```
+
+### Cross-Session Learning
+```typescript
+// Persistent learning across sessions
+queen.memory.storeLearning(
+  'widget_chart_integration',
+  'Always include Chart.js for dashboard widgets',
+  confidence: 0.95
+);
+```
+
+## Status & Monitoring
+
+```typescript
+// Real-time hive-mind status
+const status = queen.getHiveMindStatus();
+console.log(status);
+/*
+{
+  activeTasks: 2,
+  activeAgents: 5,
+  memoryStats: {
+    patterns: 24,
+    artifacts: 156,
+    learnings: 89
+  },
+  factoryStats: {
+    totalActiveAgents: 5,
+    agentTypeCounts: { 'widget-creator': 2, 'tester': 1 }
+  }
+}
+*/
+```
+
+## Integration with Existing MCP Tools
+
+The Queen uses existing MCP servers as "tools" for agents:
+
+```typescript
+// Widget agents use these MCP tools:
+- snow_deploy (unified deployment)
+- snow_preview_widget
+- snow_widget_test
+
+// Script agents use these MCP tools:  
+- snow_create_script_include
+- snow_create_business_rule
+- snow_create_client_script
+
+// All agents coordinate through Queen
+```
+
+## Advantages Over Team System
+
+| Old Team System | New Queen System |
+|-----------------|------------------|
+| 🐌 Pre-defined teams | ⚡ Dynamic agent spawning |
+| 🔧 Fixed capabilities | 🎯 Task-optimized agents |
+| 📋 Manual coordination | 🤖 Autonomous hive-mind |
+| 💾 No learning | 🧠 Continuous adaptation |
+| 🔄 Complex orchestration | ✨ Elegant simplicity |
+
+## Configuration
+
+```typescript
+const queen = new ServiceNowQueen({
+  // Memory persistence
+  memoryPath: './.snow-flow/queen/memory.db',
+  
+  // Agent management
+  maxConcurrentAgents: 8,
+  
+  // Learning parameters
+  learningRate: 0.1,
+  
+  // Development mode
+  debugMode: process.env.NODE_ENV === 'development'
+});
+```
+
+## Export & Backup
+
+```typescript
+// Export all learned patterns and memories
+const backup = queen.exportMemory();
+fs.writeFileSync('queen-backup.json', backup);
+
+// Queen automatically creates SQLite backups
+// .snow-flow/queen/memory.db
+```
+
+## Philosophy in Action
+
+The Queen embodies **snow-flow principles**:
+
+### 1. Elegance through Simplicity
+- **One entry point**: `queen.executeObjective()`
+- **No complex configuration**: Works out of the box
+- **Natural language**: "create incident dashboard" → complete deployment
+
+### 2. Intelligence through Learning
+- **Remembers what works**: Successful patterns are reused
+- **Adapts to failures**: Learns from errors and adjusts
+- **Improves over time**: Gets better with each deployment
+
+### 3. Coordination through Simplicity
+- **No manual orchestration**: Agents coordinate automatically
+- **Clear responsibilities**: Each agent type has focused capabilities
+- **Simple communication**: Message passing through Queen
+
+## Future Evolution
+
+The Queen will evolve while maintaining simplicity:
+
+- **🔌 MCP Tool Integration**: Deeper integration with all ServiceNow MCPs
+- **🎯 Specialized Agents**: New agent types for specific ServiceNow domains
+- **🧠 Advanced Learning**: More sophisticated pattern recognition
+- **⚡ Performance Optimization**: Faster agent spawning and coordination
+- **🔐 Security Integration**: Security-aware deployment patterns
+
+---
+
+*Built with ❤️ following snow-flow philosophy: Elegance through simplicity, intelligence through learning.*

package/src/schemas/deployment.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ServiceNow Deployment Configuration Schema",
+  "description": "Schema for validating ServiceNow artifact deployment configurations",
+  "type": "object",
+  "required": ["type"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["widget", "flow", "application", "script", "business_rule", "table"],
+      "description": "Type of artifact to deploy"
+    },
+    "config": {
+      "type": "object",
+      "description": "Artifact configuration (varies by type)"
+    },
+    "auto_update_set": {
+      "type": "boolean",
+      "default": true,
+      "description": "Automatically ensure active Update Set session"
+    },
+    "deployment_context": {
+      "type": "string",
+      "description": "Context for Update Set naming"
+    },
+    "fallback_strategy": {
+      "type": "string",
+      "enum": ["manual_steps", "update_set_only", "none"],
+      "default": "manual_steps",
+      "description": "Strategy when direct deployment fails"
+    },
+    "permission_escalation": {
+      "type": "string",
+      "enum": ["auto_request", "manual", "none"],
+      "default": "auto_request",
+      "description": "How to handle permission errors"
+    },
+    "scope_preference": {
+      "type": "string",
+      "enum": ["global", "application", "auto"],
+      "default": "auto",
+      "description": "Preferred deployment scope"
+    },
+    "validation_level": {
+      "type": "string",
+      "enum": ["basic", "standard", "comprehensive"],
+      "default": "standard",
+      "description": "Level of validation to perform"
+    },
+    "environment": {
+      "type": "string",
+      "enum": ["development", "testing", "production"],
+      "default": "development",
+      "description": "Target deployment environment"
+    }
+  },
+  "additionalProperties": false
+}