agent-tool-forge 0.3.0

package/lib/dep-check.js

@@ -0,0 +1,99 @@
+/**
+ * Dependency Checker — shared utility for checking and optionally
+ * installing npm dependencies at runtime.
+ *
+ * Used by:
+ *   - forge-service.js (non-interactive: requireDependency)
+ *   - init.js          (interactive: ensureDependencyInteractive)
+ */
+
+import { execFileSync } from 'child_process';
+
+/**
+ * Check whether an npm package is available via dynamic import.
+ *
+ * @param {string} packageName
+ * @returns {Promise<{ available: boolean, error?: string }>}
+ */
+export async function checkDependency(packageName) {
+  try {
+    await import(packageName);
+    return { available: true };
+  } catch (err) {
+    const notInstalled = err.code === 'MODULE_NOT_FOUND' ||
+      err.message?.includes('Cannot find package') ||
+      err.message?.includes('Does the file exist?') ||
+      err.message?.includes('Failed to load url');
+    return {
+      available: false,
+      error: err.message,
+      likelyCause: notInstalled ? 'not_installed' : 'broken_package'
+    };
+  }
+}
+
+/**
+ * Return a human-readable install hint for a missing package.
+ *
+ * @param {string} packageName
+ * @returns {string}
+ */
+function installHint(packageName) {
+  return `npm install ${packageName}`;
+}
+
+/**
+ * Non-interactive dependency check. Throws with a helpful message
+ * if the package is not available. Used at sidecar startup where
+ * there is no readline interface.
+ *
+ * @param {string} packageName
+ * @returns {Promise<void>}
+ */
+export async function requireDependency(packageName) {
+  const result = await checkDependency(packageName);
+  if (!result.available) {
+    if (result.likelyCause === 'broken_package') {
+      throw new Error(
+        `Package "${packageName}" is installed but failed to load: ${result.error}\nThis may be a native addon compilation issue. Try: npm rebuild ${packageName}`
+      );
+    }
+    throw new Error(
+      `Required package "${packageName}" is not installed. Run: ${installHint(packageName)}`
+    );
+  }
+}
+
+/**
+ * Interactive dependency check — prompts the user to install if missing.
+ *
+ * @param {string} packageName
+ * @param {import('readline').Interface} rl
+ * @returns {Promise<boolean>} true if the package is available after check/install
+ */
+export async function ensureDependencyInteractive(packageName, rl) {
+  const { available } = await checkDependency(packageName);
+  if (available) return true;
+
+  const answer = await new Promise((resolve) => {
+    rl.question(
+      `Package "${packageName}" is not installed. Install it now? (y/n): `,
+      (ans) => resolve(ans.trim().toLowerCase())
+    );
+  });
+
+  if (answer !== 'y' && answer !== 'yes') {
+    return false;
+  }
+
+  try {
+    execFileSync('npm', ['install', packageName], { stdio: 'pipe', timeout: 30000 });
+    // Verify it's actually available now
+    const recheck = await checkDependency(packageName);
+    return recheck.available;
+  } catch (err) {
+    const detail = err.stderr?.toString().trim() || err.message;
+    console.error(`  ✗ Failed to install ${packageName}: ${detail}`);
+    return false;
+  }
+}

package/lib/drift-background.js

@@ -0,0 +1,61 @@
+/**
+ * Background Drift Monitor — periodically checks all promoted tools for drift.
+ *
+ * Reuses checkDrift() and computeSuspects() from cli/drift-monitor.js.
+ * Started in forge-service.js when --mode=sidecar.
+ */
+
+import { getAllToolRegistry, insertDriftAlert } from './db.js';
+import { checkDrift, computeSuspects } from './drift-monitor.js';
+
+const DEFAULT_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Create a background drift monitor.
+ *
+ * @param {object} config — forge config (drift.threshold, drift.windowSize)
+ * @param {import('better-sqlite3').Database} db
+ * @param {number} [intervalMs] — check interval (default 5 min)
+ * @returns {{ start(): void, stop(): void, runOnce(): void }}
+ */
+export function createDriftMonitor(config, db, intervalMs = DEFAULT_INTERVAL_MS) {
+  let timer = null;
+  const threshold = config.drift?.threshold ?? 0.1;
+  const windowSize = config.drift?.windowSize ?? 5;
+
+  function runOnce() {
+    try {
+      const tools = getAllToolRegistry(db).filter(r => r.lifecycle_state === 'promoted');
+      for (const tool of tools) {
+        const drift = checkDrift(db, tool.tool_name, threshold, windowSize);
+        if (drift.drifted) {
+          const suspects = computeSuspects(db, tool.tool_name);
+          insertDriftAlert(db, {
+            tool_name: tool.tool_name,
+            trigger_tools: suspects.map(s => s.tool_name).join(','),
+            baseline_rate: drift.baseline,
+            current_rate: drift.current,
+            delta: drift.delta
+          });
+        }
+      }
+    } catch (err) {
+      process.stderr.write(`[drift-monitor] Error during check: ${err.message}\n`);
+    }
+  }
+
+  return {
+    start() {
+      if (timer) return;
+      timer = setInterval(runOnce, intervalMs);
+      timer.unref(); // Don't block process exit
+    },
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+    runOnce
+  };
+}

package/lib/drift-monitor.js

@@ -0,0 +1,187 @@
+/**
+ * Drift Monitor — synchronous drift detection and suspect computation.
+ *
+ * Pure synchronous module. All SQL via direct db.prepare() calls.
+ * No imports from db.js — avoids circular dep risk, consistent with codebase.
+ */
+
+// ── Rolling average ────────────────────────────────────────────────────────
+
+/**
+ * Compute the rolling average pass_rate for a tool over the last N runs.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} toolName
+ * @param {number} [windowSize=5]
+ * @returns {number|null} Average pass_rate, or null if no runs found
+ */
+export function computeRollingAverage(db, toolName, windowSize = 5) {
+  let rows;
+  try {
+    rows = db.prepare(`
+      SELECT pass_rate FROM eval_runs
+      WHERE tool_name = ? AND pass_rate IS NOT NULL AND total_cases > 0
+      ORDER BY run_at DESC
+      LIMIT ?
+    `).all(toolName, windowSize);
+  } catch (_) {
+    return null;
+  }
+
+  if (!rows || rows.length === 0) return null;
+  const sum = rows.reduce((acc, r) => acc + (r.pass_rate || 0), 0);
+  return sum / rows.length;
+}
+
+// ── Suspect computation ────────────────────────────────────────────────────
+
+/**
+ * Find tools promoted between the last clean run and the flagged_at timestamp.
+ * These tools are suspected of causing drift via description/trigger overlap.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} toolName
+ * @returns {string[]} List of suspected tool names
+ */
+export function computeSuspects(db, toolName) {
+  let registryRow;
+  try {
+    registryRow = db.prepare(`SELECT flagged_at, baseline_pass_rate FROM tool_registry WHERE tool_name = ?`).get(toolName);
+  } catch (_) {
+    return [];
+  }
+
+  if (!registryRow || !registryRow.flagged_at) return [];
+
+  // Find the last run where pass_rate >= baseline (last clean run)
+  let lastCleanRun;
+  try {
+    lastCleanRun = db.prepare(`
+      SELECT run_at FROM eval_runs
+      WHERE tool_name = ?
+        AND pass_rate IS NOT NULL
+        AND pass_rate >= ?
+      ORDER BY run_at DESC
+      LIMIT 1
+    `).get(toolName, registryRow.baseline_pass_rate ?? 0.8);
+  } catch (_) {
+    return [];
+  }
+
+  const cleanAt = lastCleanRun?.run_at;
+  const flaggedAt = registryRow.flagged_at;
+
+  // Tools promoted between last clean run and flagged_at
+  try {
+    const rows = db.prepare(`
+      SELECT tool_name FROM tool_registry
+      WHERE tool_name != ?
+        AND promoted_at IS NOT NULL
+        AND promoted_at > ?
+        AND promoted_at <= ?
+    `).all(toolName, cleanAt || '1970-01-01', flaggedAt);
+    return rows.map((r) => r.tool_name);
+  } catch (_) {
+    return [];
+  }
+}
+
+// ── Drift check ────────────────────────────────────────────────────────────
+
+/**
+ * Check if a tool is drifting. If drift is detected and no open alert exists,
+ * inserts a drift_alert and marks the tool as 'flagged' in tool_registry.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} toolName
+ * @param {number} [threshold=0.1] - Minimum pass_rate drop to flag as drift
+ * @param {number} [windowSize=5]
+ * @returns {{ drifting: boolean, delta: number, suspects: string[], currentRate: number|null }}
+ */
+export function checkDrift(db, toolName, threshold = 0.1, windowSize = 5) {
+  // Get baseline from tool_registry
+  let baseline = null;
+  try {
+    const reg = db.prepare(`SELECT baseline_pass_rate, lifecycle_state FROM tool_registry WHERE tool_name = ?`).get(toolName);
+    if (reg) baseline = reg.baseline_pass_rate;
+  } catch (_) { /* non-fatal */ }
+
+  const currentRate = computeRollingAverage(db, toolName, windowSize);
+
+  if (baseline == null || currentRate == null) {
+    return { drifting: false, delta: 0, suspects: [], currentRate };
+  }
+
+  const delta = baseline - currentRate;
+  const drifting = delta >= threshold;
+
+  if (!drifting) {
+    return { drifting: false, delta, suspects: [], currentRate };
+  }
+
+  // Check if open alert already exists
+  let openAlert = null;
+  try {
+    openAlert = db.prepare(`SELECT id FROM drift_alerts WHERE tool_name = ? AND status = 'open'`).get(toolName);
+  } catch (_) { /* non-fatal */ }
+
+  const suspects = computeSuspects(db, toolName);
+
+  if (!openAlert) {
+    // Insert drift alert + flag the tool atomically — partial writes corrupt drift triangulation
+    const now = new Date().toISOString();
+    try {
+      db.transaction(() => {
+        db.prepare(`
+          INSERT INTO drift_alerts (tool_name, detected_at, trigger_tools, baseline_rate, current_rate, delta, status)
+          VALUES (?, ?, ?, ?, ?, ?, 'open')
+        `).run(toolName, now, JSON.stringify(suspects), baseline, currentRate, delta);
+
+        db.prepare(`
+          UPDATE tool_registry SET lifecycle_state = 'flagged', flagged_at = ?
+          WHERE tool_name = ? AND lifecycle_state != 'flagged'
+        `).run(now, toolName);
+      })();
+    } catch (_) { /* non-fatal */ }
+  }
+
+  return { drifting: true, delta, suspects, currentRate };
+}
+
+// ── Drift resolution ───────────────────────────────────────────────────────
+
+/**
+ * Resolve a drift situation: close the alert, retire the old tool, promote the replacement.
+ * All changes run in a transaction for atomicity.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {number} alertId - The drift_alerts.id to resolve
+ * @param {string} replacementToolName - The new tool name to promote
+ */
+export function resolveDrift(db, alertId, replacementToolName) {
+  const now = new Date().toISOString();
+
+  db.transaction(() => {
+    // Get alert to find the flagged tool
+    const alert = db.prepare(`SELECT tool_name FROM drift_alerts WHERE id = ?`).get(alertId);
+    if (!alert) return;
+
+    const oldToolName = alert.tool_name;
+
+    // Resolve the alert
+    db.prepare(`UPDATE drift_alerts SET status = 'resolved', resolved_at = ? WHERE id = ?`)
+      .run(now, alertId);
+
+    // Retire the old tool
+    db.prepare(`
+      UPDATE tool_registry SET lifecycle_state = 'retired', retired_at = ?, replaced_by = ?
+      WHERE tool_name = ?
+    `).run(now, replacementToolName, oldToolName);
+
+    // Promote the replacement
+    db.prepare(`
+      UPDATE tool_registry SET lifecycle_state = 'promoted', promoted_at = ?
+      WHERE tool_name = ?
+    `).run(now, replacementToolName);
+  })();
+}