runtime-inspector 0.1.0

package/src/agent/tmuxMerge.js

@@ -0,0 +1,96 @@
+// tmux context merge — matches tmux panes to sessions, attaches metadata.
+// Runs as a two-pass integration: first merge panes (metadata only),
+// then after activity sampling, attach lastPaneOutputAt.
+
+/**
+ * Merge tmux pane context into sessions. Mutates in place.
+ *
+ * Matching heuristic (priority order):
+ * 1) Session process PID matches pane.panePid (or panePid is ancestor)
+ * 2) Session cwd === pane.panePath
+ * 3) Session repo matches last segment of panePath (weak)
+ *
+ * Each paneId is assigned to at most one session (first best match wins).
+ */
+export function mergeTmuxContext(sessions, panes, paneActivity) {
+  if (!panes || panes.length === 0) return sessions;
+
+  const assigned = new Set();
+
+  // Pass 1: PID match (strongest signal)
+  for (const session of sessions) {
+    if (session.tmux) continue; // already matched in a prior pass
+    const pids = new Set(session.processes.map(p => p.pid));
+    const ppids = new Set(session.processes.map(p => p.ppid).filter(Boolean));
+
+    for (const pane of panes) {
+      if (assigned.has(pane.paneId)) continue;
+      if (pids.has(pane.panePid) || ppids.has(pane.panePid)) {
+        attachTmux(session, pane, paneActivity);
+        assigned.add(pane.paneId);
+        break;
+      }
+    }
+  }
+
+  // Pass 2: cwd match
+  for (const session of sessions) {
+    if (session.tmux) continue;
+    if (!session.cwd) continue;
+
+    for (const pane of panes) {
+      if (assigned.has(pane.paneId)) continue;
+      if (pane.panePath && pane.panePath === session.cwd) {
+        attachTmux(session, pane, paneActivity);
+        assigned.add(pane.paneId);
+        break;
+      }
+    }
+  }
+
+  // Pass 3: repo name match (weak — last path segment)
+  for (const session of sessions) {
+    if (session.tmux) continue;
+    if (!session.repo) continue;
+
+    const repoLower = session.repo.toLowerCase();
+
+    for (const pane of panes) {
+      if (assigned.has(pane.paneId)) continue;
+      if (!pane.panePath) continue;
+
+      const lastSeg = pane.panePath.split('/').filter(Boolean).pop()?.toLowerCase();
+      if (lastSeg && lastSeg === repoLower) {
+        attachTmux(session, pane, paneActivity);
+        assigned.add(pane.paneId);
+        break;
+      }
+    }
+  }
+
+  return sessions;
+}
+
+function attachTmux(session, pane, paneActivity) {
+  const activity = paneActivity?.get(pane.paneId);
+
+  session.tmux = {
+    paneId: pane.paneId,
+    windowId: pane.windowId,
+    sessionName: pane.sessionName,
+    panePid: pane.panePid,
+    paneTty: pane.paneTty,
+    panePath: pane.panePath,
+    paneActive: pane.paneActive,
+    lastPaneOutputAt: activity?.lastChangedAt || null,
+    paneOutputChangedNow: activity?.changedNow || false,
+  };
+
+  // Update lastProgressAt if pane output is more recent
+  if (activity?.lastChangedAt) {
+    const existing = session.lastProgressAt ? new Date(session.lastProgressAt).getTime() : 0;
+    if (activity.lastChangedAt > existing) {
+      session.lastProgressAt = new Date(activity.lastChangedAt).toISOString();
+    }
+  }
+}

package/src/shell/hooks.js

@@ -0,0 +1,181 @@
+// Shell hook script generator — emits shell code for zsh/bash
+// that posts command lifecycle events to the local agent.
+
+const AGENT_URL = 'http://127.0.0.1:7331/api/shell/event';
+
+/**
+ * Generate the shell hook script for the given shell type.
+ */
+export function generateHookScript(shell = 'zsh') {
+  if (shell === 'bash') return bashScript();
+  return zshScript();
+}
+
+function zshScript() {
+  return `
+# RuntimeInspector shell integration (zsh)
+# Posts command start/end events to the local agent.
+# Non-blocking; fails silently if agent is not running.
+
+__runtimeinspector_json_escape() {
+  # Properly escape a string for JSON: backslash, double quote, and control chars
+  local s="\$1"
+  s="\${s//\\\\/\\\\\\\\}"       # \\ -> \\\\
+  s="\${s//\\"/\\\\\\"}"         # " -> \\"
+  s="\${s//$'\\n'/\\\\n}"        # newline -> \\n
+  s="\${s//$'\\r'/\\\\r}"        # carriage return -> \\r
+  s="\${s//$'\\t'/\\\\t}"        # tab -> \\t
+  printf '%s' "\$s"
+}
+
+__runtimeinspector_post_event() {
+  local event_type="\$1"
+  local payload="\$2"
+  local _tty
+  _tty="$(tty 2>/dev/null || echo unknown)"
+  local _ts="\$(date +%s000)"
+  local _cwd
+  _cwd="\$(__runtimeinspector_json_escape "\$(pwd)")"
+  local _host
+  _host="\$(__runtimeinspector_json_escape "\${HOST}")"
+  local _user
+  _user="\$(__runtimeinspector_json_escape "\${USER}")"
+  local _json="{\\"type\\":\\"\${event_type}\\",\\"shellType\\":\\"zsh\\",\\"tty\\":\\"\${_tty}\\",\\"shellPid\\":$$,\\"cwd\\":\\"\${_cwd}\\",\\"timestamp\\":\${_ts},\\"username\\":\\"\${_user}\\",\\"host\\":\\"\${_host}\\",\${payload}}"
+
+  # Non-blocking POST with 150ms timeout; discard output
+  if command -v curl >/dev/null 2>&1; then
+    curl -s -o /dev/null --max-time 0.15 -X POST \\
+      -H "Content-Type: application/json" \\
+      -d "\${_json}" \\
+      "${AGENT_URL}" 2>/dev/null &!
+  fi
+}
+
+# --- preexec: fires BEFORE a command runs ---
+__runtimeinspector_preexec() {
+  __runtimeinspector_cmd_start="\$(date +%s000)"
+  # Properly escape command for JSON safety
+  local _safe_cmd
+  _safe_cmd="\$(__runtimeinspector_json_escape "\$1")"
+  __runtimeinspector_post_event "command_start" "\\"command\\":\\"\${_safe_cmd}\\""
+}
+
+# --- precmd: fires AFTER a command completes, before next prompt ---
+__runtimeinspector_precmd() {
+  local _exit_code=\$?
+  # Only fire if we actually tracked a command start
+  if [[ -n "\${__runtimeinspector_cmd_start:-}" ]]; then
+    __runtimeinspector_post_event "command_end" "\\"exitCode\\":\${_exit_code}"
+    unset __runtimeinspector_cmd_start
+  fi
+}
+
+# Chain into existing hooks without clobbering
+autoload -Uz add-zsh-hook 2>/dev/null
+if (( \${+functions[add-zsh-hook]} )); then
+  add-zsh-hook preexec __runtimeinspector_preexec
+  add-zsh-hook precmd __runtimeinspector_precmd
+else
+  # Fallback: manual chaining
+  if [[ -n "\${preexec_functions+x}" ]]; then
+    preexec_functions+=(__runtimeinspector_preexec)
+  else
+    preexec_functions=(__runtimeinspector_preexec)
+  fi
+  if [[ -n "\${precmd_functions+x}" ]]; then
+    precmd_functions+=(__runtimeinspector_precmd)
+  else
+    precmd_functions=(__runtimeinspector_precmd)
+  fi
+fi
+`;
+}
+
+function bashScript() {
+  return `
+# RuntimeInspector shell integration (bash)
+# Posts command start/end events to the local agent.
+# Non-blocking; fails silently if agent is not running.
+
+__runtimeinspector_json_escape() {
+  # Properly escape a string for JSON: backslash, double quote, and control chars
+  local s="\$1"
+  s="\${s//\\\\/\\\\\\\\}"       # \\ -> \\\\
+  s="\${s//\\"/\\\\\\"}"         # " -> \\"
+  s="\${s//$'\\n'/\\\\n}"        # newline -> \\n
+  s="\${s//$'\\r'/\\\\r}"        # carriage return -> \\r
+  s="\${s//$'\\t'/\\\\t}"        # tab -> \\t
+  printf '%s' "\$s"
+}
+
+__runtimeinspector_post_event() {
+  local event_type="\$1"
+  local payload="\$2"
+  local _tty
+  _tty="$(tty 2>/dev/null || echo unknown)"
+  local _ts="\$(date +%s000)"
+  local _cwd
+  _cwd="\$(__runtimeinspector_json_escape "\$(pwd)")"
+  local _host
+  _host="\$(__runtimeinspector_json_escape "\${HOSTNAME}")"
+  local _user
+  _user="\$(__runtimeinspector_json_escape "\${USER}")"
+  local _json="{\\"type\\":\\"\${event_type}\\",\\"shellType\\":\\"bash\\",\\"tty\\":\\"\${_tty}\\",\\"shellPid\\":$$,\\"cwd\\":\\"\${_cwd}\\",\\"timestamp\\":\${_ts},\\"username\\":\\"\${_user}\\",\\"host\\":\\"\${_host}\\",\${payload}}"
+
+  if command -v curl >/dev/null 2>&1; then
+    curl -s -o /dev/null --max-time 0.15 -X POST \\
+      -H "Content-Type: application/json" \\
+      -d "\${_json}" \\
+      "${AGENT_URL}" 2>/dev/null &
+    disown 2>/dev/null
+  fi
+}
+
+# --- DEBUG trap: fires before each command ---
+__runtimeinspector_debug_trap() {
+  # Only capture top-level commands (not subshells, PROMPT_COMMAND, etc.)
+  if [[ -n "\${COMP_LINE:-}" ]]; then return; fi
+  if [[ "\${BASH_COMMAND}" == "\${PROMPT_COMMAND}" ]]; then return; fi
+  if [[ "\${BASH_COMMAND}" == __runtimeinspector_* ]]; then return; fi
+
+  __runtimeinspector_cmd_start="\$(date +%s000)"
+  local _safe_cmd
+  _safe_cmd="\$(__runtimeinspector_json_escape "\${BASH_COMMAND}")"
+  __runtimeinspector_post_event "command_start" "\\"command\\":\\"\${_safe_cmd}\\""
+}
+
+# --- PROMPT_COMMAND: fires after each command, before prompt ---
+__runtimeinspector_prompt_cmd() {
+  local _exit_code=\$?
+  if [[ -n "\${__runtimeinspector_cmd_start:-}" ]]; then
+    __runtimeinspector_post_event "command_end" "\\"exitCode\\":\${_exit_code}"
+    unset __runtimeinspector_cmd_start
+  fi
+}
+
+# Chain DEBUG trap (preserve existing)
+if [[ -z "\$(trap -p DEBUG)" ]] || ! trap -p DEBUG | grep -q __runtimeinspector; then
+  trap '__runtimeinspector_debug_trap; \${__runtimeinspector_prev_debug_trap:-:}' DEBUG
+fi
+
+# Chain PROMPT_COMMAND (preserve existing)
+if [[ -n "\${PROMPT_COMMAND}" ]]; then
+  PROMPT_COMMAND="__runtimeinspector_prompt_cmd;\${PROMPT_COMMAND}"
+else
+  PROMPT_COMMAND="__runtimeinspector_prompt_cmd"
+fi
+`;
+}
+
+/**
+ * The marker block that goes into rc files.
+ */
+export function rcBlock(shell = 'zsh') {
+  const cmd = `runtimeinspector init --shell ${shell}`;
+  return `# >>> runtimeinspector >>>
+eval "$(${cmd})"
+# <<< runtimeinspector <<<`;
+}
+
+export const RC_MARKER_START = '# >>> runtimeinspector >>>';
+export const RC_MARKER_END = '# <<< runtimeinspector <<<';

package/src/shell/setup.js

@@ -0,0 +1,85 @@
+// Shell setup — edits rc file to add RuntimeInspector integration.
+// Idempotent, creates backups, never deletes.
+
+import { readFileSync, writeFileSync, existsSync, copyFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { rcBlock, RC_MARKER_START } from './hooks.js';
+
+/**
+ * Detect the user's shell and return { shell, rcPath }.
+ */
+export function detectShell(overrideShell, overrideRc) {
+  const shell = overrideShell || (process.env.SHELL || '').split('/').pop() || 'zsh';
+  const home = process.env.HOME;
+
+  if (!home) {
+    throw new Error('Cannot determine HOME directory');
+  }
+
+  let rcPath;
+  if (overrideRc) {
+    rcPath = overrideRc;
+  } else if (shell === 'bash') {
+    // Prefer .bashrc; fall back to .bash_profile if .bashrc doesn't exist
+    const bashrc = join(home, '.bashrc');
+    const bashProfile = join(home, '.bash_profile');
+    if (existsSync(bashrc)) {
+      rcPath = bashrc;
+    } else if (existsSync(bashProfile)) {
+      rcPath = bashProfile;
+    } else {
+      rcPath = bashrc; // will create
+    }
+  } else {
+    rcPath = join(home, '.zshrc');
+  }
+
+  const SUPPORTED_SHELLS = new Set(['zsh', 'bash']);
+  const normalizedShell = SUPPORTED_SHELLS.has(shell) ? shell : null;
+  if (!normalizedShell) {
+    throw new Error(`Unsupported shell: "${shell}". RuntimeInspector supports zsh and bash.`);
+  }
+  return { shell: normalizedShell, rcPath };
+}
+
+/**
+ * Install the integration block into the rc file.
+ * Returns { status: 'installed' | 'already' | 'error', message: string }
+ */
+export function installRcBlock({ shell, rcPath, yes = false }) {
+  // Safety: canonicalize path to prevent traversal (e.g. /tmp/../../etc/...)
+  const resolvedPath = resolve(rcPath);
+  const home = process.env.HOME;
+  if (home && !resolvedPath.startsWith(resolve(home))) {
+    return { status: 'error', message: `Refusing to edit file outside HOME: ${resolvedPath}` };
+  }
+  rcPath = resolvedPath;
+
+  // Read existing content (or empty if file doesn't exist)
+  let existing = '';
+  if (existsSync(rcPath)) {
+    existing = readFileSync(rcPath, 'utf-8');
+  }
+
+  // Check if block already present
+  if (existing.includes(RC_MARKER_START)) {
+    return { status: 'already', message: `RuntimeInspector integration already installed in ${rcPath}` };
+  }
+
+  // Create backup
+  if (existsSync(rcPath)) {
+    const timestamp = Date.now();
+    const backupPath = `${rcPath}.runtimeinspector.bak.${timestamp}`;
+    copyFileSync(rcPath, backupPath);
+  }
+
+  // Append block
+  const block = rcBlock(shell);
+  const newContent = existing.trimEnd() + '\n\n' + block + '\n';
+  writeFileSync(rcPath, newContent, 'utf-8');
+
+  return {
+    status: 'installed',
+    message: `RuntimeInspector integration installed in ${rcPath}`,
+  };
+}

package/src/wrapper/buffer.js

@@ -0,0 +1,34 @@
+// Ring buffer for captured output lines
+
+export class OutputBuffer {
+  constructor(maxLines = 300) {
+    this.maxLines = maxLines;
+    this.lines = [];
+  }
+
+  push(text, stream = 'stdout') {
+    const timestamp = new Date().toISOString();
+    const parts = text.toString().split('\n');
+    // Last element after split on trailing newline is empty — skip it
+    for (const part of parts) {
+      if (part === '' && parts.indexOf(part) === parts.length - 1) continue;
+      this.lines.push({ text: part, stream, timestamp });
+    }
+    // Trim to max
+    if (this.lines.length > this.maxLines) {
+      this.lines = this.lines.slice(this.lines.length - this.maxLines);
+    }
+  }
+
+  getRecent(n = 20) {
+    return this.lines.slice(-n);
+  }
+
+  get length() {
+    return this.lines.length;
+  }
+
+  toJSON() {
+    return this.lines;
+  }
+}

package/src/wrapper/runner.js

@@ -0,0 +1,149 @@
+// Wrapper runner — spawns a child process, captures output, reports to agent
+
+import { spawn, execFile } from 'node:child_process';
+import { request } from 'node:http';
+import { promisify } from 'node:util';
+import { OutputBuffer } from './buffer.js';
+
+const execFileAsync = promisify(execFile);
+
+const AGENT_URL = 'http://localhost:7331/api/wrapper/report';
+const REPORT_INTERVAL = 2000;
+
+function inferState(child, buffer, startedAt, cpuPercent) {
+  if (child.exitCode !== null) {
+    return child.exitCode === 0 ? 'done' : 'failed';
+  }
+
+  const now = Date.now();
+  const age = now - startedAt;
+  const lastLine = buffer.lines[buffer.lines.length - 1];
+  const lastOutputAge = lastLine ? now - new Date(lastLine.timestamp).getTime() : age;
+
+  if (age < 5000) return 'starting';
+  if (lastOutputAge < 10000) return 'progressing';
+  if (lastOutputAge > 60000 && cpuPercent > 5) return 'stuck';
+  if (lastOutputAge > 30000 && cpuPercent < 1) return 'idle';
+  if (cpuPercent > 1) return 'working';
+  return 'progressing';
+}
+
+function sendReport(payload) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify(payload);
+    const url = new URL(AGENT_URL);
+    const req = request(
+      {
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body),
+        },
+        timeout: 2000,
+      },
+      (res) => {
+        res.resume();
+        resolve(true);
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.end(body);
+  });
+}
+
+// Simple CPU % via ps for a single PID (async, non-blocking)
+async function readCpu(pid) {
+  try {
+    const { stdout } = await execFileAsync(
+      'ps', ['-o', '%cpu=', '-p', String(pid)],
+      { encoding: 'utf-8', timeout: 1000 }
+    );
+    return parseFloat(stdout.trim()) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+export async function runWrapped(cmdArgs) {
+  if (!cmdArgs || cmdArgs.length === 0) {
+    console.error('Usage: runtime-inspector run -- <command> [args...]');
+    process.exit(1);
+  }
+
+  const [cmd, ...args] = cmdArgs;
+  const buffer = new OutputBuffer(300);
+  const startedAt = Date.now();
+  let lastOutputAt = null;
+  let exitCode = null;
+  let cpuPercent = 0;
+
+  const child = spawn(cmd, args, {
+    stdio: ['inherit', 'pipe', 'pipe'],
+    env: { ...process.env, FORCE_COLOR: '1' },
+  });
+
+  child.stdout.on('data', (chunk) => {
+    process.stdout.write(chunk);
+    buffer.push(chunk.toString(), 'stdout');
+    lastOutputAt = new Date().toISOString();
+  });
+
+  child.stderr.on('data', (chunk) => {
+    process.stderr.write(chunk);
+    buffer.push(chunk.toString(), 'stderr');
+    lastOutputAt = new Date().toISOString();
+  });
+
+  // Report loop
+  const reportTimer = setInterval(async () => {
+    cpuPercent = await readCpu(child.pid);
+    const state = inferState(child, buffer, startedAt, cpuPercent);
+    await sendReport({
+      pid: child.pid,
+      cmd: [cmd, ...args].join(' '),
+      state,
+      recentOutput: buffer.getRecent(30),
+      lastOutputAt,
+      startedAt: new Date(startedAt).toISOString(),
+      exitCode,
+      lineCount: buffer.length,
+    });
+  }, REPORT_INTERVAL);
+
+  // Forward signals to child
+  const forwardSignal = (sig) => {
+    try { child.kill(sig); } catch {}
+  };
+  process.on('SIGINT', () => forwardSignal('SIGINT'));
+  process.on('SIGTERM', () => forwardSignal('SIGTERM'));
+
+  child.on('error', (err) => {
+    console.error(`Failed to start command: ${err.message}`);
+    clearInterval(reportTimer);
+    process.exit(1);
+  });
+
+  child.on('close', async (code) => {
+    exitCode = code;
+    clearInterval(reportTimer);
+
+    // Send final report
+    const state = code === 0 ? 'done' : 'failed';
+    await sendReport({
+      pid: child.pid,
+      cmd: [cmd, ...args].join(' '),
+      state,
+      recentOutput: buffer.getRecent(30),
+      lastOutputAt,
+      startedAt: new Date(startedAt).toISOString(),
+      exitCode: code,
+      lineCount: buffer.length,
+    });
+
+    process.exit(code ?? 1);
+  });
+}