runtime-inspector 0.1.0

package/src/agent/index.js

@@ -0,0 +1,233 @@
+// RuntimeInspector Agent — main entry point
+// Scans processes, groups into sessions, serves API + embedded dashboard
+
+import express from 'express';
+import { scanProcesses, evictStaleCwdEntries } from './scanner.js';
+import { groupIntoSessions } from './grouper.js';
+import { addExplanations } from './explainer.js';
+import { addPurpose } from './purposer.js';
+import { addStateInference } from './stateInfer.js';
+import { mergeRepoActivity } from './repoActivity.js';
+import { addProgressInference } from './progressInfer.js';
+import { registerActions } from './actions.js';
+import { registerShellEventRoutes, evictStaleShellEvents } from './shellEvents.js';
+import { mergeShellContext } from './shellMerge.js';
+import { addAttentionInference, computeSafeToLeave } from './attentionInfer.js';
+import { isTmuxAvailable, listPanes, samplePaneActivity, recheckTmux, registerTmuxRoutes } from './tmux.js';
+import { mergeTmuxContext } from './tmuxMerge.js';
+import { dashboardHTML } from './dashboard.js';
+
+const PORT = parseInt(process.env.PORT || '7331', 10);
+const SCAN_INTERVAL = 120_000; // 2 minutes
+const WRAPPER_TTL = 5 * 60 * 1000; // 5 minutes after exit
+
+let currentSessions = [];
+let lastScanTime = null;
+
+// Wrapped session store: pid -> wrapper report data
+const wrappedSessions = new Map();
+
+function mergeWrappedData(sessions) {
+  for (const session of sessions) {
+    // Check if any PID in this session matches a wrapped session
+    for (const proc of session.processes) {
+      const wrapped = wrappedSessions.get(proc.pid);
+      if (wrapped) {
+        session.isWrapped = true;
+        session.runtimeState = wrapped.state;
+        session.lastActivityAt = wrapped.lastOutputAt;
+        session.recentOutput = wrapped.recentOutput;
+        session.wrappedCmd = wrapped.cmd;
+        session.wrappedStartedAt = wrapped.startedAt;
+        session.wrappedLineCount = wrapped.lineCount;
+        session.eta = null; // will be set by stateInfer
+        break;
+      }
+    }
+  }
+}
+
+function cleanExpiredWrapped() {
+  const now = Date.now();
+  for (const [pid, data] of wrappedSessions) {
+    if (data.exitCode !== null && data.exitCode !== undefined) {
+      const reportAge = now - (data._receivedAt || 0);
+      if (reportAge > WRAPPER_TTL) {
+        wrappedSessions.delete(pid);
+      }
+    }
+  }
+}
+
+// ------------------------------------------------------------------
+// Scan pipeline — order matters!
+//
+// The pipeline is split into named stages with documented dependencies.
+// Each stage mutates `sessions` in place. Reordering stages will break
+// downstream consumers that depend on fields populated by earlier stages.
+//
+// Stage               | Depends on              | Populates
+// ------------------- | ----------------------- | -------------------------
+// 1. scan             | —                       | raw process list
+// 2. group            | scan                    | sessions[] with pids, cpu, mem, cwd
+// 3. explain          | group                   | session.explanation
+// 4. purpose          | group                   | session.purpose
+// 5. repoActivity     | group (cwd)             | session.repoActivity
+// 6. shellContext      | group (cwd, pids)       | session.shellEvents
+// 7. tmux             | group (cwd, pids)       | session.tmux
+// 8. wrappedData      | group (pids)            | session.isWrapped, runtimeState, etc.
+// 9. progress         | repoActivity, wrapped   | session.progress
+// 10. state           | progress                | session.inferredState
+// 11. attention       | state, tmux             | session.attention, severity
+// ------------------------------------------------------------------
+async function scan() {
+  try {
+    // Stage 1–2: Collect and group processes
+    const processes = await scanProcesses();
+    const sessions = await groupIntoSessions(processes);
+
+    // Stage 3–4: Static enrichment (no cross-stage deps)
+    addExplanations(sessions);
+    addPurpose(sessions);
+
+    // Stage 5–7: Data-source merges (order among these is independent)
+    await mergeRepoActivity(sessions);
+    mergeShellContext(sessions);
+
+    // tmux two-pass: list panes -> merge metadata -> sample activity -> merge output timestamps
+    const panes = await listPanes();
+    if (panes.length > 0) {
+      mergeTmuxContext(sessions, panes, null);
+      const mappedPaneIds = sessions.filter(s => s.tmux).map(s => s.tmux.paneId);
+      if (mappedPaneIds.length > 0) {
+        const activity = await samplePaneActivity(mappedPaneIds);
+        mergeTmuxContext(sessions, panes, activity);
+      }
+    }
+
+    // Stage 8: Merge wrapper data (before inference stages)
+    mergeWrappedData(sessions);
+
+    // Stage 9–11: Inference chain — MUST run in this order
+    addProgressInference(sessions);   // reads repoActivity, wrapped
+    addStateInference(sessions);      // reads progress
+    addAttentionInference(sessions);  // reads state, tmux
+
+    // Final sort: ai-agents first, then dev-servers, then scripts
+    const typeOrder = { 'ai-agent': 0, 'dev-server': 1, 'script': 2, 'unknown': 3 };
+    sessions.sort((a, b) => {
+      const typeDiff = (typeOrder[a.type] ?? 3) - (typeOrder[b.type] ?? 3);
+      if (typeDiff !== 0) return typeDiff;
+      return b.cpu - a.cpu;
+    });
+
+    currentSessions = sessions;
+    lastScanTime = new Date().toISOString();
+
+    // Housekeeping: evict dead PIDs from cwd cache + stale shell events + expired wrappers
+    const livePids = new Set(processes.map(p => p.pid));
+    evictStaleCwdEntries(livePids);
+    evictStaleShellEvents();
+    cleanExpiredWrapped();
+  } catch (err) {
+    console.error('[agent] Scan error:', err.message);
+  }
+}
+
+export async function startServer({ open: shouldOpen = false } = {}) {
+  await scan();
+  const scanTimer = setInterval(() => scan().catch(err => console.error('[agent] Scan error:', err.message)), SCAN_INTERVAL);
+
+  const app = express();
+  app.use(express.json());
+
+  app.get('/api/sessions', (req, res) => {
+    const safetySummary = computeSafeToLeave(currentSessions);
+    res.json({
+      sessions: currentSessions,
+      scannedAt: lastScanTime,
+      processCount: currentSessions.reduce((sum, s) => sum + s.processes.length, 0),
+      hasWrapped: currentSessions.some(s => s.isWrapped),
+      ...safetySummary,
+    });
+  });
+
+  // Wrapper report endpoint — receives output + state from wrapper runner
+  app.post('/api/wrapper/report', (req, res) => {
+    const { pid, cmd, state, recentOutput, lastOutputAt, startedAt, exitCode, lineCount } = req.body;
+    if (!pid) {
+      return res.status(400).json({ error: 'pid required' });
+    }
+
+    wrappedSessions.set(pid, {
+      pid,
+      cmd,
+      state,
+      recentOutput: recentOutput || [],
+      lastOutputAt,
+      startedAt,
+      exitCode,
+      lineCount: lineCount || 0,
+      _receivedAt: Date.now(),
+    });
+
+    // Re-merge wrapped data into current sessions without full rescan
+    mergeWrappedData(currentSessions);
+    addStateInference(currentSessions);
+
+    res.json({ ok: true });
+  });
+
+  app.get('/api/health', (req, res) => {
+    res.json({ status: 'ok', uptime: process.uptime() });
+  });
+
+  // Shell event bus (command start/end from shell hooks)
+  registerShellEventRoutes(app);
+
+  // tmux pane debug endpoint
+  registerTmuxRoutes(app);
+
+  // Context actions (open terminal, open folder, copy command)
+  registerActions(app, (sessionId) => currentSessions.find(s => s.id === sessionId));
+
+  app.get('/', (req, res) => {
+    res.type('html').send(dashboardHTML());
+  });
+
+  // Re-check tmux availability every 2 minutes (user may start/stop tmux)
+  setInterval(recheckTmux, SCAN_INTERVAL);
+
+  // Log tmux status at startup
+  if (isTmuxAvailable()) {
+    const panes = await listPanes();
+    console.log(`  [tmux] Detected ${panes.length} pane(s)`);
+  }
+
+  app.listen(PORT, '0.0.0.0', () => {
+    console.log('');
+    console.log('  ╔══════════════════════════════════════════╗');
+    console.log('  ║         RuntimeInspector v0.1.0          ║');
+    console.log('  ╠══════════════════════════════════════════╣');
+    console.log(`  ║  Dashboard:  http://localhost:${PORT}       ║`);
+    console.log(`  ║  API:        http://localhost:${PORT}/api   ║`);
+    console.log('  ║  Scanning:   every 2 min                  ║');
+    console.log('  ╚══════════════════════════════════════════╝');
+    console.log('');
+
+    if (shouldOpen) {
+      import('open').then(({ default: open }) => {
+        open(`http://localhost:${PORT}`);
+      }).catch(() => {});
+    }
+  });
+
+  const shutdown = () => {
+    console.log('\n[agent] Shutting down...');
+    clearInterval(scanTimer);
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}

package/src/agent/progressInfer.js

@@ -0,0 +1,46 @@
+// Progress inference — uses repo file activity to refine session runtime state.
+// Runs after mergeRepoActivity() and before addStateInference().
+// Does NOT override wrapped session states.
+
+/**
+ * Add progress inference to sessions based on repoActivity.
+ * Mutates in place.
+ */
+export function addProgressInference(sessions) {
+  for (const session of sessions) {
+    // Skip sessions without repo activity data
+    if (!session.repoActivity) continue;
+
+    // Never override wrapped session states — the wrapper has better signal
+    if (session.isWrapped && session.runtimeState) continue;
+
+    const { filesChangedLast2m, lastFileWriteAt } = session.repoActivity;
+    const cpu = session.cpu || 0;
+    const elapsed = session.durationSeconds || 0;
+
+    if (filesChangedLast2m > 0) {
+      // Files are being written — session is making progress
+      if (!session.status.includes('file-progress')) {
+        session.status.push('file-progress');
+      }
+      session.runtimeState = 'progressing';
+    } else if (cpu > 5 && elapsed > 600) {
+      // No file writes but CPU active for 10+ minutes — possibly stuck
+      if (!session.status.includes('no-file-progress')) {
+        session.status.push('no-file-progress');
+      }
+      session.runtimeState = 'possibly-stuck';
+    } else if (cpu < 1 && elapsed > 300) {
+      // No file writes, low CPU, running 5+ minutes — idle
+      session.runtimeState = 'idle';
+    }
+    // Else: leave existing state untouched
+
+    // Set lastProgressAt from repo activity
+    if (lastFileWriteAt) {
+      session.lastProgressAt = lastFileWriteAt;
+    }
+  }
+
+  return sessions;
+}

package/src/agent/purposer.js

@@ -0,0 +1,253 @@
+// Purpose engine — infers *what* a session is doing, not just what it is.
+// Uses deterministic heuristics on command args, cwd, and child process signatures.
+
+// --- Activity classification ---
+// Each rule returns { activity, purpose } or null.
+// First match wins. Order matters: most specific first.
+
+const ACTIVITY_RULES = [
+
+  // Scaffolding tools (detected in any child process args)
+  {
+    // shadcn CLI generating UI components
+    test: (s) => anyProcessMatches(s, /shadcn/),
+    activity: 'scaffolding',
+    purpose: (s) => `Generating UI components with shadcn${inRepo(s)}`,
+  },
+  {
+    // create-react-app, create-next-app, etc.
+    test: (s) => anyProcessMatches(s, /create-(react|next|vite|svelte|vue)-app/),
+    activity: 'scaffolding',
+    purpose: (s) => `Scaffolding a new project${inRepo(s)}`,
+  },
+  {
+    // npm init / npx create
+    test: (s) => anyProcessMatches(s, /npm init|npx create/),
+    activity: 'scaffolding',
+    purpose: (s) => `Initializing a new project${inRepo(s)}`,
+  },
+  {
+    // prisma generate / migrate
+    test: (s) => anyProcessMatches(s, /prisma\s+(generate|migrate|db\s+push)/),
+    activity: 'scaffolding',
+    purpose: (s) => `Running Prisma database operations${inRepo(s)}`,
+  },
+
+  // Dev servers (the session itself is a server)
+  {
+    test: (s) => s.detectedAs === 'nextjs',
+    activity: 'serving',
+    purpose: (s) => `Serving a Next.js app with hot reload${inRepo(s)}`,
+  },
+  {
+    test: (s) => s.detectedAs === 'vite',
+    activity: 'serving',
+    purpose: (s) => `Serving a Vite project with HMR${inRepo(s)}`,
+  },
+  {
+    test: (s) => s.detectedAs === 'react-scripts',
+    activity: 'serving',
+    purpose: (s) => `Serving a React app in development${inRepo(s)}`,
+  },
+  {
+    test: (s) => s.detectedAs === 'webpack-dev',
+    activity: 'serving',
+    purpose: (s) => `Serving via Webpack dev server${inRepo(s)}`,
+  },
+  {
+    test: (s) => s.detectedAs === 'fastapi',
+    activity: 'serving',
+    purpose: (s) => `Running a FastAPI backend${inRepo(s)}`,
+  },
+  {
+    test: (s) => s.detectedAs === 'flask',
+    activity: 'serving',
+    purpose: (s) => `Running a Flask backend${inRepo(s)}`,
+  },
+  {
+    test: (s) => s.detectedAs === 'django',
+    activity: 'serving',
+    purpose: (s) => `Running a Django development server${inRepo(s)}`,
+  },
+  {
+    test: (s) => s.detectedAs === 'docker-compose',
+    activity: 'serving',
+    purpose: (s) => `Running a Docker Compose stack${inRepo(s)}`,
+  },
+
+  // File watchers / compilers
+  {
+    // tsc --watch
+    test: (s) => s.detectedAs === 'tsc' || anyProcessMatches(s, /tsc.*--watch/),
+    activity: 'watching',
+    purpose: (s) => `Watching TypeScript files and recompiling on change${inRepo(s)}`,
+  },
+  {
+    // nodemon / tsx watch
+    test: (s) => anyProcessMatches(s, /nodemon|tsx\s+watch/),
+    activity: 'watching',
+    purpose: (s) => `Watching files and restarting on change${inRepo(s)}`,
+  },
+  {
+    // jest --watch / vitest
+    test: (s) => anyProcessMatches(s, /jest.*--watch|vitest/),
+    activity: 'watching',
+    purpose: (s) => `Running tests in watch mode${inRepo(s)}`,
+  },
+  {
+    // tailwind --watch
+    test: (s) => anyProcessMatches(s, /tailwind.*--watch/),
+    activity: 'watching',
+    purpose: (s) => `Compiling Tailwind CSS on file changes${inRepo(s)}`,
+  },
+
+  // AI agents — infer what they're doing from child processes
+  {
+    // AI agent with dev server child → coding + serving
+    test: (s) => isAIAgent(s) && anyProcessMatches(s, /next\s+dev|vite|npm\s+run\s+dev/),
+    activity: 'coding',
+    purpose: (s) => `AI coding agent running a dev server${inRepo(s)}`,
+  },
+  {
+    // AI agent with test runner
+    test: (s) => isAIAgent(s) && anyProcessMatches(s, /jest|vitest|pytest|mocha/),
+    activity: 'coding',
+    purpose: (s) => `AI coding agent running tests${inRepo(s)}`,
+  },
+  {
+    // AI agent with build tool
+    test: (s) => isAIAgent(s) && anyProcessMatches(s, /npm\s+run\s+build|tsc(?!\s+--watch)/),
+    activity: 'coding',
+    purpose: (s) => `AI coding agent building the project${inRepo(s)}`,
+  },
+  {
+    // Generic AI agent with a repo → coding
+    test: (s) => isAIAgent(s) && s.repo,
+    activity: 'coding',
+    purpose: (s) => `AI coding agent working on '${s.repo}'`,
+  },
+  {
+    // Generic AI agent without repo
+    test: (s) => isAIAgent(s),
+    activity: 'coding',
+    purpose: (s) => `AI coding agent active`,
+  },
+
+  // npm scripts
+  {
+    // npm run build
+    test: (s) => anyProcessMatches(s, /npm\s+run\s+build/),
+    activity: 'scaffolding',
+    purpose: (s) => `Building project${inRepo(s)}`,
+  },
+  {
+    // npm run dev (generic, not matched by specific framework)
+    test: (s) => anyProcessMatches(s, /npm\s+run\s+dev/),
+    activity: 'serving',
+    purpose: (s) => `Running dev server via npm${inRepo(s)}`,
+  },
+  {
+    // npm test
+    test: (s) => anyProcessMatches(s, /npm\s+(run\s+)?test/),
+    activity: 'watching',
+    purpose: (s) => `Running tests${inRepo(s)}`,
+  },
+
+  // Generic node/python with area inference
+  {
+    // Node script with identifiable file
+    test: (s) => s.detectedAs === 'node' && getScriptArea(s),
+    activity: 'coding',
+    purpose: (s) => {
+      const area = getScriptArea(s);
+      return `Running a ${area} Node.js script${inRepo(s)}`;
+    },
+  },
+  {
+    test: (s) => s.detectedAs === 'python' && getScriptArea(s),
+    activity: 'coding',
+    purpose: (s) => {
+      const area = getScriptArea(s);
+      return `Running a ${area} Python script${inRepo(s)}`;
+    },
+  },
+];
+
+
+// --- Helpers ---
+
+function isAIAgent(session) {
+  return session.type === 'ai-agent';
+}
+
+/** Check if any process in the session matches a regex against its cmd args. */
+function anyProcessMatches(session, regex) {
+  return session.processes.some(p => regex.test(p.cmd));
+}
+
+/** Return " in 'repoName'" or empty string. */
+function inRepo(session) {
+  return session.repo ? ` in '${session.repo}'` : '';
+}
+
+/**
+ * Infer the area of a script from file paths in args.
+ * Looks for common directory/file patterns to classify as frontend, backend, etc.
+ */
+function getScriptArea(session) {
+  const allArgs = session.processes.map(p => p.cmd).join(' ');
+
+  // Frontend signals
+  if (/src\/(components?|pages?|app|views?|ui)\b/.test(allArgs)) return 'frontend';
+  if (/\.(tsx|jsx|vue|svelte)\b/.test(allArgs)) return 'frontend';
+  if (/webpack|babel|postcss|tailwind/.test(allArgs)) return 'frontend';
+
+  // Backend signals
+  if (/src\/(server|api|routes?|controllers?|middleware)\b/.test(allArgs)) return 'backend';
+  if (/server\.(js|ts|py)\b/.test(allArgs)) return 'backend';
+  if (/manage\.py|wsgi|asgi/.test(allArgs)) return 'backend';
+  if (/express|fastify|hono|koa/.test(allArgs)) return 'backend';
+
+  // Config / infra signals
+  if (/\.(config|rc|env|json|ya?ml)\b/.test(allArgs)) return 'config';
+  if (/docker|terraform|ansible|k8s|kubernetes/.test(allArgs)) return 'infra';
+
+  // Test signals
+  if (/test|spec|__tests__|\.test\.|\.spec\./.test(allArgs)) return 'test';
+
+  return null;
+}
+
+
+/**
+ * Add activity and purpose to each session. Mutates in place.
+ */
+export function addPurpose(sessions) {
+  for (const session of sessions) {
+    let matched = false;
+
+    for (const rule of ACTIVITY_RULES) {
+      if (rule.test(session)) {
+        session.activity = rule.activity;
+        session.purpose = typeof rule.purpose === 'function'
+          ? rule.purpose(session)
+          : rule.purpose;
+        matched = true;
+        break;
+      }
+    }
+
+    // Fallback: idle if low CPU + long running, otherwise unknown
+    if (!matched) {
+      if (session.status.includes('idle')) {
+        session.activity = 'idle';
+        session.purpose = `Idle process${inRepo(session)}`;
+      } else {
+        session.activity = 'coding';
+        session.purpose = `Active process${inRepo(session)}`;
+      }
+    }
+  }
+
+  return sessions;
+}

package/src/agent/repoActivity.js

@@ -0,0 +1,142 @@
+// Repo activity scanner — detects file write activity per session repo.
+// Uses find -mmin -2 for both git and non-git repos (consistent 2-min window).
+// Cached per cwd with 30s TTL. Never throws.
+
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const CACHE_TTL = 30_000; // 30 seconds
+const EXEC_TIMEOUT = 1000; // 1 second per command
+
+// Map<cwd, { result, timestamp }>
+const cache = new Map();
+
+// Directories to exclude from find scans
+const FIND_EXCLUDES = [
+  'node_modules', '.git', 'dist', 'build', '.next', '.nuxt',
+  '__pycache__', '.cache', 'coverage', '.turbo', '.output',
+];
+
+/**
+ * Build prune args for find (shared between probes).
+ */
+function buildPruneArgs() {
+  const pruneArgs = [];
+  for (const dir of FIND_EXCLUDES) {
+    pruneArgs.push('-name', dir, '-prune', '-o');
+  }
+  return pruneArgs;
+}
+
+/**
+ * Best-effort newest mtime from a list of files using stat.
+ */
+async function newestMtime(files) {
+  if (files.length === 0) return null;
+  try {
+    const filesToStat = files.slice(0, 50);
+    const statArgs = process.platform === 'darwin'
+      ? ['-f', '%m', ...filesToStat]
+      : ['-c', '%Y', ...filesToStat];
+
+    const { stdout } = await execFileAsync('stat', statArgs, {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT,
+    });
+
+    const mtimes = stdout.trim().split('\n')
+      .map(s => parseInt(s.trim(), 10) * 1000)
+      .filter(t => !isNaN(t));
+    return mtimes.length > 0 ? Math.max(...mtimes) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find files modified in the last N minutes under cwd.
+ * Returns list of file paths (capped at 200).
+ */
+async function findRecentFiles(cwd, minutes) {
+  try {
+    const pruneArgs = buildPruneArgs();
+    const args = [
+      cwd, '-maxdepth', '4',
+      ...pruneArgs,
+      '-type', 'f', '-mmin', `-${minutes}`, '-print',
+    ];
+
+    const { stdout } = await execFileAsync('find', args, {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT,
+      maxBuffer: 64 * 1024,
+    });
+
+    const trimmed = stdout.trim();
+    if (!trimmed) return [];
+    return trimmed.split('\n').slice(0, 200);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Probe a single repo for file activity.
+ * Returns a repoActivity object or null.
+ */
+async function probeRepo(cwd) {
+  const now = Date.now();
+
+  // Check cache
+  const cached = cache.get(cwd);
+  if (cached && now - cached.timestamp < CACHE_TTL) {
+    return cached.result;
+  }
+
+  try {
+    // Count files modified in last 2 minutes
+    const recentFiles = await findRecentFiles(cwd, 2);
+    const filesChanged = recentFiles.length;
+
+    // Get most recent mtime from files modified in last 30 minutes
+    let lastFileWriteAt = null;
+    const recentFiles30m = await findRecentFiles(cwd, 30);
+    if (recentFiles30m.length > 0) {
+      lastFileWriteAt = await newestMtime(recentFiles30m);
+    }
+
+    const result = {
+      lastFileWriteAt,
+      filesChangedLast2m: filesChanged,
+      repoWriteRate: filesChanged / 2, // writes per minute (window is 2min)
+      lastCheckedAt: now,
+    };
+
+    cache.set(cwd, { result, timestamp: now });
+    return result;
+  } catch {
+    cache.set(cwd, { result: null, timestamp: now });
+    return null;
+  }
+}
+
+/**
+ * Merge repo activity data into sessions. Mutates in place.
+ * Skips sessions without a cwd.
+ */
+export async function mergeRepoActivity(sessions) {
+  const promises = sessions.map(async (session) => {
+    if (!session.cwd || session.cwd === '/') return;
+    const activity = await probeRepo(session.cwd);
+    if (activity) {
+      session.repoActivity = activity;
+    }
+  });
+
+  await Promise.all(promises);
+  return sessions;
+}