runtime-inspector 0.1.0

package/src/agent/scanner.js

@@ -0,0 +1,117 @@
+// Process scanner — collects OS process information
+import { execFile } from 'child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Scan all running processes and return structured data.
+ * Uses `ps` on macOS/Linux. Does NOT look up cwd here (too slow for all procs).
+ */
+export async function scanProcesses() {
+  try {
+    const { stdout: raw } = await execFileAsync(
+      'ps', ['-eo', 'pid,ppid,pcpu,pmem,etime,comm,args'],
+      { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, timeout: 5000 }
+    );
+
+    const lines = raw.trim().split('\n').slice(1); // skip header
+    const processes = [];
+
+    for (const line of lines) {
+      const parsed = parsePsLine(line);
+      if (parsed) processes.push(parsed);
+    }
+
+    return processes;
+  } catch (err) {
+    console.error('[scanner] Failed to scan processes:', err.message);
+    return [];
+  }
+}
+
+/**
+ * Parse a single line of ps output.
+ */
+function parsePsLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  // Match: PID  PPID  %CPU  %MEM  ELAPSED  COMM  ARGS...
+  const match = trimmed.match(
+    /^\s*(\d+)\s+(\d+)\s+([\d.]+)\s+([\d.]+)\s+(\S+)\s+(\S+)\s+(.*)$/
+  );
+  if (!match) return null;
+
+  const [, pid, ppid, cpu, mem, etime, comm, args] = match;
+
+  return {
+    pid: parseInt(pid, 10),
+    ppid: parseInt(ppid, 10),
+    cpu: parseFloat(cpu),
+    mem: parseFloat(mem),
+    elapsed: etime.trim(),
+    elapsedSeconds: parseElapsed(etime.trim()),
+    comm: comm.trim(),
+    args: args.trim(),
+    cwd: null, // populated lazily by grouper for interesting pids only
+  };
+}
+
+/**
+ * Parse ps elapsed time format (e.g., "01:23:45", "12:34", "3-01:23:45") to seconds.
+ */
+function parseElapsed(etime) {
+  const parts = etime.replace(/-/g, ':').split(':').map(Number);
+  if (parts.length === 2) return parts[0] * 60 + parts[1];
+  if (parts.length === 3) return parts[0] * 3600 + parts[1] * 60 + parts[2];
+  if (parts.length === 4) return parts[0] * 86400 + parts[1] * 3600 + parts[2] * 60 + parts[3];
+  return 0;
+}
+
+/**
+ * Best-effort cwd lookup via lsof (macOS/Linux). Only call for specific pids.
+ */
+const cwdCache = new Map();
+const CWD_CACHE_TTL = 30000;
+
+/**
+ * Evict cwdCache entries for PIDs no longer in the live process list.
+ */
+export function evictStaleCwdEntries(livePids) {
+  for (const pid of cwdCache.keys()) {
+    if (!livePids.has(pid)) {
+      cwdCache.delete(pid);
+    }
+  }
+}
+
+export async function getCwd(pid) {
+  const now = Date.now();
+  const cached = cwdCache.get(pid);
+  if (cached && now - cached.time < CWD_CACHE_TTL) return cached.value;
+
+  const safePid = parseInt(pid, 10);
+  if (isNaN(safePid) || safePid <= 0) return null;
+
+  try {
+    const { stdout: result } = await execFileAsync(
+      'lsof', ['-a', '-p', String(safePid), '-d', 'cwd', '-Fn'],
+      { encoding: 'utf-8', timeout: 1000 }
+    );
+    // Output format: p<pid>\nfcwd\nn<path>
+    const lines = result.trim().split('\n');
+    let cwd = null;
+    for (const line of lines) {
+      if (line.startsWith('n/')) {
+        cwd = line.slice(1);
+        break;
+      }
+    }
+    cwdCache.set(pid, { value: cwd, time: now });
+    return cwd;
+  } catch {
+    cwdCache.set(pid, { value: null, time: now });
+    return null;
+  }
+}

package/src/agent/shellEvents.js

@@ -0,0 +1,115 @@
+// Shell event bus — stores command lifecycle events from shell hooks.
+// In-memory ring buffer per TTY. No persistence.
+
+const MAX_EVENTS_PER_TTY = 200;
+
+// Map<tty, event[]>
+const eventStore = new Map();
+
+/**
+ * Validate and ingest a shell event.
+ * Returns { ok: true } or { error: string }.
+ */
+export function ingestShellEvent(event) {
+  if (!event || !event.type) {
+    return { error: 'missing event type' };
+  }
+  if (!event.tty && !event.shellPid) {
+    return { error: 'missing tty or shellPid' };
+  }
+
+  // Normalize
+  const key = event.tty || `pid-${event.shellPid}`;
+  const stored = {
+    type: event.type,
+    shellType: event.shellType || 'unknown',
+    tty: event.tty || null,
+    shellPid: event.shellPid || null,
+    cwd: event.cwd || null,
+    command: event.command || null,
+    exitCode: event.exitCode ?? null,
+    timestamp: event.timestamp || Date.now(),
+    username: event.username || null,
+    host: event.host || null,
+  };
+
+  if (!eventStore.has(key)) {
+    eventStore.set(key, []);
+  }
+
+  const buffer = eventStore.get(key);
+  buffer.push(stored);
+
+  // Ring buffer trim
+  if (buffer.length > MAX_EVENTS_PER_TTY) {
+    buffer.splice(0, buffer.length - MAX_EVENTS_PER_TTY);
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Get a snapshot of all shell events, grouped by TTY.
+ */
+export function getShellEventsSnapshot() {
+  const result = {};
+  for (const [tty, events] of eventStore) {
+    result[tty] = events.slice(-50); // last 50 per tty for API response
+  }
+  return result;
+}
+
+/**
+ * Get summary stats for shell events.
+ */
+export function getShellEventStats() {
+  let totalEvents = 0;
+  let activeTtys = 0;
+  const now = Date.now();
+
+  for (const [, events] of eventStore) {
+    totalEvents += events.length;
+    // Active if any event in last 5 minutes
+    const latest = events[events.length - 1];
+    if (latest && now - latest.timestamp < 5 * 60 * 1000) {
+      activeTtys++;
+    }
+  }
+
+  return { totalEvents, totalTtys: eventStore.size, activeTtys };
+}
+
+/**
+ * Evict TTY entries with no events in the last 30 minutes.
+ */
+const STALE_TTY_THRESHOLD = 30 * 60 * 1000;
+
+export function evictStaleShellEvents() {
+  const now = Date.now();
+  for (const [tty, events] of eventStore) {
+    const latest = events[events.length - 1];
+    if (!latest || now - latest.timestamp > STALE_TTY_THRESHOLD) {
+      eventStore.delete(tty);
+    }
+  }
+}
+
+/**
+ * Register shell event routes on the Express app.
+ */
+export function registerShellEventRoutes(app) {
+  app.post('/api/shell/event', (req, res) => {
+    const result = ingestShellEvent(req.body);
+    if (result.error) {
+      return res.status(400).json(result);
+    }
+    res.json(result);
+  });
+
+  app.get('/api/shell/events', (req, res) => {
+    res.json({
+      events: getShellEventsSnapshot(),
+      stats: getShellEventStats(),
+    });
+  });
+}

package/src/agent/shellMerge.js

@@ -0,0 +1,103 @@
+// Shell context merge — enriches sessions with shell event data.
+// Matches shell events to sessions by cwd or TTY, attaches
+// lastCommand, commandState, waitingForInput, etc.
+
+import { getShellEventsSnapshot } from './shellEvents.js';
+
+/**
+ * Merge shell context into sessions. Mutates in place.
+ * Called after mergeRepoActivity() and before mergeWrappedData().
+ */
+export function mergeShellContext(sessions) {
+  const snapshot = getShellEventsSnapshot();
+  const ttyKeys = Object.keys(snapshot);
+
+  if (ttyKeys.length === 0) return sessions;
+
+  for (const session of sessions) {
+    const cwd = session.cwd;
+    if (!cwd) continue;
+
+    // Find the best-matching TTY for this session:
+    // 1. Match by cwd in recent events
+    // 2. Match by shellPid appearing in session process tree
+    let bestTty = null;
+    let bestEvents = null;
+    let bestScore = 0;
+
+    for (const ttyKey of ttyKeys) {
+      const events = snapshot[ttyKey];
+      if (!events || events.length === 0) continue;
+
+      let score = 0;
+
+      // Check if any event's cwd matches session cwd
+      for (let i = events.length - 1; i >= Math.max(0, events.length - 10); i--) {
+        if (events[i].cwd && events[i].cwd === cwd) {
+          score += 10;
+          break;
+        }
+      }
+
+      // Check if shellPid is in the session's process tree
+      const shellPid = events[0]?.shellPid;
+      if (shellPid && session.processes.some(p => p.pid === shellPid || p.ppid === shellPid)) {
+        score += 20;
+      }
+
+      if (score > bestScore) {
+        bestScore = score;
+        bestTty = ttyKey;
+        bestEvents = events;
+      }
+    }
+
+    if (!bestEvents || bestScore === 0) continue;
+
+    // Extract shell context from matched events
+    const lastEvent = bestEvents[bestEvents.length - 1];
+    const lastStartEvent = findLastOfType(bestEvents, 'command_start');
+    const lastEndEvent = findLastOfType(bestEvents, 'command_end');
+
+    session.tty = bestTty;
+    session.shellPid = lastEvent.shellPid;
+
+    if (lastStartEvent) {
+      session.lastCommand = lastStartEvent.command;
+      session.lastCommandAt = lastStartEvent.timestamp;
+
+      // Determine command state
+      if (lastEndEvent && lastEndEvent.timestamp > lastStartEvent.timestamp) {
+        // Command finished
+        session.commandState = 'completed';
+        session.lastCommandExitCode = lastEndEvent.exitCode;
+        session.waitingForInput = true;
+        session.lastInputAt = lastEndEvent.timestamp;
+      } else {
+        // Command is still running
+        session.commandState = 'running';
+        session.waitingForInput = false;
+      }
+    } else if (lastEndEvent) {
+      session.commandState = 'completed';
+      session.lastCommandExitCode = lastEndEvent.exitCode;
+      session.waitingForInput = true;
+      session.lastInputAt = lastEndEvent.timestamp;
+    }
+
+    // Count recent commands (last 5 minutes)
+    const fiveMinAgo = Date.now() - 5 * 60 * 1000;
+    session.recentCommandCount = bestEvents.filter(
+      e => e.type === 'command_start' && e.timestamp > fiveMinAgo
+    ).length;
+  }
+
+  return sessions;
+}
+
+function findLastOfType(events, type) {
+  for (let i = events.length - 1; i >= 0; i--) {
+    if (events[i].type === type) return events[i];
+  }
+  return null;
+}

package/src/agent/stateInfer.js

@@ -0,0 +1,72 @@
+// Runtime state inference for sessions (wrapped and non-wrapped)
+
+/**
+ * Infer runtime state for a session.
+ * For wrapped sessions, the wrapper provides the state directly.
+ * For non-wrapped sessions, use CPU/status heuristics.
+ *
+ * States: starting, progressing, idle, stuck, done, failed, working
+ */
+export function inferState(session) {
+  // Wrapped sessions already carry state from the wrapper report
+  if (session.isWrapped && session.runtimeState) {
+    return session.runtimeState;
+  }
+
+  // Non-wrapped: heuristic from CPU + status flags
+  const cpu = session.cpu || 0;
+  const elapsed = session.durationSeconds || session.elapsedSeconds || 0;
+
+  if (elapsed < 5) return 'starting';
+  if (session.status?.includes('idle') && cpu < 1) return 'idle';
+  if (session.status?.includes('high-cpu') && cpu > 50) return 'working';
+  if (cpu > 5) return 'progressing';
+  if (cpu < 0.1 && elapsed > 300) return 'idle';
+  if (cpu >= 0.1) return 'progressing';
+
+  return 'progressing'; // default for active sessions
+}
+
+/**
+ * Simple ETA heuristic for common tasks.
+ * Returns a string like "~2m remaining" or null.
+ */
+export function estimateEta(session) {
+  if (!session.isWrapped) return null;
+  if (!session.runtimeState || session.runtimeState === 'done' || session.runtimeState === 'failed') return null;
+
+  const cmd = session.wrappedCmd || '';
+  const lineCount = session.wrappedLineCount || 0;
+
+  // npm install: rough estimate ~50 lines/min
+  if (/npm\s+(install|ci|i)\b/.test(cmd) && lineCount > 5) {
+    // Most npm installs are 50-200 lines. Very rough.
+    const elapsed = (Date.now() - new Date(session.wrappedStartedAt).getTime()) / 1000;
+    const rate = lineCount / Math.max(elapsed, 1); // lines per second
+    if (rate > 0 && lineCount < 200) {
+      const remaining = Math.round((200 - lineCount) / rate);
+      if (remaining > 2 && remaining < 300) {
+        return `~${Math.ceil(remaining / 60)}m remaining`;
+      }
+    }
+  }
+
+  // Build/dev servers: no ETA
+  return null;
+}
+
+/**
+ * Add state inference to all sessions. Mutates in place.
+ */
+export function addStateInference(sessions) {
+  for (const session of sessions) {
+    if (!session.runtimeState) {
+      const state = inferState(session);
+      if (state) session.runtimeState = state;
+    }
+    if (!session.eta) {
+      session.eta = estimateEta(session);
+    }
+  }
+  return sessions;
+}

package/src/agent/tmux.js

@@ -0,0 +1,210 @@
+// tmux integration — snapshot collector + output-activity sampling.
+// Optional: silently disables if tmux is not installed or no server running.
+// Privacy-first: only stores sha1 hashes of pane output, never the text itself.
+
+import { spawnSync, execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const MAX_PANES_TO_SAMPLE = 20;
+const SAMPLE_COOLDOWN_MS = 5_000; // min 5s between full sampling rounds
+const PANE_CACHE_TTL = 5 * 60 * 1000; // evict entries for disappeared panes after 5m
+
+// ---- Availability check ----
+
+let _tmuxChecked = false;
+let _tmuxAvailable = false;
+
+export function isTmuxAvailable() {
+  if (_tmuxChecked) return _tmuxAvailable;
+  _tmuxChecked = true;
+
+  try {
+    const r = spawnSync('tmux', ['-V'], { timeout: 1000, encoding: 'utf-8', stdio: 'pipe' });
+    if (r.status !== 0 && r.status !== null) {
+      _tmuxAvailable = false;
+      return false;
+    }
+    // Also check if a tmux server is actually running
+    const s = spawnSync('tmux', ['list-sessions'], { timeout: 1000, encoding: 'utf-8', stdio: 'pipe' });
+    _tmuxAvailable = s.status === 0;
+  } catch {
+    _tmuxAvailable = false;
+  }
+  return _tmuxAvailable;
+}
+
+/**
+ * Re-check tmux availability (call periodically in case user starts/stops tmux).
+ */
+export function recheckTmux() {
+  _tmuxChecked = false;
+  return isTmuxAvailable();
+}
+
+// ---- Pane listing ----
+
+const PANE_FORMAT = '#{pane_id}\t#{window_id}\t#{session_name}\t#{pane_pid}\t#{pane_tty}\t#{pane_current_path}\t#{?pane_active,1,0}';
+
+/**
+ * List all tmux panes. Returns [] if tmux unavailable.
+ */
+export async function listPanes() {
+  if (!isTmuxAvailable()) return [];
+
+  try {
+    const { stdout } = await execFileAsync(
+      'tmux', ['list-panes', '-a', '-F', PANE_FORMAT],
+      { timeout: 2000, encoding: 'utf-8' }
+    );
+
+    if (!stdout) return [];
+
+    const panes = [];
+    for (const line of stdout.trim().split('\n')) {
+      if (!line) continue;
+      const parts = line.split('\t');
+      if (parts.length < 7) continue;
+
+      panes.push({
+        paneId: parts[0],           // e.g. %0
+        windowId: parts[1],         // e.g. @0
+        sessionName: parts[2],
+        panePid: parseInt(parts[3], 10) || 0,
+        paneTty: parts[4],          // e.g. /dev/ttys003
+        panePath: parts[5],
+        paneActive: parts[6] === '1',
+      });
+    }
+
+    return panes;
+  } catch {
+    return [];
+  }
+}
+
+// ---- Output activity sampling (hash-based, privacy-first) ----
+
+// Map<paneId, { lastHash, lastChangedAt, lastCheckedAt }>
+const paneHashCache = new Map();
+let lastSampleTime = 0;
+
+/**
+ * Compute sha256 hash of the last 50 lines of a pane's visible output.
+ * Returns null on failure (pane gone, tmux error, timeout).
+ */
+export async function getPaneTailHash(paneId) {
+  if (!isTmuxAvailable()) return null;
+
+  try {
+    const { stdout } = await execFileAsync(
+      'tmux', ['capture-pane', '-p', '-t', paneId, '-S', '-50'],
+      { timeout: 500, encoding: 'utf-8' }
+    );
+
+    if (stdout == null) return null;
+
+    // Hash the output — never store the text
+    return createHash('sha256').update(stdout).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sample pane activity for the given pane IDs.
+ * Returns Map<paneId, { lastChangedAt, changedNow, lastCheckedAt }>.
+ *
+ * Rate-limited: will return cached results if called within SAMPLE_COOLDOWN_MS.
+ * Caps at MAX_PANES_TO_SAMPLE panes per round.
+ */
+export async function samplePaneActivity(paneIds) {
+  const now = Date.now();
+  const result = new Map();
+
+  // Rate limit: skip if sampled recently
+  const shouldSample = (now - lastSampleTime) >= SAMPLE_COOLDOWN_MS;
+
+  // Only sample a bounded set
+  const toSample = paneIds.slice(0, MAX_PANES_TO_SAMPLE);
+
+  if (shouldSample) {
+    // Hash all panes concurrently instead of sequentially
+    const hashResults = await Promise.all(
+      toSample.map(async (paneId) => ({
+        paneId,
+        hash: await getPaneTailHash(paneId),
+      }))
+    );
+
+    for (const { paneId, hash } of hashResults) {
+      const cached = paneHashCache.get(paneId);
+
+      if (hash !== null) {
+        const changedNow = cached ? (hash !== cached.lastHash) : true;
+        const entry = {
+          lastHash: hash,
+          lastChangedAt: changedNow ? now : (cached?.lastChangedAt || now),
+          lastCheckedAt: now,
+        };
+        paneHashCache.set(paneId, entry);
+        result.set(paneId, {
+          lastChangedAt: entry.lastChangedAt,
+          changedNow,
+          lastCheckedAt: now,
+        });
+      } else if (cached) {
+        result.set(paneId, {
+          lastChangedAt: cached.lastChangedAt,
+          changedNow: false,
+          lastCheckedAt: cached.lastCheckedAt,
+        });
+      }
+    }
+
+    lastSampleTime = now;
+    cleanStaleCacheEntries(paneIds, now);
+  } else {
+    // Return cached results for all panes
+    for (const paneId of toSample) {
+      const cached = paneHashCache.get(paneId);
+      if (cached) {
+        result.set(paneId, {
+          lastChangedAt: cached.lastChangedAt,
+          changedNow: false,
+          lastCheckedAt: cached.lastCheckedAt,
+        });
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Evict cache entries for panes that no longer appear in current pane list.
+ */
+function cleanStaleCacheEntries(activePaneIds, now) {
+  const activeSet = new Set(activePaneIds);
+  for (const [paneId, entry] of paneHashCache) {
+    if (!activeSet.has(paneId) && (now - entry.lastCheckedAt) > PANE_CACHE_TTL) {
+      paneHashCache.delete(paneId);
+    }
+  }
+}
+
+/**
+ * Register tmux debug endpoint.
+ */
+export function registerTmuxRoutes(app) {
+  app.get('/api/tmux/panes', async (req, res) => {
+    const available = isTmuxAvailable();
+    if (!available) {
+      return res.json({ ok: true, available: false, panes: [] });
+    }
+    const panes = await listPanes();
+    res.json({ ok: true, available: true, panes });
+  });
+}