snow-flow 10.0.201 → 10.0.202

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "10.0.201",
+  "version": "10.0.202",
   "name": "snow-flow",
   "description": "Snow-Flow - ServiceNow Multi-Agent Development Framework powered by AI",
   "license": "Elastic-2.0",

package/src/servicenow/servicenow-mcp-unified/shared/auth.ts

@@ -123,7 +123,12 @@ export class ServiceNowAuthManager {
     const accessToken = await this.getAccessToken(context)
 
     if (!accessToken) {
-      throw new Error("Failed to obtain access token. Please verify ServiceNow credentials and run: snow-flow auth login")
+      throw new Error(
+        "Failed to obtain access token. This can happen when:\n" +
+        "• Your ServiceNow instance is hibernating — open it in a browser to wake it up\n" +
+        "• Your credentials have expired — run: snow-flow auth login\n" +
+        "• Your OAuth client ID/secret are incorrect"
+      )
     }
 
     // Determine correct Authorization header format
@@ -171,6 +176,19 @@ export class ServiceNowAuthManager {
         return response
       },
       async (error) => {
+        const status = error.response?.status
+
+        // Detect hibernating instance (502/503 from proxy or ServiceNow itself)
+        if (status === 502 || status === 503) {
+          const err = new Error(
+            `ServiceNow instance is hibernating or starting up (HTTP ${status}). ` +
+            `Open ${context.instanceUrl} in your browser to wake it up, then wait 1-2 minutes and try again.`
+          )
+          ;(err as any).response = error.response
+          ;(err as any).isHibernating = true
+          throw err
+        }
+
         // Check if the error response has ServiceNow error structure
         if (error.response?.data?.error) {
           const snowError = error.response.data.error

package/src/servicenow/servicenow-mcp-unified/tools/connectors/snow_check_health.ts

@@ -39,6 +39,37 @@ export async function execute(args: any, context: ServiceNowContext): Promise<To
       status: responseTime < 1000 ? "good" : responseTime < 3000 ? "fair" : "slow",
     })
   } catch (error: any) {
+    const msg = error.message || ""
+    const status = error.response?.status
+
+    // Detect hibernating instance
+    if (
+      status === 502 || status === 503
+      || msg.includes("ECONNREFUSED")
+      || msg.includes("ETIMEDOUT")
+      || msg.includes("socket hang up")
+      || (msg.includes("Failed to obtain access token") && !msg.includes("Invalid credentials"))
+    ) {
+      return createErrorResult(
+        `ServiceNow instance appears to be hibernating or starting up.\n\n` +
+        `Developer instances automatically hibernate after periods of inactivity. ` +
+        `To wake it up:\n` +
+        `1. Open your instance URL in a browser: ${context.instanceUrl}\n` +
+        `2. Wait 1-2 minutes for it to fully start\n` +
+        `3. Try this command again\n\n` +
+        `Technical detail: ${status ? `HTTP ${status}` : msg}`
+      )
+    }
+
+    // Detect auth issues separately
+    if (msg.includes("Failed to obtain access token") || status === 401) {
+      return createErrorResult(
+        `Authentication failed. Your access token may be expired.\n\n` +
+        `Run: snow-flow auth login\n\n` +
+        `If you've already logged in, check: snow-flow auth status`
+      )
+    }
+
     return createErrorResult(error.message)
   }
 }