agent-recon 1.0.1

package/server/start.js

@@ -0,0 +1,178 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Apache License, Version 2.0 — see LICENSE for terms.
+
+'use strict';
+/**
+ * Agent Recon — cross-platform startup wrapper
+ *
+ * Checks whether the better-sqlite3 native binary matches the current
+ * platform (Linux ELF, Win32 PE, or macOS Mach-O). If it doesn't,
+ * the wrong binary is renamed to a platform-tagged backup and
+ * `npm rebuild better-sqlite3` downloads the correct prebuilt binary.
+ *
+ * This means you never have to manually run npm rebuild when switching
+ * between a WSL terminal, Windows PowerShell/CMD, or macOS.
+ *
+ * Additionally migrates the SQLite database off NTFS/DrvFs on Linux/WSL
+ * (WAL mode requires mmap, which DrvFs does not support) and checks for
+ * YARA-X platform binary availability.
+ *
+ * Usage (from server/):
+ *   node start.js        — normal start (auto-fixes binary if needed)
+ *   npm start            — same (package.json "start" points here)
+ *
+ * @module start
+ */
+
+const { execSync } = require('child_process');
+const fs   = require('fs');
+const path = require('path');
+const platform = require('./platform');
+
+const BINARY = path.join(
+  __dirname,
+  'node_modules', 'better-sqlite3', 'build', 'Release', 'better_sqlite3.node'
+);
+
+/** Human-readable name for each binary type (used in log messages). */
+const BINARY_TYPE_NAMES = {
+  pe:               'Win32 PE',
+  elf:              'Linux ELF',
+  'macho-x64':      'Mach-O x64',
+  'macho-arm64':    'Mach-O arm64',
+  'macho-universal': 'Mach-O universal',
+  unknown:          'unknown',
+};
+
+/** Human-readable target platform name for log messages. */
+function targetPlatformName() {
+  const os = platform.detectOS();
+  switch (os) {
+    case 'windows': return 'Windows';
+    case 'macos':   return 'macOS';
+    case 'wsl':     return 'Linux (WSL)';
+    case 'linux':   return 'Linux';
+    default:        return os;
+  }
+}
+
+// ── Binary platform check ──────────────────────────────────────────────────
+// This solves the cross-platform scenario where node_modules is shared or
+// synced between environments (e.g. NTFS mounts visible from both Windows
+// and WSL, or a checkout copied between macOS and Linux). The native
+// better-sqlite3 .node addon compiled for one OS won't load on another,
+// so we detect the mismatch proactively and rebuild before server.js tries
+// to require() it.
+if (fs.existsSync(BINARY)) {
+  try {
+    // We only need 5 bytes: the first 4 are the file format magic number
+    // (MZ for PE, 7F ELF for ELF, CF FA ED FE for Mach-O). Byte 5 is the
+    // Mach-O cputype field, needed because both x64 and arm64 macOS use the
+    // same 4-byte little-endian magic (CF FA ED FE) — the cputype at offset 4
+    // distinguishes them (0x07 = CPU_TYPE_X86_64, 0x0C = CPU_TYPE_ARM64).
+    const hdr = fs.readFileSync(BINARY).slice(0, 5);
+
+    const binaryType = platform.detectBinaryType(hdr);
+
+    if (platform.needsRebuild(binaryType)) {
+      const fromDesc = BINARY_TYPE_NAMES[binaryType] || binaryType;
+      const toDesc   = targetPlatformName();
+      const backupExt = platform.backupSuffix(binaryType);
+
+      console.log(`\n[start] better-sqlite3: ${fromDesc} binary detected — rebuilding for ${toDesc}...`);
+
+      // renameSync instead of unlinkSync: on NTFS (Windows or DrvFs mounts),
+      // a loaded .node file has its handle held open by the process that
+      // loaded it. unlinkSync would fail with EBUSY because NTFS requires
+      // all handles to be closed before deletion. renameSync works because
+      // it only updates the directory entry — the file data remains accessible
+      // via the existing handle until the last reference is closed.
+      try {
+        fs.renameSync(BINARY, BINARY + backupExt);
+      } catch (_) {
+        // Rename failed (e.g. permissions) — try unlinking instead
+        try { fs.unlinkSync(BINARY); } catch (_) {}
+      }
+
+      execSync('npm rebuild better-sqlite3', {
+        cwd:     __dirname,
+        stdio:   'inherit',
+        timeout: 120_000,
+      });
+
+      console.log(`[start] Binary switched to ${toDesc}.\n`);
+    }
+  } catch (err) {
+    // Don't abort — let server.js surface a cleaner error if the binary
+    // is still wrong after this point.
+    console.warn(`[start] Binary check skipped: ${err.message}`);
+  }
+}
+
+// ── YARA-X binary availability check ──────────────────────────────────────
+{
+  const platformKey = `${process.platform}-${process.arch}`;
+  const YARA_PLATFORM_PKGS = {
+    'win32-x64':   '@litko/yara-x-win32-x64-msvc',
+    'linux-x64':   '@litko/yara-x-linux-x64-gnu',
+    'linux-arm64': '@litko/yara-x-linux-arm64-gnu',
+    'darwin-x64':  '@litko/yara-x-darwin-x64',
+    'darwin-arm64': '@litko/yara-x-darwin-arm64',
+  };
+  const expectedPkg = YARA_PLATFORM_PKGS[platformKey];
+  if (expectedPkg) {
+    let yaraResolved = false;
+    try { require.resolve(expectedPkg); yaraResolved = true; } catch (_) {}
+    if (!yaraResolved) {
+      console.warn(
+        `\n[start] YARA-X: missing platform binary for ${platformKey}.` +
+        `\n        Expected package: ${expectedPkg}` +
+        `\n        Install it: npm pack ${expectedPkg}@0.5.0 && ` +
+        `mkdir -p node_modules/${expectedPkg} && ` +
+        `tar -xzf *.tgz -C node_modules/${expectedPkg} --strip-components=1` +
+        `\n        (Security classification will use regex fallback until fixed.)\n`
+      );
+    }
+  }
+}
+
+// ── DB path: migrate off NTFS/DrvFs on Linux (WAL mode needs mmap) ────────
+if (process.platform !== 'win32' && !process.env.DB_PATH) {
+  const defaultDb = path.join(__dirname, '..', 'data', 'agent-recon.db');
+
+  if (platform.isNtfs(defaultDb)) {
+    const homeDb = path.join(
+      platform.homedir(),
+      '.agent-recon', 'agent-recon.db'
+    );
+    fs.mkdirSync(path.dirname(homeDb), { recursive: true });
+    // Use the ext4 copy if it exists and passes an integrity check.
+    // If it's missing or corrupt, copy fresh from NTFS (source of truth for hooks).
+    // WAL files are cleaned on copy to avoid opening a stale WAL.
+    let needsCopy = !fs.existsSync(homeDb);
+    if (!needsCopy) {
+      try {
+        const Database = require('better-sqlite3');
+        const testDb = new Database(homeDb, { readonly: true });
+        const ok = testDb.pragma('integrity_check', { simple: true });
+        testDb.close();
+        if (ok !== 'ok') { needsCopy = true; console.warn('[start] ext4 DB failed integrity check — replacing from NTFS'); }
+      } catch (_) { needsCopy = true; console.warn('[start] ext4 DB unreadable — replacing from NTFS'); }
+    }
+    if (needsCopy && fs.existsSync(defaultDb)) {
+      try {
+        console.log(`[start] Copying NTFS DB to ext4: ${homeDb}`);
+        fs.copyFileSync(defaultDb, homeDb);
+        try { fs.unlinkSync(homeDb + '-shm'); } catch (_) {}
+        try { fs.unlinkSync(homeDb + '-wal'); } catch (_) {}
+      } catch (e) {
+        console.warn(`[start] DB migration warning: ${e.message}`);
+      }
+    }
+    process.env.DB_PATH = homeDb;
+    console.log(`[start] Using ext4 DB path: ${homeDb}`);
+  }
+}
+
+// ── Start the server ───────────────────────────────────────────────────────
+require('./server');

package/service/agent-recon.service

@@ -0,0 +1,30 @@
+# Agent Recon — systemd user service
+# ─────────────────────────────────────────────────────────────────────────────
+# Installation (after running setup-linux.sh):
+#
+#   mkdir -p ~/.config/systemd/user
+#   cp agent-recon.service ~/.config/systemd/user/
+#   systemctl --user daemon-reload
+#   systemctl --user enable agent-recon
+#   systemctl --user start agent-recon
+#
+# Logs:
+#   journalctl --user -u agent-recon -f
+#
+# The {{INSTALL_DIR}} placeholder is replaced by setup-linux.sh during install.
+# ─────────────────────────────────────────────────────────────────────────────
+
+[Unit]
+Description=Agent Recon — Claude Code Observability Server
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/node {{INSTALL_DIR}}/server/start.js
+WorkingDirectory={{INSTALL_DIR}}/server
+Restart=on-failure
+RestartSec=5
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=default.target

package/service/com.agent-recon.server.plist

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Agent Recon — macOS launchd service
+  ====================================
+  Auto-starts the Agent Recon server on login and restarts on crash.
+
+  Install:
+    cp service/com.agent-recon.server.plist ~/Library/LaunchAgents/
+    # Edit the plist to replace {{INSTALL_DIR}} with your actual path, e.g.:
+    #   sed -i '' 's|{{INSTALL_DIR}}|/Users/you/agent-recon|g' \
+    #       ~/Library/LaunchAgents/com.agent-recon.server.plist
+    launchctl load ~/Library/LaunchAgents/com.agent-recon.server.plist
+
+  Uninstall:
+    launchctl unload ~/Library/LaunchAgents/com.agent-recon.server.plist
+    rm ~/Library/LaunchAgents/com.agent-recon.server.plist
+
+  View logs:
+    tail -f ~/Library/Logs/agent-recon.log
+    tail -f ~/Library/Logs/agent-recon.error.log
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.agent-recon.server</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>node</string>
+    <string>start.js</string>
+  </array>
+
+  <key>WorkingDirectory</key>
+  <string>{{INSTALL_DIR}}/server</string>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>StandardOutPath</key>
+  <string>{{HOME}}/Library/Logs/agent-recon.log</string>
+
+  <key>StandardErrorPath</key>
+  <string>{{HOME}}/Library/Logs/agent-recon.error.log</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+  </dict>
+</dict>
+</plist>

package/setup-linux.sh

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# Agent Recon — Native Linux Setup
+# Run this script on a native Linux machine (not WSL) to wire the Agent Recon
+# hooks into your Claude Code installation.
+#
+#   bash setup-linux.sh
+#
+# What it does:
+#   1. Creates ~/.claude/hooks/
+#   2. Copies (or updates) send-event.py there (with sha256 drift detection)
+#   3. Verifies python3 is available
+#   4. Tests connectivity to localhost:3131
+#   5. Writes (or merges) ~/.claude/settings.json with all 13 hook registrations
+#   6. Checks for libsecret credential backend (secret-tool)
+#   7. Optionally installs a systemd user service for auto-start
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HOOK_SRC="$SCRIPT_DIR/.claude/hooks/send-event.py"
+HOOK_DST="$HOME/.claude/hooks/send-event.py"
+SETTINGS="$HOME/.claude/settings.json"
+HOOK_CMD="python3 $HOOK_DST"
+SERVICE_SRC="$SCRIPT_DIR/service/agent-recon.service"
+
+# ── Validate ─────────────────────────────────────────────────────────────────
+if [[ ! -f "$HOOK_SRC" ]]; then
+  echo "ERROR: Cannot find hook source at $HOOK_SRC"
+  echo "  Run this script from the agent-recon project root directory."
+  exit 1
+fi
+
+if ! command -v python3 &>/dev/null; then
+  echo "ERROR: python3 not found. Install it with your package manager:"
+  echo "  Debian/Ubuntu : sudo apt install python3"
+  echo "  Fedora        : sudo dnf install python3"
+  echo "  Arch          : sudo pacman -S python"
+  exit 1
+fi
+
+echo "✓  python3 found: $(python3 --version 2>&1)"
+
+# ── Install / sync hook script ───────────────────────────────────────────────
+mkdir -p "$HOME/.claude/hooks"
+
+if [[ -f "$HOOK_DST" ]]; then
+  SRC_HASH=$(sha256sum "$HOOK_SRC" | cut -d' ' -f1)
+  DST_HASH=$(sha256sum "$HOOK_DST" | cut -d' ' -f1)
+  if [[ "$SRC_HASH" != "$DST_HASH" ]]; then
+    echo "↻  Hook script updated — syncing to $HOOK_DST"
+    cp "$HOOK_SRC" "$HOOK_DST"
+    chmod +x "$HOOK_DST"
+    echo "✓  Synced"
+  else
+    echo "✓  Hook script already up-to-date: $HOOK_DST"
+  fi
+else
+  cp "$HOOK_SRC" "$HOOK_DST"
+  chmod +x "$HOOK_DST"
+  echo "✓  Installed hook forwarder → $HOOK_DST"
+fi
+
+# ── Test Agent Recon server connectivity ─────────────────────────────────────
+echo ""
+echo "── Connectivity check ──────────────────────────────────────────────────"
+
+if curl -sf --max-time 2 "http://localhost:3131/health" > /dev/null 2>&1; then
+  echo "  ✓ localhost:3131  REACHABLE"
+else
+  echo "  ✗ localhost:3131  not reachable"
+  echo ""
+  echo "  ⚠  Agent Recon server is not running."
+  echo "     Start it with:"
+  echo "       cd $SCRIPT_DIR/server && node start.js"
+  echo "     Then re-run this script to verify connectivity."
+fi
+
+# ── Write settings.json ─────────────────────────────────────────────────────
+echo ""
+echo "── Hook registration ─────────────────────────────────────────────────"
+
+if [[ -f "$SETTINGS" ]]; then
+  # Merge hooks into existing settings.json using Python so we don't clobber
+  # other fields (e.g. skipDangerousModePermissionPrompt).
+  python3 - "$SETTINGS" "$HOOK_CMD" <<'PYEOF'
+import json, sys
+
+settings_path = sys.argv[1]
+hook_cmd      = sys.argv[2]
+
+with open(settings_path) as f:
+    cfg = json.load(f)
+
+hooks = cfg.setdefault("hooks", {})
+
+def hook_entry(matcher=False):
+    entry = {"type": "command", "command": hook_cmd, "async": True, "timeout": 10}
+    if matcher:
+        return {"matcher": "", "hooks": [entry]}
+    return {"hooks": [entry]}
+
+EVENTS_PLAIN   = ["SessionStart","SessionEnd","UserPromptSubmit",
+                  "SubagentStart","SubagentStop","Stop","TeammateIdle","TaskCompleted"]
+EVENTS_MATCHER = ["PreToolUse","PostToolUse","PostToolUseFailure","Notification","PreCompact"]
+
+def already_registered(event_hooks):
+    for group in event_hooks:
+        for h in group.get("hooks", []):
+            if h.get("command","") == hook_cmd:
+                return True
+    return False
+
+added = []
+for ev in EVENTS_PLAIN:
+    if ev not in hooks:
+        hooks[ev] = [hook_entry(False)]
+        added.append(ev)
+    elif not already_registered(hooks[ev]):
+        hooks[ev].append(hook_entry(False))
+        added.append(ev)
+
+for ev in EVENTS_MATCHER:
+    if ev not in hooks:
+        hooks[ev] = [hook_entry(True)]
+        added.append(ev)
+    elif not already_registered(hooks[ev]):
+        hooks[ev].append(hook_entry(True))
+        added.append(ev)
+
+with open(settings_path, "w") as f:
+    json.dump(cfg, f, indent=2)
+    f.write("\n")
+
+if added:
+    print("✓  Merged hooks into", settings_path)
+    print("   Added:", ", ".join(added))
+else:
+    print("✓  All hooks already present in", settings_path, "— nothing changed")
+PYEOF
+else
+  cat > "$SETTINGS" <<SETTINGSEOF
+{
+  "hooks": {
+    "SessionStart":        [{"hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "SessionEnd":          [{"hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "UserPromptSubmit":    [{"hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "PreToolUse":          [{"matcher": "","hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "PostToolUse":         [{"matcher": "","hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "PostToolUseFailure":  [{"matcher": "","hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "SubagentStart":       [{"hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "SubagentStop":        [{"hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "Stop":                [{"hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "Notification":        [{"matcher": "","hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "TeammateIdle":        [{"hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "TaskCompleted":       [{"hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}],
+    "PreCompact":          [{"matcher": "","hooks": [{"type": "command","command": "$HOOK_CMD","async": true,"timeout": 10}]}]
+  }
+}
+SETTINGSEOF
+  echo "✓  Created $SETTINGS"
+fi
+
+# ── Check libsecret credential backend ──────────────────────────────────────
+echo ""
+echo "── Credential backend check ──────────────────────────────────────────"
+
+if command -v secret-tool &>/dev/null; then
+  echo "  ✓ secret-tool found (libsecret credential backend available)"
+
+  # Test store/lookup/clear cycle
+  TEST_KEY="agent-recon-setup-test-$$"
+  SECRET_OK=true
+
+  if ! echo -n "test-value" | secret-tool store --label="Agent Recon test" agent-recon-key "$TEST_KEY" 2>/dev/null; then
+    SECRET_OK=false
+  fi
+
+  if $SECRET_OK; then
+    LOOKUP=$(secret-tool lookup agent-recon-key "$TEST_KEY" 2>/dev/null || true)
+    if [[ "$LOOKUP" == "test-value" ]]; then
+      echo "  ✓ secret-tool store/lookup cycle passed"
+    else
+      SECRET_OK=false
+    fi
+    # Clean up test entry
+    secret-tool clear agent-recon-key "$TEST_KEY" 2>/dev/null || true
+  fi
+
+  if ! $SECRET_OK; then
+    echo "  ⚠  secret-tool is installed but the test cycle failed."
+    echo "     This may happen if no keyring daemon is running (e.g. headless server)."
+    echo "     PBKDF2 fallback will be used for credential storage."
+  fi
+else
+  echo "  ⚠  secret-tool not found — PBKDF2 fallback will be used for credentials."
+  echo "     To install libsecret for native keyring support:"
+  echo "       Debian/Ubuntu : sudo apt install libsecret-tools"
+  echo "       Fedora        : sudo dnf install libsecret"
+  echo "       Arch          : sudo pacman -S libsecret"
+fi
+
+# ── Optional systemd user service ───────────────────────────────────────────
+echo ""
+echo "── Systemd user service ────────────────────────────────────────────────"
+
+if [[ ! -f "$SERVICE_SRC" ]]; then
+  echo "  ⚠  Service unit file not found at $SERVICE_SRC — skipping."
+else
+  echo "  A systemd user service can auto-start Agent Recon on login."
+  echo ""
+  read -r -p "  Install systemd user service? [y/N] " INSTALL_SERVICE
+  if [[ "${INSTALL_SERVICE,,}" == "y" ]]; then
+    SERVICE_DIR="$HOME/.config/systemd/user"
+    mkdir -p "$SERVICE_DIR"
+
+    # Replace {{INSTALL_DIR}} placeholder with the actual project path
+    sed "s|{{INSTALL_DIR}}|$SCRIPT_DIR|g" "$SERVICE_SRC" > "$SERVICE_DIR/agent-recon.service"
+
+    systemctl --user daemon-reload
+    systemctl --user enable agent-recon
+    echo "  ✓  Service installed and enabled."
+    echo ""
+    read -r -p "  Start the service now? [y/N] " START_NOW
+    if [[ "${START_NOW,,}" == "y" ]]; then
+      systemctl --user start agent-recon
+      echo "  ✓  Service started."
+      echo "     Check status: systemctl --user status agent-recon"
+      echo "     View logs   : journalctl --user -u agent-recon -f"
+    else
+      echo "  Service enabled but not started. Start it later with:"
+      echo "    systemctl --user start agent-recon"
+    fi
+  else
+    echo "  Skipped. You can install it manually later:"
+    echo "    mkdir -p ~/.config/systemd/user"
+    echo "    sed 's|{{INSTALL_DIR}}|$SCRIPT_DIR|g' $SERVICE_SRC > ~/.config/systemd/user/agent-recon.service"
+    echo "    systemctl --user daemon-reload"
+    echo "    systemctl --user enable agent-recon"
+    echo "    systemctl --user start agent-recon"
+  fi
+fi
+
+# ── Summary ──────────────────────────────────────────────────────────────────
+echo ""
+echo "────────────────────────────────────────────────────────────────────────"
+echo "  Linux setup complete!"
+echo ""
+echo "  Hook script : $HOOK_DST"
+echo "  Server URL  : http://localhost:3131"
+echo ""
+echo "  Start server: cd $SCRIPT_DIR/server && node start.js"
+echo "  (start.js auto-rebuilds the SQLite binary if platform mismatches)"
+echo ""
+echo "  Start a Claude session in any directory and events will stream"
+echo "  to http://localhost:3131"
+echo ""
+echo "  Debug mode  : AGENT_RECON_DEBUG=1 claude  →  ~/.claude/agent-recon-debug.log"
+echo "────────────────────────────────────────────────────────────────────────"