snow-flow 8.3.2 → 8.4.1

package/OPENCODE-SETUP.md

@@ -0,0 +1,312 @@
+# OpenCode Setup Guide for Snow-Flow
+
+This guide explains how to properly configure OpenCode to use Snow-Flow's MCP tools.
+
+## Quick Start
+
+### 1. Copy Example Config
+
+```bash
+cp opencode-config.example.json opencode-config.json
+```
+
+### 2. Update Environment Variables
+
+Edit `opencode-config.json` and replace the `${VARIABLE}` placeholders with your actual values:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "name": "snow-flow-opencode",
+  "description": "OpenCode configuration for Snow-Flow ServiceNow development",
+  "model": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-5-20250929",
+    "temperature": 1.0
+  },
+  "mcp": {
+    "servicenow-unified": {
+      "type": "local",
+      "command": ["node", "dist/mcp/servicenow-mcp-unified/index.js"],
+      "environment": {
+        "SNOW_INSTANCE": "your-instance.service-now.com",
+        "SNOW_CLIENT_ID": "your-client-id",
+        "SNOW_CLIENT_SECRET": "your-client-secret",
+        "SNOW_USERNAME": "your-username",
+        "SNOW_PASSWORD": "your-password"
+      },
+      "enabled": true
+    },
+    "snow-flow": {
+      "type": "local",
+      "command": ["node", "dist/mcp/snow-flow-mcp.js"],
+      "environment": {
+        "SNOW_FLOW_ENV": "production"
+      },
+      "enabled": true
+    }
+  },
+  "tools": {
+    "enabled": true,
+    "requireApproval": false
+  },
+  "theme": "servicenow",
+  "instructions": [
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".opencode/AGENTS.md"
+  ],
+  "cwd": "/path/to/your/snow-flow/installation"
+}
+```
+
+### 3. Build Snow-Flow
+
+```bash
+npm run build
+```
+
+This creates the `dist/` directory with the MCP server files.
+
+### 4. Start OpenCode
+
+```bash
+opencode
+```
+
+## Critical Configuration Details
+
+### ⚠️ Common Mistakes
+
+1. **Using `"env"` instead of `"environment"`**
+   ```json
+   // ❌ WRONG - Tools won't load!
+   "env": { "SNOW_INSTANCE": "..." }
+
+   // ✅ CORRECT
+   "environment": { "SNOW_INSTANCE": "..." }
+   ```
+
+2. **Wrong command path**
+   ```json
+   // ❌ WRONG - File doesn't exist
+   "command": ["node", "src/mcp/servicenow-mcp-unified/index.js"]
+
+   // ✅ CORRECT - Must point to dist/ after build
+   "command": ["node", "dist/mcp/servicenow-mcp-unified/index.js"]
+   ```
+
+3. **Forgetting to build**
+   - Always run `npm run build` after pulling updates
+   - The `dist/` directory must exist before starting OpenCode
+
+### Environment Variables
+
+**Required for ServiceNow MCP:**
+- `SNOW_INSTANCE` - Your ServiceNow instance URL (e.g., `dev12345.service-now.com`)
+- `SNOW_CLIENT_ID` - OAuth client ID
+- `SNOW_CLIENT_SECRET` - OAuth client secret
+- `SNOW_USERNAME` - ServiceNow username
+- `SNOW_PASSWORD` - ServiceNow password
+
+**Optional for Snow-Flow MCP:**
+- `SNOW_FLOW_ENV` - Environment (default: `production`)
+
+## Verifying MCP Tools are Loaded
+
+### Check Tool Availability
+
+When OpenCode starts, you should see the MCP servers loading in the logs:
+
+```
+[MCP] Loading servicenow-unified...
+[MCP] Loaded 370+ tools from servicenow-unified
+[MCP] Loading snow-flow...
+[MCP] Loaded 176+ tools from snow-flow
+```
+
+### Test Tool Execution
+
+In OpenCode, try a simple command:
+
+```
+Create an Update Set named "Test Update Set"
+```
+
+The agent should:
+1. ✅ Call `snow_update_set_manage()` function
+2. ✅ Show the actual function call in the response
+3. ✅ Return the Update Set sys_id
+
+**If the agent only shows code snippets instead of calling tools, check:**
+- Is `opencode-config.json` using `"environment"` (not `"env"`)?
+- Did you run `npm run build` after updating Snow-Flow?
+- Are the MCP servers enabled (`"enabled": true`)?
+- Do the `dist/` files exist?
+
+## MCP Tool Categories
+
+### ServiceNow Unified MCP (370+ tools)
+
+**Core Operations:**
+- `snow_query_table` - Query any ServiceNow table
+- `snow_create_record` - Create records
+- `snow_update_record` - Update records
+
+**Development:**
+- `snow_update_set_manage` - Manage Update Sets (v8.2.0+)
+- `snow_deploy` - Deploy widgets, pages, etc.
+- `snow_pull_artifact` - Local widget sync
+
+**UI Builder:**
+- `snow_create_uib_page` - Create UI Builder pages
+- `snow_add_uib_page_element` - Add components
+- `snow_create_uib_data_broker` - Connect data sources
+
+**Workspace:**
+- `snow_create_complete_workspace` - Create agent workspaces
+- `snow_create_workspace_tab` - Add tabs
+
+### Snow-Flow MCP (176+ tools)
+
+**Orchestration:**
+- `swarm_init` - Initialize agent swarms
+- `agent_spawn` - Create specialized agents
+- `task_orchestrate` - Complex task coordination
+
+**Memory:**
+- `memory_search` - Search persistent memory
+- `memory_usage` - Memory analytics
+
+**ML (TensorFlow.js):**
+- `neural_train` - Train neural networks
+- `neural_patterns` - Pattern recognition
+
+## Troubleshooting
+
+### Problem: "Tools not available"
+
+**Solution:**
+1. Check `opencode-config.json` exists
+2. Verify `"environment"` key (not `"env"`)
+3. Run `npm run build`
+4. Restart OpenCode
+
+### Problem: "Agent shows code instead of calling tools"
+
+This usually means the MCP servers aren't loaded correctly.
+
+**Solution:**
+1. Check OpenCode logs for MCP loading errors
+2. Verify `dist/` directory exists
+3. Check command paths in config
+4. Ensure `"enabled": true`
+
+### Problem: "Module not found" errors
+
+**Solution:**
+```bash
+# Rebuild everything
+npm run build
+
+# Verify dist files exist
+ls -la dist/mcp/servicenow-mcp-unified/index.js
+ls -la dist/mcp/snow-flow-mcp.js
+```
+
+## Advanced Configuration
+
+### Per-Agent Tool Control
+
+Disable tools globally but enable for specific agents:
+
+```json
+{
+  "mcp": {
+    "servicenow-unified": { "enabled": true }
+  },
+  "tools": {
+    "servicenow-unified*": false  // Disable all by default
+  },
+  "agent": {
+    "servicenow-dev": {
+      "tools": {
+        "servicenow-unified*": true  // Enable for this agent
+      }
+    }
+  }
+}
+```
+
+### Custom Tool Approval
+
+Require approval for specific tools:
+
+```json
+{
+  "tools": {
+    "enabled": true,
+    "requireApproval": true,
+    "approvalPatterns": {
+      "snow_execute_background_script": true,  // Always require approval
+      "snow_update_set_manage": false          // Auto-approve
+    }
+  }
+}
+```
+
+## Best Practices
+
+### 1. Always Create Update Sets First
+
+```javascript
+// ✅ CORRECT workflow
+const updateSet = await snow_update_set_manage({
+  action: 'create',
+  name: "Feature: X"
+});
+// ... develop ...
+await snow_update_set_manage({ action: 'complete' });
+```
+
+### 2. Use Specific Tools Over Generic
+
+```javascript
+// ❌ Generic (slower)
+await snow_query_table({ table: 'incident' });
+
+// ✅ Specific (faster, better features)
+await snow_query_incidents({ filters: { active: true } });
+```
+
+### 3. Use Local Sync for Widgets
+
+```javascript
+// ✅ CORRECT - No token limits!
+await snow_pull_artifact({ sys_id: 'widget_sys_id' });
+// ... edit locally ...
+await snow_push_artifact({ sys_id: 'widget_sys_id' });
+
+// ❌ WRONG - Token limits!
+await snow_query_table({ table: 'sp_widget' });
+```
+
+## Getting Help
+
+If you encounter issues:
+
+1. **Check logs**: OpenCode shows detailed MCP loading logs
+2. **Verify config**: Use `"environment"` (not `"env"`)
+3. **Rebuild**: Always `npm run build` after updates
+4. **GitHub Issues**: https://github.com/your-repo/snow-flow/issues
+
+## Version Info
+
+- **OpenCode**: Requires OpenCode v1.0+
+- **Snow-Flow**: v8.3.0+
+- **Node.js**: v18+ recommended
+- **MCP Spec**: 1.0.0
+
+---
+
+**Last Updated**: 2025-10-22 (v8.3.0)

package/OPENCODE-TROUBLESHOOTING.md

@@ -0,0 +1,381 @@
+# OpenCode MCP Troubleshooting Guide
+
+## Problem: "Tools not available" or Agent Shows Code Instead of Calling Tools
+
+### Root Causes
+
+There are TWO independent issues that can cause this:
+
+1. **MCP Configuration Issue** (`"env"` vs `"environment"`)
+2. **ServiceNow Authentication Failure** (OAuth without refresh token)
+
+Both have been fixed in v8.3.1+!
+
+---
+
+## ✅ Solution 1: Use Updated Configuration (v8.3.1+)
+
+### Quick Fix
+
+```bash
+# Update to v8.3.1+
+npm install -g snow-flow@latest
+
+# Use the new launcher (handles everything)
+cd your-project
+./node_modules/snow-flow/scripts/start-opencode.sh
+```
+
+The launcher will:
+- ✅ Check .env file exists
+- ✅ Build Snow-Flow if needed
+- ✅ Start MCP servers automatically
+- ✅ Run health checks
+- ✅ Launch OpenCode with tools pre-loaded
+
+---
+
+## ✅ Solution 2: Manual Setup (Understanding the Fix)
+
+### Step 1: Fix Authentication
+
+**Option A: Use Username/Password (Simpler)**
+
+Edit your `.env` file:
+
+```bash
+# ServiceNow Configuration
+SNOW_INSTANCE=dev123456.service-now.com
+
+# Use username/password (NEW in v8.3.1!)
+SNOW_USERNAME=admin
+SNOW_PASSWORD=your-password
+
+# OAuth can be left empty
+SNOW_CLIENT_ID=
+SNOW_CLIENT_SECRET=
+```
+
+**Option B: Fix OAuth (For Production)**
+
+If you prefer OAuth, ensure your ServiceNow OAuth app has:
+- ✅ Refresh Token Lifespan set (not "0")
+- ✅ Redirect URI configured
+- ✅ Access Token Lifespan ≥ 1800 seconds
+
+Go to: **System OAuth** → **Application Registry** → Your OAuth App
+
+### Step 2: Fix OpenCode Configuration
+
+Ensure `opencode-config.json` uses `"environment"` (not `"env"`):
+
+```json
+{
+  "mcp": {
+    "servicenow-unified": {
+      "type": "local",
+      "command": ["node", "dist/mcp/servicenow-mcp-unified/index.js"],
+      "environment": {  // ✅ CORRECT (not "env")
+        "SERVICENOW_INSTANCE_URL": "https://dev123456.service-now.com",
+        "SERVICENOW_USERNAME": "admin",
+        "SERVICENOW_PASSWORD": "your-password"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+### Step 3: Test MCP Servers Manually
+
+```bash
+# Start MCP server
+./scripts/mcp-server-manager.sh start
+
+# Check status
+./scripts/mcp-server-manager.sh status
+# Should show: "✓ MCP server is running (PID: ...)"
+# Should show: "✓ Tools loaded: 370+"
+
+# Run health check
+./scripts/mcp-server-manager.sh health
+# Should show: "✓ Health check passed - 370+ tools available"
+```
+
+### Step 4: Launch OpenCode
+
+```bash
+# Option A: Use launcher (recommended)
+./scripts/start-opencode.sh
+
+# Option B: Manual launch
+opencode
+```
+
+---
+
+## 🔍 Diagnostic Commands
+
+### Check if MCP Server is Running
+
+```bash
+./scripts/mcp-server-manager.sh status
+```
+
+**Good Output:**
+```
+✓ MCP server is running (PID: 12345)
+✓ Tools loaded: 370
+```
+
+**Bad Output:**
+```
+✗ MCP server is not running
+```
+
+**Fix:** `./scripts/mcp-server-manager.sh start`
+
+### Check Authentication
+
+```bash
+./scripts/mcp-server-manager.sh logs
+```
+
+**Good Output:**
+```
+[Auth] Using username/password authentication
+[Auth] Username/password authentication successful
+[ToolRegistry] Registered 370 tools
+```
+
+**Bad Output:**
+```
+[Auth] OAuth token refresh failed: No refresh token available
+[Auth] Username/password authentication failed: Invalid credentials
+```
+
+**Fix:**
+- Check .env file has correct credentials
+- For OAuth: Add SNOW_USERNAME + SNOW_PASSWORD as fallback
+- Verify instance URL is correct (should be `dev123456.service-now.com`, NOT `https://...`)
+
+### Test JSON-RPC Communication
+
+```bash
+./scripts/mcp-server-manager.sh health
+```
+
+**Good Output:**
+```
+Testing JSON-RPC communication...
+✓ Health check passed - 370 tools available
+```
+
+**Bad Output:**
+```
+✗ Health check failed - timeout
+```
+
+**Fix:**
+- Check MCP server logs: `./scripts/mcp-server-manager.sh logs`
+- Restart server: `./scripts/mcp-server-manager.sh restart`
+
+---
+
+## Common Error Messages & Fixes
+
+### Error: "Missing required environment variables"
+
+**Cause:** .env file not found or MCP server can't read it
+
+**Fix:**
+```bash
+# Create .env from example
+cp .env.example .env
+
+# Edit with your credentials
+vi .env
+
+# Restart MCP server
+./scripts/mcp-server-manager.sh restart
+```
+
+### Error: "OAuth token refresh failed: No refresh token available"
+
+**Cause:** OAuth configuration doesn't provide refresh tokens
+
+**Fix:** Add username/password to .env (fallback auth method):
+```bash
+SNOW_USERNAME=admin
+SNOW_PASSWORD=your-password
+```
+
+**Why this works:** v8.3.1+ tries OAuth first, then automatically falls back to username/password.
+
+### Error: "Username/password authentication failed: Invalid credentials"
+
+**Cause:** Wrong username or password
+
+**Fix:**
+1. Verify credentials work in ServiceNow web UI
+2. Check for special characters (escape them in .env)
+3. Try different user account
+
+### Error: "Model tried to call unavailable tool '$functions.snow_update_set_manage'"
+
+**Cause:** MCP tools not loaded in OpenCode
+
+**Fix:**
+1. Check `opencode-config.json` uses `"environment"` (not `"env"`)
+2. Verify MCP servers are running: `./scripts/mcp-server-manager.sh status`
+3. Restart OpenCode: `./scripts/start-opencode.sh`
+
+### Error: "Connection timeout" or "ECONNREFUSED"
+
+**Cause:** ServiceNow instance URL wrong or network issue
+
+**Fix:**
+1. Verify SNOW_INSTANCE in .env (should be `dev123456.service-now.com`)
+2. Test connectivity: `ping dev123456.service-now.com`
+3. Check firewall/VPN settings
+
+---
+
+## Authentication Flow (v8.3.1+)
+
+```
+┌─────────────────────────────────────┐
+│  MCP Server Starts                  │
+└─────────┬───────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────┐
+│  Try OAuth Authentication           │
+│  (if CLIENT_ID + CLIENT_SECRET)     │
+└─────────┬───────────────────────────┘
+          │
+          ├─ Success ──► Use OAuth tokens
+          │
+          ├─ No refresh token ─────┐
+          │                        │
+          ▼                        ▼
+┌─────────────────────────────────────┐
+│  Fallback to Username/Password      │
+│  (if USERNAME + PASSWORD)           │
+└─────────┬───────────────────────────┘
+          │
+          ├─ Success ──► Use Basic Auth
+          │
+          ├─ Fail ─────► Error (no auth method works)
+          │
+          ▼
+     Tools Available!
+```
+
+---
+
+## MCP Server Manager Commands
+
+```bash
+# Start MCP server in background
+./scripts/mcp-server-manager.sh start
+
+# Stop MCP server
+./scripts/mcp-server-manager.sh stop
+
+# Restart MCP server
+./scripts/mcp-server-manager.sh restart
+
+# Check status
+./scripts/mcp-server-manager.sh status
+
+# Run health check (tests JSON-RPC communication)
+./scripts/mcp-server-manager.sh health
+
+# Follow logs (Ctrl+C to exit)
+./scripts/mcp-server-manager.sh logs
+
+# Show help
+./scripts/mcp-server-manager.sh help
+```
+
+---
+
+## OpenCode Launcher Benefits
+
+Using `./scripts/start-opencode.sh` instead of direct `opencode`:
+
+- ✅ Validates .env file exists
+- ✅ Builds Snow-Flow if dist/ missing
+- ✅ Auto-starts MCP servers
+- ✅ Runs pre-flight health checks
+- ✅ Creates opencode-config.json if missing
+- ✅ Replaces ${VARIABLES} with actual values
+- ✅ Shows clear error messages with solutions
+
+---
+
+## Still Having Issues?
+
+### 1. Check All Logs
+
+```bash
+# MCP server logs
+./scripts/mcp-server-manager.sh logs
+
+# OpenCode logs (if available)
+cat ~/.opencode/logs/latest.log
+```
+
+### 2. Test Individual Components
+
+```bash
+# Test MCP server binary exists
+ls -la dist/mcp/servicenow-mcp-unified/index.js
+
+# Test environment variables
+source .env && echo $SNOW_INSTANCE
+
+# Test ServiceNow connectivity
+curl -u "$SNOW_USERNAME:$SNOW_PASSWORD" \
+  "https://$SNOW_INSTANCE/api/now/table/sys_user?sysparm_limit=1"
+```
+
+### 3. Clean Restart
+
+```bash
+# Stop everything
+./scripts/mcp-server-manager.sh stop
+
+# Rebuild
+npm run build
+
+# Start fresh
+./scripts/start-opencode.sh
+```
+
+### 4. Report Issue
+
+If none of the above works, create a GitHub issue with:
+
+- Snow-Flow version: `npm list -g snow-flow`
+- Node.js version: `node -v`
+- OpenCode version: `opencode --version`
+- Output of: `./scripts/mcp-server-manager.sh health`
+- Relevant logs (without passwords!)
+
+---
+
+## Version Information
+
+- **v8.3.0 and earlier**: Only OAuth supported, config used `"env"`
+- **v8.3.1+**: OAuth + Username/Password fallback, config uses `"environment"`
+
+**Upgrade command:**
+```bash
+npm install -g snow-flow@latest
+```
+
+---
+
+**Last Updated:** 2025-10-22 (v8.3.1)

package/dist/agents/index.d.ts

@@ -2,6 +2,6 @@
  * ServiceNow Agent System - Claude Agent SDK Integration v4.7.0
  * DEPRECATED: Custom agents replaced by @anthropic-ai/claude-agent-sdk@0.1.1
  */
-export { ClaudeAgentSDKIntegration, QueenOrchestrator } from '../sdk/index.js';
-export type { SnowFlowAgentConfig, AgentExecutionResult, QueenObjective, OrchestrationResult } from '../sdk/index.js';
+export { ClaudeAgentSDKIntegration } from '../sdk/index.js';
+export type { SnowFlowAgentConfig, AgentExecutionResult, AgentType } from '../sdk/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}