scene-capability-engine 3.0.0

package/lib/lock/task-lock-manager.js

@@ -0,0 +1,345 @@
+/**
+ * TaskLockManager - Task-level fine-grained lock manager
+ *
+ * Provides per-task locking instead of per-Spec locking, allowing multiple
+ * Agents to work on different tasks within the same Spec concurrently.
+ *
+ * Lock file path: `.kiro/specs/{specName}/locks/{taskId}.lock`
+ * (dots in taskId replaced with dashes for filesystem safety)
+ *
+ * In single-Agent mode, delegates to the existing LockManager (Spec-level lock).
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const fsUtils = require('../utils/fs-utils');
+const { MultiAgentConfig } = require('../collab/multi-agent-config');
+const { LockManager } = require('./lock-manager');
+const TaskClaimer = require('../task/task-claimer');
+
+class TaskLockManager {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   * @param {import('./machine-identifier').MachineIdentifier} machineIdentifier
+   */
+  constructor(workspaceRoot, machineIdentifier) {
+    this._workspaceRoot = workspaceRoot;
+    this._machineIdentifier = machineIdentifier;
+    this._specsDir = path.join(workspaceRoot, '.kiro', 'specs');
+    this._multiAgentConfig = new MultiAgentConfig(workspaceRoot);
+    this._lockManager = new LockManager(workspaceRoot, machineIdentifier);
+    this._taskClaimer = new TaskClaimer();
+  }
+
+  /**
+   * Convert a taskId to a filesystem-safe filename.
+   * Replaces dots with dashes (e.g. "2.1" → "2-1").
+   * @param {string} taskId
+   * @returns {string}
+   * @private
+   */
+  _safeTaskId(taskId) {
+    return taskId.replace(/\./g, '-');
+  }
+
+  /**
+   * Get the locks directory for a spec.
+   * @param {string} specName
+   * @returns {string}
+   * @private
+   */
+  _locksDir(specName) {
+    return path.join(this._specsDir, specName, 'locks');
+  }
+
+  /**
+   * Get the lock file path for a specific task.
+   * @param {string} specName
+   * @param {string} taskId
+   * @returns {string}
+   * @private
+   */
+  _lockFilePath(specName, taskId) {
+    return path.join(this._locksDir(specName), `${this._safeTaskId(taskId)}.lock`);
+  }
+
+  /**
+   * Check whether multi-Agent mode is enabled.
+   * @returns {Promise<boolean>}
+   */
+  async isMultiAgentMode() {
+    return this._multiAgentConfig.isEnabled();
+  }
+
+  /**
+   * Acquire a task-level lock.
+   *
+   * In multi-Agent mode: creates `.kiro/specs/{specName}/locks/{taskId}.lock`
+   * In single-Agent mode: delegates to LockManager.acquireLock(specName)
+   *
+   * @param {string} specName
+   * @param {string} taskId
+   * @param {string} agentId
+   * @param {object} [options={}]
+   * @param {string} [options.reason] - Reason for acquiring the lock
+   * @returns {Promise<{success: boolean, lock?: object, holder?: object, error?: string}>}
+   */
+  async acquireTaskLock(specName, taskId, agentId, options = {}) {
+    const multiAgent = await this.isMultiAgentMode();
+
+    if (!multiAgent) {
+      // Single-Agent mode: delegate to Spec-level lock
+      return this._lockManager.acquireLock(specName, { reason: options.reason });
+    }
+
+    const lockPath = this._lockFilePath(specName, taskId);
+
+    // Check for existing lock
+    const existing = await this._readLockFile(lockPath);
+    if (existing) {
+      if (existing.agentId === agentId) {
+        // Already held by this agent – refresh
+        const lock = await this._buildLockRecord(specName, taskId, agentId, options.reason);
+        await this._atomicWriteLock(lockPath, lock);
+        return { success: true, lock };
+      }
+      // Held by another agent (Req 2.2)
+      return { success: false, error: 'Task is already locked', holder: existing };
+    }
+
+    // Acquire new lock (Req 2.1)
+    const lock = await this._buildLockRecord(specName, taskId, agentId, options.reason);
+    await fsUtils.ensureDirectory(this._locksDir(specName));
+    await this._atomicWriteLock(lockPath, lock);
+
+    // Verify we actually got the lock (race-condition guard)
+    const verify = await this._readLockFile(lockPath);
+    if (verify && verify.agentId === agentId) {
+      // Integrate with TaskClaimer: claim the task atomically (Req 2.5)
+      const claimResult = await this._taskClaimer.claimTask(
+        this._workspaceRoot, specName, taskId, agentId, true
+      );
+      if (!claimResult.success) {
+        // Rollback: release the lock file since claim failed
+        try {
+          await fs.unlink(lockPath);
+        } catch (unlinkErr) {
+          if (unlinkErr.code !== 'ENOENT') throw unlinkErr;
+        }
+        return { success: false, error: `Lock acquired but claim failed: ${claimResult.error}` };
+      }
+      return { success: true, lock };
+    }
+
+    return { success: false, error: 'Task is already locked', holder: verify };
+  }
+
+  /**
+   * Release a task-level lock.
+   *
+   * In multi-Agent mode: deletes the lock file (Req 2.3)
+   * In single-Agent mode: delegates to LockManager.releaseLock(specName)
+   *
+   * @param {string} specName
+   * @param {string} taskId
+   * @param {string} agentId
+   * @returns {Promise<{success: boolean, error?: string}>}
+   */
+  async releaseTaskLock(specName, taskId, agentId) {
+    const multiAgent = await this.isMultiAgentMode();
+
+    if (!multiAgent) {
+      return this._lockManager.releaseLock(specName);
+    }
+
+    const lockPath = this._lockFilePath(specName, taskId);
+    const existing = await this._readLockFile(lockPath);
+
+    if (!existing) {
+      return { success: true }; // Nothing to release
+    }
+
+    if (existing.agentId !== agentId) {
+      return { success: false, error: 'Lock owned by different agent', holder: existing };
+    }
+
+    // Integrate with TaskClaimer: unclaim the task (best effort) (Req 2.5)
+    try {
+      await this._taskClaimer.unclaimTask(this._workspaceRoot, specName, taskId, agentId);
+    } catch (_unclaimErr) {
+      // Best effort – proceed with lock file deletion even if unclaim fails
+    }
+
+    try {
+      await fs.unlink(lockPath);
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    return { success: true };
+  }
+
+  /**
+   * Release all task locks held by a specific agent.
+   * Scans all spec directories for `locks/` subdirectories.
+   *
+   * @param {string} agentId
+   * @returns {Promise<{released: Array<{specName: string, taskId: string}>}>}
+   */
+  async releaseAllLocks(agentId) {
+    const released = [];
+
+    let specEntries;
+    try {
+      specEntries = await fs.readdir(this._specsDir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === 'ENOENT') return { released };
+      throw err;
+    }
+
+    for (const entry of specEntries) {
+      if (!entry.isDirectory()) continue;
+
+      const specName = entry.name;
+      const locksDir = this._locksDir(specName);
+
+      let lockFiles;
+      try {
+        lockFiles = await fs.readdir(locksDir);
+      } catch (err) {
+        if (err.code === 'ENOENT') continue;
+        throw err;
+      }
+
+      for (const file of lockFiles) {
+        if (!file.endsWith('.lock')) continue;
+
+        const lockPath = path.join(locksDir, file);
+        const lockData = await this._readLockFile(lockPath);
+
+        if (lockData && lockData.agentId === agentId) {
+          try {
+            await fs.unlink(lockPath);
+            released.push({ specName, taskId: lockData.taskId });
+          } catch (err) {
+            if (err.code !== 'ENOENT') throw err;
+          }
+        }
+      }
+    }
+
+    return { released };
+  }
+
+  /**
+   * Get the lock status for a specific task.
+   *
+   * @param {string} specName
+   * @param {string} taskId
+   * @returns {Promise<{locked: boolean, lock?: object}>}
+   */
+  async getTaskLockStatus(specName, taskId) {
+    const lockPath = this._lockFilePath(specName, taskId);
+    const lockData = await this._readLockFile(lockPath);
+
+    if (!lockData) {
+      return { locked: false, specName, taskId };
+    }
+
+    return { locked: true, specName, taskId, lock: lockData };
+  }
+
+  /**
+   * List all locked tasks within a spec.
+   *
+   * @param {string} specName
+   * @returns {Promise<Array<{locked: boolean, specName: string, taskId: string, lock?: object}>>}
+   */
+  async listLockedTasks(specName) {
+    const locksDir = this._locksDir(specName);
+    const results = [];
+
+    let files;
+    try {
+      files = await fs.readdir(locksDir);
+    } catch (err) {
+      if (err.code === 'ENOENT') return results;
+      throw err;
+    }
+
+    for (const file of files) {
+      if (!file.endsWith('.lock')) continue;
+
+      const lockPath = path.join(locksDir, file);
+      const lockData = await this._readLockFile(lockPath);
+
+      if (lockData) {
+        results.push({
+          locked: true,
+          specName,
+          taskId: lockData.taskId,
+          lock: lockData,
+        });
+      }
+    }
+
+    return results;
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────
+
+  /**
+   * Build a lock record object.
+   * @private
+   */
+  async _buildLockRecord(specName, taskId, agentId, reason) {
+    const machineInfo = await this._machineIdentifier.getMachineId();
+    return {
+      agentId,
+      machineId: machineInfo.id,
+      hostname: machineInfo.hostname,
+      taskId,
+      specName,
+      acquiredAt: new Date().toISOString(),
+      reason: reason || null,
+    };
+  }
+
+  /**
+   * Read and parse a lock file. Returns null if missing or corrupted.
+   * @param {string} lockPath
+   * @returns {Promise<object|null>}
+   * @private
+   */
+  async _readLockFile(lockPath) {
+    try {
+      const raw = await fs.readFile(lockPath, 'utf8');
+      const data = JSON.parse(raw);
+      if (data && typeof data.agentId === 'string' && typeof data.taskId === 'string') {
+        return data;
+      }
+      return null; // Invalid structure
+    } catch (err) {
+      if (err.code === 'ENOENT' || err instanceof SyntaxError) {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Atomically write a lock file using temp + rename (Req 2.7).
+   * @param {string} lockPath
+   * @param {object} data
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _atomicWriteLock(lockPath, data) {
+    const content = JSON.stringify(data, null, 2);
+    await fsUtils.atomicWrite(lockPath, content);
+  }
+}
+
+module.exports = { TaskLockManager };

package/lib/operations/audit-logger.js

@@ -0,0 +1,293 @@
+/**
+ * Audit Logger
+ * 
+ * Logs all AI operations with tamper-evident storage
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const crypto = require('crypto');
+
+class AuditLogger {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.auditPath = path.join(projectRoot, '.kiro/audit');
+  }
+  
+  /**
+   * Log an operation
+   * 
+   * @param {Object} entry - Audit entry
+   * @returns {Promise<string>} Entry ID
+   */
+  async logOperation(entry) {
+    await fs.ensureDir(this.auditPath);
+    
+    // Generate entry ID
+    const id = `audit-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    
+    // Create full entry
+    const fullEntry = {
+      id,
+      timestamp: new Date().toISOString(),
+      ...entry
+    };
+    
+    // Calculate checksum for tamper-evidence
+    const checksum = this.calculateChecksum(fullEntry);
+    fullEntry.checksum = checksum;
+    
+    // Write to log file (append)
+    const logFile = path.join(this.auditPath, 'operations.jsonl');
+    await fs.appendFile(
+      logFile,
+      JSON.stringify(fullEntry) + '\n',
+      'utf8'
+    );
+    
+    return id;
+  }
+  
+  /**
+   * Query audit logs
+   * 
+   * @param {Object} query - Query parameters
+   * @returns {Promise<Array>} Matching entries
+   */
+  async queryLogs(query = {}) {
+    const logFile = path.join(this.auditPath, 'operations.jsonl');
+    
+    if (!await fs.pathExists(logFile)) {
+      return [];
+    }
+    
+    // Read all entries
+    const content = await fs.readFile(logFile, 'utf8');
+    const lines = content.trim().split('\n').filter(line => line);
+    const entries = lines.map(line => JSON.parse(line));
+    
+    // Filter by query
+    return entries.filter(entry => {
+      if (query.projectName && entry.project !== query.projectName) return false;
+      if (query.operationType && entry.operationType !== query.operationType) return false;
+      if (query.outcome && entry.outcome !== query.outcome) return false;
+      if (query.environment && entry.securityEnvironment !== query.environment) return false;
+      
+      if (query.fromDate) {
+        const entryDate = new Date(entry.timestamp);
+        const fromDate = new Date(query.fromDate);
+        if (entryDate < fromDate) return false;
+      }
+      
+      if (query.toDate) {
+        const entryDate = new Date(entry.timestamp);
+        const toDate = new Date(query.toDate);
+        if (entryDate > toDate) return false;
+      }
+      
+      return true;
+    });
+  }
+  
+  /**
+   * Generate audit summary
+   * 
+   * @param {string} project - Project name
+   * @param {Object} timeRange - Time range {from, to}
+   * @returns {Promise<Object>} Audit summary
+   */
+  async generateSummary(project, timeRange = {}) {
+    const entries = await this.queryLogs({
+      projectName: project,
+      fromDate: timeRange.from,
+      toDate: timeRange.to
+    });
+    
+    const summary = {
+      project,
+      timeRange,
+      totalOperations: entries.length,
+      successCount: entries.filter(e => e.outcome === 'success').length,
+      failureCount: entries.filter(e => e.outcome === 'failure').length,
+      operationsByType: {},
+      operationsByLevel: {}
+    };
+    
+    summary.successRate = summary.totalOperations > 0
+      ? (summary.successCount / summary.totalOperations * 100).toFixed(2) + '%'
+      : '0%';
+    
+    // Count by type
+    entries.forEach(entry => {
+      const type = entry.operationType || 'unknown';
+      summary.operationsByType[type] = (summary.operationsByType[type] || 0) + 1;
+      
+      const level = entry.takeoverLevel || 'unknown';
+      summary.operationsByLevel[level] = (summary.operationsByLevel[level] || 0) + 1;
+    });
+    
+    return summary;
+  }
+  
+  /**
+   * Export audit logs
+   * 
+   * @param {Object} query - Query parameters
+   * @param {string} format - Export format (json, csv)
+   * @returns {Promise<string>} Exported data
+   */
+  async exportLogs(query = {}, format = 'json') {
+    const entries = await this.queryLogs(query);
+    
+    if (format === 'json') {
+      return JSON.stringify(entries, null, 2);
+    }
+    
+    if (format === 'csv') {
+      if (entries.length === 0) return '';
+      
+      // CSV header
+      const headers = Object.keys(entries[0]);
+      let csv = headers.join(',') + '\n';
+      
+      // CSV rows
+      entries.forEach(entry => {
+        const row = headers.map(h => {
+          const value = entry[h];
+          return typeof value === 'string' ? `"${value}"` : value;
+        });
+        csv += row.join(',') + '\n';
+      });
+      
+      return csv;
+    }
+    
+    throw new Error(`Unsupported export format: ${format}`);
+  }
+  
+  /**
+   * Calculate checksum for tamper-evidence
+   * 
+   * @param {Object} entry - Audit entry
+   * @returns {string} SHA-256 checksum
+   */
+  calculateChecksum(entry) {
+    const data = JSON.stringify(entry);
+    return crypto.createHash('sha256').update(data).digest('hex');
+  }
+  
+  /**
+   * Verify entry integrity
+   * 
+   * @param {Object} entry - Audit entry with checksum
+   * @returns {boolean} Whether entry is valid
+   */
+  verifyEntry(entry) {
+    const { checksum, ...entryWithoutChecksum } = entry;
+    const calculatedChecksum = this.calculateChecksum(entryWithoutChecksum);
+    return checksum === calculatedChecksum;
+  }
+  
+  /**
+   * Flag anomalies in operations
+   * 
+   * @param {string} project - Project name
+   * @param {Object} threshold - Anomaly thresholds
+   * @returns {Promise<Array>} Detected anomalies
+   */
+  async flagAnomalies(project, threshold = {}) {
+    const entries = await this.queryLogs({ projectName: project });
+    
+    if (entries.length === 0) {
+      return [];
+    }
+    
+    const anomalies = [];
+    
+    // Default thresholds
+    const thresholds = {
+      errorRatePercent: threshold.errorRatePercent || 10,
+      operationCountPerHour: threshold.operationCountPerHour || 100,
+      unusualOperationType: threshold.unusualOperationType || true,
+      ...threshold
+    };
+    
+    // Calculate baseline metrics
+    const totalOps = entries.length;
+    const failedOps = entries.filter(e => e.outcome === 'failure').length;
+    const errorRate = (failedOps / totalOps) * 100;
+    
+    // Anomaly 1: High error rate
+    if (errorRate > thresholds.errorRatePercent) {
+      anomalies.push({
+        type: 'high_error_rate',
+        severity: 'high',
+        message: `Error rate ${errorRate.toFixed(2)}% exceeds threshold ${thresholds.errorRatePercent}%`,
+        metric: errorRate,
+        threshold: thresholds.errorRatePercent,
+        affectedOperations: failedOps
+      });
+    }
+    
+    // Anomaly 2: Unusual operation frequency
+    const now = new Date();
+    const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000);
+    const recentOps = entries.filter(e => new Date(e.timestamp) > oneHourAgo);
+    
+    if (recentOps.length > thresholds.operationCountPerHour) {
+      anomalies.push({
+        type: 'high_operation_frequency',
+        severity: 'medium',
+        message: `${recentOps.length} operations in last hour exceeds threshold ${thresholds.operationCountPerHour}`,
+        metric: recentOps.length,
+        threshold: thresholds.operationCountPerHour,
+        timeWindow: '1 hour'
+      });
+    }
+    
+    // Anomaly 3: Unusual operation types
+    if (thresholds.unusualOperationType) {
+      const operationTypes = {};
+      entries.forEach(e => {
+        const type = e.operationType || 'unknown';
+        operationTypes[type] = (operationTypes[type] || 0) + 1;
+      });
+      
+      // Flag operation types that appear only once or twice (potentially unusual)
+      Object.entries(operationTypes).forEach(([type, count]) => {
+        if (count <= 2 && totalOps > 10) {
+          anomalies.push({
+            type: 'unusual_operation_type',
+            severity: 'low',
+            message: `Operation type '${type}' appears only ${count} time(s)`,
+            operationType: type,
+            occurrences: count
+          });
+        }
+      });
+    }
+    
+    // Anomaly 4: Repeated failures of same operation
+    const failuresByType = {};
+    entries.filter(e => e.outcome === 'failure').forEach(e => {
+      const type = e.operationType || 'unknown';
+      failuresByType[type] = (failuresByType[type] || 0) + 1;
+    });
+    
+    Object.entries(failuresByType).forEach(([type, count]) => {
+      if (count >= 3) {
+        anomalies.push({
+          type: 'repeated_failures',
+          severity: 'high',
+          message: `Operation type '${type}' failed ${count} times`,
+          operationType: type,
+          failureCount: count
+        });
+      }
+    });
+    
+    return anomalies;
+  }
+}
+
+module.exports = AuditLogger;