runtime-inspector 0.1.0

package/src/agent/detector.js

@@ -0,0 +1,235 @@
+// Framework and AI agent detection via heuristics
+
+const AI_AGENT_PATTERNS = [
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    icon: '🤖',
+    type: 'ai-agent',
+    match: (p) => /claude/i.test(p.comm) || /claude/i.test(p.args),
+  },
+  {
+    id: 'codex',
+    name: 'Codex CLI',
+    icon: '🧠',
+    type: 'ai-agent',
+    match: (p) => /codex/i.test(p.comm) || /codex/i.test(p.args),
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    icon: '📝',
+    type: 'ai-agent',
+    match: (p) => /cursor/i.test(p.comm) || /cursor.*server/i.test(p.args),
+  },
+  {
+    id: 'copilot',
+    name: 'GitHub Copilot',
+    icon: '🐙',
+    type: 'ai-agent',
+    match: (p) => /copilot/i.test(p.args),
+  },
+  {
+    id: 'aider',
+    name: 'Aider',
+    icon: '🛠️',
+    type: 'ai-agent',
+    match: (p) => /aider/i.test(p.comm) || /aider/i.test(p.args),
+  },
+  {
+    id: 'continue',
+    name: 'Continue',
+    icon: '🔄',
+    type: 'ai-agent',
+    match: (p) => /continue.*server/i.test(p.args),
+  },
+];
+
+const FRAMEWORK_PATTERNS = [
+  {
+    id: 'nextjs',
+    name: 'Next.js',
+    icon: '▲',
+    type: 'dev-server',
+    match: (p) => /next\s+(dev|start|build)/.test(p.args) || /next-server/.test(p.args),
+  },
+  {
+    id: 'vite',
+    name: 'Vite',
+    icon: '⚡',
+    type: 'dev-server',
+    // Guard: exclude when vite appears only inside a node_modules path in args
+    match: (p) => /vite/.test(p.args) && !/node_modules\/.*vite/.test(p.args),
+  },
+  {
+    id: 'react-scripts',
+    name: 'React Dev Server',
+    icon: '⚛️',
+    type: 'dev-server',
+    match: (p) => /react-scripts\s+start/.test(p.args),
+  },
+  {
+    id: 'webpack-dev',
+    name: 'Webpack Dev Server',
+    icon: '📦',
+    type: 'dev-server',
+    match: (p) => /webpack.*dev.*server/.test(p.args) || /webpack.*serve/.test(p.args),
+  },
+  {
+    id: 'fastapi',
+    name: 'FastAPI',
+    icon: '🚀',
+    type: 'dev-server',
+    match: (p) => /uvicorn/.test(p.args) || /fastapi/.test(p.args),
+  },
+  {
+    id: 'flask',
+    name: 'Flask',
+    icon: '🧪',
+    type: 'dev-server',
+    match: (p) => /flask\s+run/.test(p.args) || /FLASK_APP/.test(p.args),
+  },
+  {
+    id: 'django',
+    name: 'Django',
+    icon: '🎯',
+    type: 'dev-server',
+    match: (p) => /manage\.py\s+runserver/.test(p.args),
+  },
+  {
+    id: 'docker-compose',
+    name: 'Docker Compose',
+    icon: '🐳',
+    type: 'dev-server',
+    match: (p) => /docker.compose/.test(p.args) || /docker-compose/.test(p.comm),
+  },
+  {
+    id: 'docker',
+    name: 'Docker',
+    icon: '🐳',
+    type: 'dev-server',
+    // Only match docker CLI commands, not the daemon
+    match: (p) => p.comm === 'docker' && p.comm !== 'dockerd',
+  },
+  {
+    id: 'dockerd',
+    name: 'Docker Daemon',
+    icon: '🐳',
+    type: 'script', // daemon is infrastructure, not a dev-server
+    match: (p) => p.comm === 'dockerd',
+  },
+  {
+    id: 'node',
+    name: 'Node.js',
+    icon: '🟢',
+    type: 'script',
+    match: (p) => p.comm === 'node' && !/next|vite|webpack|react-scripts/.test(p.args),
+  },
+  {
+    id: 'python',
+    name: 'Python',
+    icon: '🐍',
+    type: 'script',
+    match: (p) => /^python/.test(p.comm),
+  },
+  {
+    id: 'npm-run',
+    name: 'npm script',
+    icon: '📦',
+    type: 'script',
+    // Exclude npm run build/test which have their own categories
+    match: (p) => /npm\s+run\b/.test(p.args) && !/npm\s+run\s+(build|test)\b/.test(p.args),
+  },
+  {
+    id: 'pnpm-run',
+    name: 'pnpm script',
+    icon: '📦',
+    type: 'script',
+    match: (p) => /pnpm\s+(run|dev|start)\b/.test(p.args),
+  },
+  {
+    id: 'yarn-run',
+    name: 'Yarn script',
+    icon: '📦',
+    type: 'script',
+    match: (p) => /yarn\s+(run|dev|start)\b/.test(p.args) || p.comm === 'yarn',
+  },
+  {
+    id: 'bun-run',
+    name: 'Bun script',
+    icon: '🍞',
+    type: 'script',
+    match: (p) => p.comm === 'bun' || /bun\s+(run|dev|start)\b/.test(p.args),
+  },
+  {
+    id: 'npm-build',
+    name: 'npm build',
+    icon: '🔨',
+    type: 'script',
+    match: (p) => /npm\s+run\s+build\b/.test(p.args),
+  },
+  {
+    id: 'npm-test',
+    name: 'npm test',
+    icon: '🧪',
+    type: 'script',
+    match: (p) => /npm\s+(test|run\s+test)\b/.test(p.args),
+  },
+  {
+    id: 'tsc-watch',
+    name: 'TypeScript Compiler (watch)',
+    icon: '🔷',
+    type: 'script',
+    match: (p) => /tsc/.test(p.args) && /--watch\b/.test(p.args),
+  },
+  {
+    id: 'tsc',
+    name: 'TypeScript Compiler',
+    icon: '🔷',
+    type: 'script',
+    match: (p) => /tsc/.test(p.args) && !/--watch\b/.test(p.args),
+  },
+  {
+    id: 'cargo',
+    name: 'Cargo (Rust)',
+    icon: '🦀',
+    type: 'script',
+    match: (p) => p.comm === 'cargo' || /cargo\s+(build|run|test|watch)/.test(p.args),
+  },
+  {
+    id: 'go-run',
+    name: 'Go',
+    icon: '🐹',
+    type: 'script',
+    match: (p) => /go\s+(run|build|test)/.test(p.args),
+  },
+];
+
+const ALL_PATTERNS = [...AI_AGENT_PATTERNS, ...FRAMEWORK_PATTERNS];
+
+/**
+ * Detect what a process is.
+ * Returns { id, name, icon, type } or null.
+ */
+export function detectProcess(process) {
+  for (const pattern of ALL_PATTERNS) {
+    if (pattern.match(process)) {
+      return { id: pattern.id, name: pattern.name, icon: pattern.icon, type: pattern.type };
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect all processes in a list, returning detection info keyed by pid.
+ */
+export function detectAll(processes) {
+  const results = new Map();
+  for (const p of processes) {
+    const detection = detectProcess(p);
+    if (detection) {
+      results.set(p.pid, detection);
+    }
+  }
+  return results;
+}

package/src/agent/explainer.js

@@ -0,0 +1,137 @@
+// Explanation engine — generates human-readable descriptions for sessions.
+// Tone: confident and direct. No "appears to be" or "looks like".
+
+function timeSince(isoString) {
+  const seconds = Math.floor((Date.now() - new Date(isoString).getTime()) / 1000);
+  if (seconds < 5) return 'just now';
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ${minutes % 60}m`;
+}
+
+const TEMPLATES = {
+  'claude-code': (s) => {
+    const childCount = s.processes.length - 1;
+    const children = childCount > 0 ? ` with ${childCount} child process${childCount > 1 ? 'es' : ''}` : '';
+    const repo = s.repo ? ` in '${s.repo}'` : '';
+    return `Claude Code session${repo}${children}, running for ${s.duration}.`;
+  },
+
+  'codex': (s) => {
+    const repo = s.repo ? ` in '${s.repo}'` : '';
+    return `Codex CLI session${repo}, running for ${s.duration}.`;
+  },
+
+  'cursor': (s) => {
+    const repo = s.repo ? ` editing '${s.repo}'` : '';
+    return `Cursor editor${repo}, active for ${s.duration}.`;
+  },
+
+  'copilot': (s) => {
+    return `GitHub Copilot agent, running for ${s.duration}.`;
+  },
+
+  'aider': (s) => {
+    const repo = s.repo ? ` in '${s.repo}'` : '';
+    return `Aider AI coding session${repo}, running for ${s.duration}.`;
+  },
+
+  'nextjs': (s) => {
+    const repo = s.repo ? ` for '${s.repo}'` : '';
+    return `Next.js dev server${repo}, watching files and serving on localhost. Running for ${s.duration}.`;
+  },
+
+  'vite': (s) => {
+    const repo = s.repo ? ` for '${s.repo}'` : '';
+    return `Vite dev server${repo} with HMR active. Running for ${s.duration}.`;
+  },
+
+  'react-scripts': (s) => {
+    const repo = s.repo ? ` for '${s.repo}'` : '';
+    return `React dev server${repo} with live reload. Running for ${s.duration}.`;
+  },
+
+  'webpack-dev': (s) => {
+    const repo = s.repo ? ` for '${s.repo}'` : '';
+    return `Webpack dev server${repo} watching files. Running for ${s.duration}.`;
+  },
+
+  'fastapi': (s) => {
+    const repo = s.repo ? ` serving '${s.repo}'` : '';
+    return `FastAPI server${repo} via Uvicorn. Active for ${s.duration}.`;
+  },
+
+  'flask': (s) => {
+    const repo = s.repo ? ` for '${s.repo}'` : '';
+    return `Flask dev server${repo}. Running for ${s.duration}.`;
+  },
+
+  'django': (s) => {
+    const repo = s.repo ? ` for '${s.repo}'` : '';
+    return `Django dev server${repo}. Active for ${s.duration}.`;
+  },
+
+  'docker-compose': (s) => {
+    const count = s.processes.length;
+    return `Docker Compose stack, ${count} process${count > 1 ? 'es' : ''}. Running for ${s.duration}.`;
+  },
+
+  'docker': (s) => {
+    return `Docker daemon, active for ${s.duration}.`;
+  },
+
+  'node': (s) => {
+    const repo = s.repo ? ` in '${s.repo}'` : '';
+    return `Node.js process${repo}. Running for ${s.duration}.`;
+  },
+
+  'python': (s) => {
+    const repo = s.repo ? ` in '${s.repo}'` : '';
+    return `Python process${repo}. Running for ${s.duration}.`;
+  },
+
+  'npm-run': (s) => {
+    const repo = s.repo ? ` in '${s.repo}'` : '';
+    return `npm script${repo}. Running for ${s.duration}.`;
+  },
+
+  'tsc': (s) => {
+    const repo = s.repo ? ` for '${s.repo}'` : '';
+    return `TypeScript compiler in watch mode${repo}. Running for ${s.duration}.`;
+  },
+};
+
+/**
+ * Add explanations to sessions. Mutates in place.
+ */
+export function addExplanations(sessions) {
+  for (const session of sessions) {
+    const template = TEMPLATES[session.detectedAs];
+    if (template) {
+      session.explanation = template(session);
+    } else {
+      const repo = session.repo ? ` in '${session.repo}'` : '';
+      session.explanation = `Process group${repo}, ${session.processes.length} process${session.processes.length > 1 ? 'es' : ''}. Running for ${session.duration}.`;
+    }
+
+    // Prepend wrapper context if wrapped
+    if (session.isWrapped && session.runtimeState) {
+      const stateLabel = session.runtimeState;
+      const lastActivity = session.lastActivityAt
+        ? ` Last output ${timeSince(session.lastActivityAt)} ago.`
+        : '';
+      session.explanation = `Running via RuntimeInspector wrapper. Currently ${stateLabel}.${lastActivity} ` + session.explanation;
+    }
+
+    // Append status context
+    if (session.status.includes('high-cpu')) {
+      session.explanation += ' High CPU usage.';
+    }
+    if (session.status.includes('idle')) {
+      session.explanation += ' Currently idle.';
+    }
+  }
+  return sessions;
+}

package/src/agent/grouper.js

@@ -0,0 +1,161 @@
+// Session grouper — groups processes into logical sessions
+import { detectAll } from './detector.js';
+import { getCwd } from './scanner.js';
+
+/**
+ * Build a pid->process map and a pid->children map (process tree).
+ */
+function buildTree(processes) {
+  const byPid = new Map();
+  const children = new Map();
+
+  for (const p of processes) {
+    byPid.set(p.pid, p);
+    if (!children.has(p.ppid)) children.set(p.ppid, []);
+    children.get(p.ppid).push(p.pid);
+  }
+
+  return { byPid, children };
+}
+
+/**
+ * Get all descendant pids of a given pid.
+ */
+function getDescendants(pid, children) {
+  const result = [];
+  const stack = [pid];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const kids = children.get(current) || [];
+    for (const kid of kids) {
+      result.push(kid);
+      stack.push(kid);
+    }
+  }
+  return result;
+}
+
+/**
+ * Extract repo name from a cwd path.
+ */
+function extractRepo(cwd) {
+  if (!cwd) return null;
+  // Try to find a meaningful directory name
+  const parts = cwd.split('/').filter(Boolean);
+  // Skip common prefixes
+  const skip = new Set(['Users', 'home', 'var', 'tmp', 'opt', 'usr', 'private']);
+  for (let i = parts.length - 1; i >= 0; i--) {
+    if (!skip.has(parts[i]) && !parts[i].startsWith('.')) {
+      return parts[i];
+    }
+  }
+  return parts[parts.length - 1] || null;
+}
+
+/**
+ * Group processes into sessions.
+ */
+export async function groupIntoSessions(processes) {
+  const { byPid, children } = buildTree(processes);
+  const detections = detectAll(processes);
+  const assigned = new Set();
+  const sessions = [];
+
+  // Ignore system/low-level processes
+  const IGNORE_COMMS = new Set([
+    'kernel_task', 'launchd', 'syslogd', 'mds', 'mds_stores',
+    'WindowServer', 'loginwindow', 'SystemUIServer', 'Dock', 'Finder',
+    'coreaudiod', 'bluetoothd', 'distnoted', 'cfprefsd',
+  ]);
+
+  // Pass 1: Build sessions around detected root processes
+  // Sort by detection priority: ai-agents first, then dev-servers, then scripts
+  const typePriority = { 'ai-agent': 0, 'dev-server': 1, 'script': 2 };
+  const detectedPids = [...detections.entries()]
+    .sort((a, b) => (typePriority[a[1].type] ?? 3) - (typePriority[b[1].type] ?? 3));
+
+  for (const [pid, detection] of detectedPids) {
+    if (assigned.has(pid)) continue;
+
+    const rootProcess = byPid.get(pid);
+    if (!rootProcess || IGNORE_COMMS.has(rootProcess.comm)) continue;
+
+    // Gather this process + all descendants
+    const descendantPids = getDescendants(pid, children);
+    const sessionPids = [pid, ...descendantPids].filter(p => !assigned.has(p));
+
+    if (sessionPids.length === 0) continue;
+
+    // Mark all as assigned
+    for (const sp of sessionPids) assigned.add(sp);
+
+    const sessionProcesses = sessionPids
+      .map(p => byPid.get(p))
+      .filter(Boolean);
+
+    // Aggregate stats
+    const totalCpu = sessionProcesses.reduce((sum, p) => sum + p.cpu, 0);
+    const totalMem = sessionProcesses.reduce((sum, p) => sum + p.mem, 0);
+    const maxElapsed = sessionProcesses.reduce((max, p) => Math.max(max, p.elapsedSeconds), 0);
+
+    // Lookup cwd only for the root process of each session (lazy, avoids scanning all)
+    const cwd = await getCwd(rootProcess.pid);
+
+    const repo = extractRepo(cwd);
+
+    // Determine statuses
+    const statuses = [];
+    if (maxElapsed > 3600) statuses.push('long-running');
+    if (totalCpu > 80) statuses.push('high-cpu');
+    if (totalCpu < 0.1 && maxElapsed > 300) statuses.push('idle');
+
+    // Orphan detection: ppid=1 means parented by launchd/init, which is normal
+    // for system services. Only flag as orphan if this is a dev-tool type session
+    // (dev-server or script) that was likely started from a terminal but whose
+    // parent shell died. AI agents manage their own lifecycle so exclude them.
+    if (rootProcess.ppid === 1 && detection.type !== 'ai-agent') {
+      // Check if this looks like it was started from a terminal: dev-servers
+      // and scripts with a cwd inside a user home directory
+      const home = process.env.HOME || '/Users';
+      const isUserProcess = cwd && cwd.startsWith(home);
+      if (isUserProcess) {
+        statuses.push('orphan');
+      }
+    }
+
+    sessions.push({
+      id: `session-${pid}`,
+      type: detection.type,
+      icon: detection.icon,
+      title: detection.name + (repo ? ` — ${repo}` : ''),
+      detectedAs: detection.id,
+      repo,
+      cwd,
+      duration: formatDuration(maxElapsed),
+      durationSeconds: maxElapsed,
+      cpu: Math.round(totalCpu * 10) / 10,
+      memory: Math.round(totalMem * 10) / 10,
+      status: statuses,
+      explanation: '', // filled in by explainer
+      processes: sessionProcesses.map(p => ({
+        pid: p.pid,
+        cmd: p.args,
+        cpu: p.cpu,
+        mem: p.mem,
+      })),
+    });
+  }
+
+  return sessions;
+}
+
+/**
+ * Format seconds into a human readable string.
+ */
+function formatDuration(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  return `${h}h ${m}m`;
+}