@the-open-engine/zeroshot 6.38.1 → 6.39.0

package/src/agent/agent-stuck-detector.js

@@ -1,256 +1,188 @@
-/**
- * AgentStuckDetector - Multi-indicator process health analysis
- *
- * Detects stuck Claude processes using multiple indicators:
- * - Process state (S=sleeping vs R=running)
- * - Wait channel (ep_poll = blocked on epoll_wait)
- * - CPU usage over sample period
- * - Context switches (activity indicator)
- * - Network socket state (data in flight)
- *
- * CRITICAL: Single-indicator detection (just output freshness) has HIGH false positive risk.
- * Multi-indicator approach ONLY flags processes that fail ALL indicators.
- *
- * Scoring system:
- * - isSleeping: +1
- * - isBlockedOnPoll: +1
- * - lowCpuUsage: +1
- * - lowCtxSwitches: +1
- * - noDataInFlight: +0.5 (secondary signal)
- * - hasSynSent: +1 (stuck trying to connect)
- * - hasDataInFlight: -2 (active I/O = working)
- *
- * Threshold: stuckScore >= 3.5 = likely stuck
- */
-
-const { execSync } = require('../lib/safe-exec'); // Enforces timeouts
-const fs = require('fs');
-
-// Stuck detection thresholds
-const STUCK_THRESHOLD = 3.5; // Score at which we consider process stuck
+"use strict";
+const fs = require("fs");
+function isSafeExecModule(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'execSync' in value &&
+        typeof value.execSync === 'function');
+}
+function errorMessage(error) {
+    if (typeof error === 'object' && error !== null && 'message' in error) {
+        return error.message;
+    }
+    return undefined;
+}
+function parseProcInteger(value) {
+    return value === undefined ? Number.NaN : parseInt(value, 10);
+}
+function hasSocketFields(fields) {
+    return fields?.length === 5;
+}
+const STUCK_THRESHOLD = 3.5;
 const HIGH_CONFIDENCE_THRESHOLD = 4.5;
-const CPU_LOW_THRESHOLD = 1; // Percent - below this is considered "low"
-const CTX_SWITCHES_LOW_THRESHOLD = 10; // Below this is considered "inactive"
-
-/**
- * Get process state from /proc filesystem
- * @param {number} pid - Process ID
- * @returns {object} Process state info
- */
+const CPU_LOW_THRESHOLD = 1;
+const CTX_SWITCHES_LOW_THRESHOLD = 10;
+function stuckScoreFor(indicators, hasDataInFlight) {
+    const score = Number(indicators.isSleeping) +
+        Number(indicators.isBlockedOnPoll) +
+        Number(indicators.lowCpuUsage) +
+        Number(indicators.lowCtxSwitches) +
+        Number(indicators.noDataInFlight) * 0.5 +
+        Number(Boolean(indicators.hasSynSent));
+    return hasDataInFlight ? Math.max(0, score - 2) : score;
+}
+function confidenceFor(stuckScore) {
+    if (stuckScore >= HIGH_CONFIDENCE_THRESHOLD)
+        return 'high';
+    if (stuckScore >= STUCK_THRESHOLD)
+        return 'medium';
+    return 'low';
+}
+const rawSafeExec = require('../lib/safe-exec');
+if (!isSafeExecModule(rawSafeExec)) {
+    throw new TypeError('safe-exec must export execSync');
+}
+const { execSync } = rawSafeExec;
 function getProcessState(pid) {
-  try {
-    const statPath = `/proc/${pid}/stat`;
-    if (!fs.existsSync(statPath)) {
-      return { exists: false };
-    }
-
-    const stat = fs.readFileSync(statPath, 'utf8');
-    const parts = stat.split(' ');
-
-    // stat fields: pid, comm, state, ppid, pgrp, ...
-    // State is the 3rd field (index 2): R=running, S=sleeping, D=disk sleep, Z=zombie
-    const state = parts[2];
-
-    // Get wchan (what the process is waiting on)
-    let wchan = '';
     try {
-      wchan = fs.readFileSync(`/proc/${pid}/wchan`, 'utf8').trim();
-    } catch {
-      // wchan may not be readable
+        const statPath = `/proc/${pid}/stat`;
+        if (!fs.existsSync(statPath)) {
+            return { exists: false };
+        }
+        const stat = fs.readFileSync(statPath, 'utf8');
+        const parts = stat.split(' ');
+        const state = parts[2];
+        let wchan = '';
+        try {
+            wchan = fs.readFileSync(`/proc/${pid}/wchan`, 'utf8').trim();
+        }
+        catch {
+            // wchan may not be readable.
+        }
+        const utime = parseProcInteger(parts[13]);
+        const stime = parseProcInteger(parts[14]);
+        const status = fs.readFileSync(`/proc/${pid}/status`, 'utf8');
+        const threads = /Threads:\s+(\d+)/.exec(status)?.[1] || '1';
+        const volCtxSwitches = /voluntary_ctxt_switches:\s+(\d+)/.exec(status)?.[1] || '0';
+        return {
+            exists: true,
+            state,
+            wchan,
+            cpuTicks: utime + stime,
+            threads: parseInt(threads, 10),
+            volCtxSwitches: parseInt(volCtxSwitches, 10),
+        };
+    }
+    catch (error) {
+        return { exists: false, error: errorMessage(error) };
     }
-
-    // Get CPU usage from stat
-    // utime (field 14) + stime (field 15) = total CPU ticks
-    const utime = parseInt(parts[13], 10);
-    const stime = parseInt(parts[14], 10);
-
-    // Get status for more info
-    const status = fs.readFileSync(`/proc/${pid}/status`, 'utf8');
-    const threads = status.match(/Threads:\s+(\d+)/)?.[1] || '1';
-    const volCtxSwitches = status.match(/voluntary_ctxt_switches:\s+(\d+)/)?.[1] || '0';
-
-    return {
-      exists: true,
-      state,
-      wchan,
-      cpuTicks: utime + stime,
-      threads: parseInt(threads, 10),
-      volCtxSwitches: parseInt(volCtxSwitches, 10),
-    };
-  } catch (err) {
-    return { exists: false, error: err.message };
-  }
 }
-
-/**
- * Get network socket activity for a process
- * @param {number} pid - Process ID
- * @returns {object} Network state info
- */
 function getNetworkState(pid) {
-  try {
-    const fdPath = `/proc/${pid}/fd`;
-    if (!fs.existsSync(fdPath)) {
-      return { hasNetwork: false };
-    }
-
-    // Use ss to get socket states for this process
-    let ssOutput = '';
     try {
-      ssOutput = execSync(`ss -tunp 2>/dev/null | grep ",pid=${pid}," || true`, {
-        encoding: 'utf8',
-        timeout: 5000,
-      });
-    } catch {
-      return { hasNetwork: false };
+        const fdPath = `/proc/${pid}/fd`;
+        if (!fs.existsSync(fdPath)) {
+            return { hasNetwork: false };
+        }
+        let ssOutput = '';
+        try {
+            ssOutput = execSync(`ss -tunp 2>/dev/null | grep ",pid=${pid}," || true`, {
+                encoding: 'utf8',
+                timeout: 5000,
+            });
+        }
+        catch {
+            return { hasNetwork: false };
+        }
+        if (!ssOutput.trim()) {
+            return { hasNetwork: false, connections: [] };
+        }
+        const connections = [];
+        for (const line of ssOutput.trim().split('\n')) {
+            const match = /^(\S+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)/.exec(line);
+            const fields = match?.slice(1, 6);
+            if (!hasSocketFields(fields))
+                continue;
+            const [state, recvQ, sendQ, local, peer] = fields;
+            connections.push({
+                state,
+                recvQ: parseInt(recvQ, 10),
+                sendQ: parseInt(sendQ, 10),
+                local,
+                peer,
+            });
+        }
+        return {
+            hasNetwork: connections.length > 0,
+            connections,
+            establishedCount: connections.filter((connection) => connection.state === 'ESTAB').length,
+            hasDataInFlight: connections.some((connection) => connection.recvQ > 0 || connection.sendQ > 0),
+            hasSynSent: connections.some((connection) => connection.state === 'SYN-SENT'),
+        };
     }
-
-    if (!ssOutput.trim()) {
-      return { hasNetwork: false, connections: [] };
+    catch (error) {
+        return { hasNetwork: false, error: errorMessage(error) };
     }
-
-    const connections = [];
-    const lines = ssOutput.trim().split('\n');
-
-    for (const line of lines) {
-      // Parse ss output: State  Recv-Q  Send-Q  Local Address:Port  Peer Address:Port  Process
-      const match = line.match(/^(\S+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)/);
-      if (match) {
-        connections.push({
-          state: match[1],
-          recvQ: parseInt(match[2], 10),
-          sendQ: parseInt(match[3], 10),
-          local: match[4],
-          peer: match[5],
-        });
-      }
+}
+async function analyzeProcessHealth(pid, samplePeriodMs = 5000) {
+    const t0 = getProcessState(pid);
+    if (!t0.exists) {
+        return { isLikelyStuck: null, reason: 'Process does not exist', pid };
     }
-
-    // Analyze connection health
-    const establishedCount = connections.filter((c) => c.state === 'ESTAB').length;
-    const hasDataInFlight = connections.some((c) => c.recvQ > 0 || c.sendQ > 0);
-    const hasSynSent = connections.some((c) => c.state === 'SYN-SENT');
-
+    await new Promise((resolve) => setTimeout(resolve, samplePeriodMs));
+    const t1 = getProcessState(pid);
+    if (!t1.exists) {
+        return { isLikelyStuck: null, reason: 'Process died during analysis', pid };
+    }
+    const cpuTicksDelta = t1.cpuTicks - t0.cpuTicks;
+    const ctxSwitchesDelta = t1.volCtxSwitches - t0.volCtxSwitches;
+    const cpuSeconds = cpuTicksDelta / 100;
+    const sampleSeconds = samplePeriodMs / 1000;
+    const cpuPercent = (cpuSeconds / sampleSeconds) * 100;
+    const network = getNetworkState(pid);
+    const indicators = {
+        isSleeping: t1.state === 'S',
+        isBlockedOnPoll: t1.wchan.includes('poll') || t1.wchan.includes('wait'),
+        lowCpuUsage: cpuPercent < CPU_LOW_THRESHOLD,
+        lowCtxSwitches: ctxSwitchesDelta < CTX_SWITCHES_LOW_THRESHOLD,
+        noDataInFlight: network.hasNetwork && !network.hasDataInFlight,
+        hasSynSent: network.hasSynSent,
+    };
+    const stuckScore = stuckScoreFor(indicators, network.hasDataInFlight);
+    const isLikelyStuck = stuckScore >= STUCK_THRESHOLD;
+    const confidence = confidenceFor(stuckScore);
     return {
-      hasNetwork: connections.length > 0,
-      connections,
-      establishedCount,
-      hasDataInFlight,
-      hasSynSent,
+        pid,
+        state: t1.state,
+        wchan: t1.wchan,
+        cpuPercent: parseFloat(cpuPercent.toFixed(2)),
+        ctxSwitchesDelta,
+        threads: t1.threads,
+        network: {
+            hasConnections: network.hasNetwork,
+            establishedCount: network.establishedCount || 0,
+            hasDataInFlight: network.hasDataInFlight || false,
+            hasSynSent: network.hasSynSent || false,
+        },
+        indicators,
+        stuckScore: parseFloat(stuckScore.toFixed(1)),
+        isLikelyStuck,
+        confidence,
+        analysis: isLikelyStuck
+            ? `Process appears STUCK: sleeping on ${t1.wchan}, ${cpuPercent.toFixed(1)}% CPU, ` +
+                `${ctxSwitchesDelta} ctx switches`
+            : `Process appears WORKING: ${cpuPercent.toFixed(1)}% CPU, ${ctxSwitchesDelta} ctx switches, state=${t1.state}`,
     };
-  } catch (err) {
-    return { hasNetwork: false, error: err.message };
-  }
-}
-
-/**
- * Analyze process health using multi-indicator approach
- *
- * @param {number} pid - Process ID
- * @param {number} samplePeriodMs - How long to sample (default 5000ms)
- * @returns {Promise<object>} Analysis result with isLikelyStuck, stuckScore, indicators
- */
-async function analyzeProcessHealth(pid, samplePeriodMs = 5000) {
-  const t0 = getProcessState(pid);
-  if (!t0.exists) {
-    return { isLikelyStuck: null, reason: 'Process does not exist', pid };
-  }
-
-  // Wait and sample again
-  await new Promise((r) => setTimeout(r, samplePeriodMs));
-
-  const t1 = getProcessState(pid);
-  if (!t1.exists) {
-    return { isLikelyStuck: null, reason: 'Process died during analysis', pid };
-  }
-
-  // Calculate CPU usage during sample period
-  const cpuTicksDelta = t1.cpuTicks - t0.cpuTicks;
-  const ctxSwitchesDelta = t1.volCtxSwitches - t0.volCtxSwitches;
-
-  // Get clock ticks per second (typically 100 on Linux)
-  const clockTicks = 100;
-
-  // CPU seconds used during sample
-  const cpuSeconds = cpuTicksDelta / clockTicks;
-  const sampleSeconds = samplePeriodMs / 1000;
-  const cpuPercent = (cpuSeconds / sampleSeconds) * 100;
-
-  // Get network state
-  const network = getNetworkState(pid);
-
-  // Analyze stuck indicators
-  const indicators = {
-    isSleeping: t1.state === 'S',
-    isBlockedOnPoll: t1.wchan.includes('poll') || t1.wchan.includes('wait'),
-    lowCpuUsage: cpuPercent < CPU_LOW_THRESHOLD,
-    lowCtxSwitches: ctxSwitchesDelta < CTX_SWITCHES_LOW_THRESHOLD,
-    // Network indicators (only apply if process has network connections)
-    noDataInFlight: network.hasNetwork && !network.hasDataInFlight,
-    hasSynSent: network.hasSynSent, // Stuck trying to connect
-  };
-
-  // Calculate stuck score using weighted indicators
-  let stuckScore = 0;
-  if (indicators.isSleeping) stuckScore += 1;
-  if (indicators.isBlockedOnPoll) stuckScore += 1;
-  if (indicators.lowCpuUsage) stuckScore += 1;
-  if (indicators.lowCtxSwitches) stuckScore += 1;
-  if (indicators.noDataInFlight) stuckScore += 0.5; // Secondary signal
-  if (indicators.hasSynSent) stuckScore += 1; // Strong signal - stuck connecting
-
-  // CRITICAL: If data IS flowing, REDUCE stuck score (legitimate work)
-  if (network.hasDataInFlight) {
-    stuckScore = Math.max(0, stuckScore - 2); // Active I/O = likely working
-  }
-
-  const isLikelyStuck = stuckScore >= STUCK_THRESHOLD;
-  let confidence = 'low';
-  if (stuckScore >= HIGH_CONFIDENCE_THRESHOLD) {
-    confidence = 'high';
-  } else if (stuckScore >= STUCK_THRESHOLD) {
-    confidence = 'medium';
-  }
-
-  return {
-    pid,
-    state: t1.state,
-    wchan: t1.wchan,
-    cpuPercent: parseFloat(cpuPercent.toFixed(2)),
-    ctxSwitchesDelta,
-    threads: t1.threads,
-    network: {
-      hasConnections: network.hasNetwork,
-      establishedCount: network.establishedCount || 0,
-      hasDataInFlight: network.hasDataInFlight || false,
-      hasSynSent: network.hasSynSent || false,
-    },
-    indicators,
-    stuckScore: parseFloat(stuckScore.toFixed(1)),
-    isLikelyStuck,
-    confidence,
-    analysis: isLikelyStuck
-      ? `Process appears STUCK: sleeping on ${t1.wchan}, ${cpuPercent.toFixed(1)}% CPU, ${ctxSwitchesDelta} ctx switches`
-      : `Process appears WORKING: ${cpuPercent.toFixed(1)}% CPU, ${ctxSwitchesDelta} ctx switches, state=${t1.state}`,
-  };
 }
-
-/**
- * Check if we're on a platform that supports /proc filesystem
- * @returns {boolean}
- */
 function isPlatformSupported() {
-  return process.platform === 'linux' && fs.existsSync('/proc');
+    return process.platform === 'linux' && fs.existsSync('/proc');
 }
-
 module.exports = {
-  analyzeProcessHealth,
-  getProcessState,
-  getNetworkState,
-  isPlatformSupported,
-  // Export thresholds for testing
-  STUCK_THRESHOLD,
-  HIGH_CONFIDENCE_THRESHOLD,
-  CPU_LOW_THRESHOLD,
-  CTX_SWITCHES_LOW_THRESHOLD,
+    analyzeProcessHealth,
+    getProcessState,
+    getNetworkState,
+    isPlatformSupported,
+    STUCK_THRESHOLD,
+    HIGH_CONFIDENCE_THRESHOLD,
+    CPU_LOW_THRESHOLD,
+    CTX_SWITCHES_LOW_THRESHOLD,
 };