@howlil/ez-agents 3.4.2 → 4.0.0

package/bin/lib/cost-tracker.cjs

@@ -0,0 +1,275 @@
+'use strict';
+/**
+ * EZ Cost Tracker — Token usage and USD cost recording with budget enforcement
+ * Persists entries to .planning/metrics.json using file-lock for concurrent safety.
+ * Usage:
+ *   const CostTracker = require('./cost-tracker.cjs');
+ *   const ct = new CostTracker(cwd);
+ *   await ct.record({ phase: 30, provider: 'claude', model: 'claude-sonnet-4-6', input_tokens: 1000, output_tokens: 500 });
+ *   const report = ct.aggregate();
+ *   const budget = ct.checkBudget();
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { withLock } = require('./file-lock.cjs');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+const CostAlerts = require('./cost-alerts.cjs');
+
+/**
+ * Returns default cost configuration with model rates.
+ */
+function defaultCostConfig() {
+  return {
+    enabled: true,
+    budget: null,
+    warning_threshold: 80,
+    auto_pause: false,
+    rates: {
+      'claude-3':          { input: 0.003, output: 0.015 },
+      'claude-sonnet-4-6': { input: 0.003, output: 0.015 },
+      'gpt-4':             { input: 0.03,  output: 0.06  },
+      'qwen':              { input: 0.002, output: 0.006 },
+      'kimi':              { input: 0.002, output: 0.006 },
+    },
+  };
+}
+
+/**
+ * Read cost_tracking section from .planning/config.json.
+ * Falls back to defaultCostConfig() when absent or unreadable.
+ * @param {string} cwd
+ * @returns {object}
+ */
+function readCostConfig(cwd) {
+  const configPath = path.join(cwd, '.planning', 'config.json');
+  if (!fs.existsSync(configPath)) return defaultCostConfig();
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return Object.assign(defaultCostConfig(), raw.cost_tracking || {});
+  } catch (e) {
+    return defaultCostConfig();
+  }
+}
+
+class CostTracker {
+  /**
+   * @param {string} [cwd] - Working directory (defaults to process.cwd())
+   */
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.metricsPath = path.join(this.cwd, '.planning', 'metrics.json');
+  }
+
+  /**
+   * Returns the cost_tracking config merged with defaults.
+   * @returns {object}
+   */
+  getConfig() {
+    return readCostConfig(this.cwd);
+  }
+
+  /**
+   * Record a cost entry to metrics.json atomically (via file-lock).
+   * If cost_usd is not supplied, it is computed from token counts and model rates.
+   * @param {object} entry
+   * @param {string} [entry.agent] - Agent name for per-agent tracking (e.g., 'ez-planner', 'ez-executor')
+   * @returns {Promise<void>}
+   */
+  async record(entry) {
+    // Ensure .planning directory exists before locking
+    const planningDir = path.join(this.cwd, '.planning');
+    if (!fs.existsSync(planningDir)) {
+      fs.mkdirSync(planningDir, { recursive: true });
+    }
+
+    await withLock(this.metricsPath, async () => {
+      // Read existing data or initialise empty structure
+      let data = { version: '1.0', entries: [] };
+      if (fs.existsSync(this.metricsPath)) {
+        try {
+          data = JSON.parse(fs.readFileSync(this.metricsPath, 'utf8'));
+          if (!Array.isArray(data.entries)) data.entries = [];
+        } catch (e) {
+          logger.warn('cost-tracker: failed to parse metrics.json, reinitialising', { error: e.message });
+          data = { version: '1.0', entries: [] };
+        }
+      }
+
+      // Compute cost_usd if not provided
+      let cost_usd = entry.cost_usd;
+      if (cost_usd === undefined || cost_usd === null) {
+        const cfg = readCostConfig(this.cwd);
+        const rates = cfg.rates || {};
+        const modelKey = entry.model;
+        const providerKey = entry.provider;
+        const rate = rates[modelKey] || rates[providerKey] || null;
+        if (rate) {
+          const inputTokens = entry.input_tokens || 0;
+          const outputTokens = entry.output_tokens || 0;
+          cost_usd = (inputTokens * rate.input + outputTokens * rate.output) / 1000;
+        } else {
+          cost_usd = 0;
+        }
+      }
+
+      const fullEntry = Object.assign({}, entry, {
+        timestamp: new Date().toISOString(),
+        cost_usd,
+      });
+
+      data.entries.push(fullEntry);
+      fs.writeFileSync(this.metricsPath, JSON.stringify(data, null, 2), 'utf8');
+    });
+  }
+
+  /**
+   * Aggregate cost entries, optionally filtered.
+   * @param {object} [filter] - Optional { phase?, milestone?, provider?, by_agent? }
+   * @param {boolean} [filter.by_agent] - If true, group by agent field and return nested breakdown
+   * @returns {{ total: { cost: number, tokens: number }, by_phase: object, by_provider: object, by_agent?: object }}
+   */
+  aggregate(filter = {}) {
+    const emptyResult = () => ({ total: { cost: 0, tokens: 0 }, by_phase: {}, by_provider: {} });
+    
+    if (!fs.existsSync(this.metricsPath)) return emptyResult();
+
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(this.metricsPath, 'utf8'));
+    } catch (e) {
+      return emptyResult();
+    }
+
+    let entries = data.entries || [];
+
+    if (filter.phase !== undefined) entries = entries.filter(e => e.phase == filter.phase);
+    if (filter.milestone)          entries = entries.filter(e => e.milestone === filter.milestone);
+    if (filter.provider)           entries = entries.filter(e => e.provider === filter.provider);
+
+    const result = { total: { cost: 0, tokens: 0 }, by_phase: {}, by_provider: {} };
+
+    for (const e of entries) {
+      const phaseKey = String(e.phase || 'unknown');
+      if (!result.by_phase[phaseKey]) result.by_phase[phaseKey] = { cost: 0, tokens: 0 };
+      result.by_phase[phaseKey].cost   += e.cost_usd || 0;
+      result.by_phase[phaseKey].tokens += (e.input_tokens || 0) + (e.output_tokens || 0);
+
+      const provKey = e.provider || 'unknown';
+      if (!result.by_provider[provKey]) result.by_provider[provKey] = { cost: 0 };
+      result.by_provider[provKey].cost += e.cost_usd || 0;
+
+      result.total.cost   += e.cost_usd || 0;
+      result.total.tokens += (e.input_tokens || 0) + (e.output_tokens || 0);
+    }
+
+    // Add by_agent breakdown if requested
+    if (filter.by_agent) {
+      result.by_agent = {};
+      for (const e of entries) {
+        const agentKey = e.agent || 'unknown';
+        if (!result.by_agent[agentKey]) result.by_agent[agentKey] = { cost: 0, tokens: 0 };
+        result.by_agent[agentKey].cost += e.cost_usd || 0;
+        result.by_agent[agentKey].tokens += (e.input_tokens || 0) + (e.output_tokens || 0);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Check total spending against a budget ceiling.
+   * Does NOT call process.exit() — caller decides how to react.
+   * Triggers multi-threshold alerts when thresholds are crossed.
+   * @param {object} [opts] - { ceiling?, warning_threshold? }
+   * @returns {{ status: 'ok'|'warning'|'exceeded', message: string, total?: number, ceiling?: number, percentUsed?: number, alerts?: Array }}
+   */
+  async checkBudget(opts = {}) {
+    const cfg = this.getConfig();
+    const ceiling = (opts.ceiling !== undefined) ? opts.ceiling : cfg.budget;
+    const warning_threshold = (opts.warning_threshold !== undefined) ? opts.warning_threshold : cfg.warning_threshold;
+
+    const agg = this.aggregate();
+    const total = agg.total.cost;
+
+    if (ceiling === null || ceiling === undefined || typeof ceiling !== 'number') {
+      return { status: 'ok', message: 'No budget set' };
+    }
+
+    const percentUsed = (total / ceiling) * 100;
+    const alerts = new CostAlerts(this.cwd).checkThresholds({ percentUsed, totalSpent: total, budget: ceiling });
+
+    // Log triggered alerts
+    if (alerts.length > 0) {
+      const costAlerts = new CostAlerts(this.cwd);
+      for (const alert of alerts) {
+        await costAlerts.logAlert(alert);
+      }
+    }
+
+    if (total >= ceiling) {
+      return {
+        status: 'exceeded',
+        message: `Budget ceiling $${ceiling} exceeded ($${total.toFixed(4)} spent)`,
+        total,
+        ceiling,
+        percentUsed,
+        alerts
+      };
+    }
+
+    if (percentUsed >= warning_threshold) {
+      return {
+        status: 'warning',
+        message: `${percentUsed.toFixed(1)}% of budget used`,
+        total,
+        ceiling,
+        percentUsed,
+        alerts
+      };
+    }
+
+    return {
+      status: 'ok',
+      message: 'Within budget',
+      total,
+      ceiling,
+      percentUsed,
+      alerts
+    };
+  }
+
+  /**
+   * Persist a budget ceiling (and optional warning threshold) to .planning/config.json.
+   * @param {number} ceiling
+   * @param {number} [warningThreshold]
+   */
+  setBudget(ceiling, warningThreshold) {
+    const configPath = path.join(this.cwd, '.planning', 'config.json');
+    const planningDir = path.join(this.cwd, '.planning');
+
+    if (!fs.existsSync(planningDir)) {
+      fs.mkdirSync(planningDir, { recursive: true });
+    }
+
+    let config = {};
+    if (fs.existsSync(configPath)) {
+      try {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      } catch (e) {
+        config = {};
+      }
+    }
+
+    if (!config.cost_tracking) config.cost_tracking = {};
+    config.cost_tracking.budget = ceiling;
+    if (warningThreshold !== undefined) {
+      config.cost_tracking.warning_threshold = warningThreshold;
+    }
+
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+  }
+}
+
+module.exports = CostTracker;

package/bin/lib/crash-recovery.cjs

@@ -0,0 +1,220 @@
+'use strict';
+
+/**
+ * EZ Crash Recovery — PID-stamped lock file management
+ * Detects orphaned operations and enables safe concurrent execution gates.
+ * Usage:
+ *   const CrashRecovery = require('./crash-recovery.cjs');
+ *   const cr = new CrashRecovery(cwd);
+ *   cr.acquire('phase-30-plan');
+ *   // ... later ...
+ *   cr.release('phase-30-plan');
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+const HEARTBEAT_INTERVAL_MS = 10000;
+const STALE_HEARTBEAT_MS = 60000;
+
+/**
+ * Check if a process is alive by sending signal 0.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isProcessAlive(pid) {
+  try {
+    process.kill(Number(pid), 0);
+    return true;
+  } catch (e) {
+    if (e.code === 'ESRCH') return false; // No such process
+    if (e.code === 'EPERM') return true;  // Process exists, no permission
+    return false;
+  }
+}
+
+class CrashRecovery {
+  /**
+   * @param {string} cwd - Root directory containing .planning/
+   */
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.locksDir = path.join(this.cwd, '.planning', 'locks');
+    this._intervals = {};
+    this._exitHandlers = {};
+  }
+
+  /**
+   * Sanitize an operation name to be a safe file name component.
+   * @param {string} operation
+   * @returns {string}
+   */
+  slugifyOperation(operation) {
+    return String(operation).replace(/[^a-zA-Z0-9-_]/g, '_');
+  }
+
+  /**
+   * Return the full path to the lock file for an operation.
+   * @param {string} operation
+   * @returns {string}
+   */
+  getLockPath(operation) {
+    return path.join(this.locksDir, this.slugifyOperation(operation) + '.lock.json');
+  }
+
+  /**
+   * Acquire a lock for the given operation.
+   * Creates a PID-stamped JSON lock file and starts a heartbeat interval.
+   * @param {string} operation
+   */
+  acquire(operation) {
+    if (!fs.existsSync(this.locksDir)) {
+      fs.mkdirSync(this.locksDir, { recursive: true });
+    }
+
+    const lockPath = this.getLockPath(operation);
+    const now = new Date().toISOString();
+    const data = { pid: process.pid, started: now, heartbeat: now, operation };
+    fs.writeFileSync(lockPath, JSON.stringify(data, null, 2), 'utf8');
+    logger.debug('Lock acquired: ' + operation);
+
+    // Heartbeat interval — keeps heartbeat timestamp fresh every 10s
+    const intervalId = setInterval(() => {
+      try {
+        if (fs.existsSync(lockPath)) {
+          const current = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+          current.heartbeat = new Date().toISOString();
+          fs.writeFileSync(lockPath, JSON.stringify(current, null, 2), 'utf8');
+        }
+      } catch (e) {
+        // Ignore heartbeat write errors (process may be exiting)
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+
+    // Allow process to exit naturally even with active interval
+    if (intervalId.unref) intervalId.unref();
+    this._intervals[operation] = intervalId;
+
+    // Release on process exit to avoid orphaned lock files
+    const exitHandler = () => this.release(operation);
+    this._exitHandlers[operation] = exitHandler;
+    process.on('exit', exitHandler);
+  }
+
+  /**
+   * Check whether a lock is orphaned (process is dead or heartbeat is stale).
+   * @param {string} operation
+   * @returns {boolean}
+   */
+  isOrphan(operation) {
+    const lockPath = this.getLockPath(operation);
+    if (!fs.existsSync(lockPath)) return false;
+
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    } catch (e) {
+      return true; // Corrupt lock file treated as orphan
+    }
+
+    if (!isProcessAlive(data.pid)) return true;
+
+    // Stale heartbeat check — lock is orphaned if heartbeat is too old
+    const heartbeatAge = Date.now() - new Date(data.heartbeat).getTime();
+    if (heartbeatAge > STALE_HEARTBEAT_MS) return true;
+
+    return false;
+  }
+
+  /**
+   * Release a lock for the given operation.
+   * Clears the heartbeat interval and removes the lock file.
+   * @param {string} operation
+   */
+  release(operation) {
+    if (this._intervals[operation]) {
+      clearInterval(this._intervals[operation]);
+      delete this._intervals[operation];
+    }
+
+    if (this._exitHandlers[operation]) {
+      process.off('exit', this._exitHandlers[operation]);
+      delete this._exitHandlers[operation];
+    }
+
+    const lockPath = this.getLockPath(operation);
+    if (fs.existsSync(lockPath)) {
+      try {
+        fs.unlinkSync(lockPath);
+      } catch (e) {
+        // Ignore unlink errors (file may already be removed)
+      }
+    }
+
+    logger.debug('Lock released: ' + operation);
+  }
+
+  /**
+   * Return a list of operation slugs whose lock files are orphaned.
+   * @returns {string[]}
+   */
+  listOrphans() {
+    if (!fs.existsSync(this.locksDir)) return [];
+    return fs.readdirSync(this.locksDir)
+      .filter(f => f.endsWith('.lock.json'))
+      .map(f => f.replace(/\.lock\.json$/, ''))
+      .filter(op => this.isOrphan(op));
+  }
+
+  /**
+   * Return a list of all active locks with their metadata.
+   * @returns {Array<{operation: string, pid: number, started: string, heartbeat: string}>}
+   */
+  listLocks() {
+    if (!fs.existsSync(this.locksDir)) return [];
+    return fs.readdirSync(this.locksDir)
+      .filter(f => f.endsWith('.lock.json'))
+      .map(f => {
+        const lockPath = path.join(this.locksDir, f);
+        try {
+          const data = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+          return {
+            operation: data.operation,
+            pid: data.pid,
+            started: data.started,
+            heartbeat: data.heartbeat
+          };
+        } catch (e) {
+          return null;
+        }
+      })
+      .filter(lock => lock !== null);
+  }
+
+  /**
+   * Get the status of a specific lock.
+   * @param {string} operation
+   * @returns {{locked: boolean, pid?: number, started?: string, heartbeat?: string}}
+   */
+  getLockStatus(operation) {
+    const lockPath = this.getLockPath(operation);
+    if (!fs.existsSync(lockPath)) {
+      return { locked: false };
+    }
+    try {
+      const data = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+      return {
+        locked: true,
+        pid: data.pid,
+        started: data.started,
+        heartbeat: data.heartbeat
+      };
+    } catch (e) {
+      return { locked: false };
+    }
+  }
+}
+
+module.exports = CrashRecovery;