scene-capability-engine 3.0.0

package/lib/collab/agent-registry.js

@@ -0,0 +1,240 @@
+/**
+ * Agent Registry - Manages Agent registration, heartbeat, and lifecycle
+ *
+ * Stores agent records in `.kiro/config/agent-registry.json`.
+ * Uses MachineIdentifier for unique Agent ID generation ({machineId}:{instanceIndex}).
+ * All write operations use atomic writes via fs-utils.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.5, 1.6, 1.7
+ */
+
+const path = require('path');
+const fsUtils = require('../utils/fs-utils');
+const { MultiAgentConfig } = require('./multi-agent-config');
+
+const REGISTRY_FILENAME = 'agent-registry.json';
+const CONFIG_DIR = '.kiro/config';
+
+const EMPTY_REGISTRY = Object.freeze({
+  version: '1.0.0',
+  agents: {},
+});
+
+class AgentRegistry {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   * @param {import('../lock/machine-identifier').MachineIdentifier} machineIdentifier
+   * @param {import('../lock/task-lock-manager').TaskLockManager|null} [taskLockManager=null] - Optional, injected to avoid circular deps
+   */
+  constructor(workspaceRoot, machineIdentifier, taskLockManager = null) {
+    this._workspaceRoot = workspaceRoot;
+    this._machineIdentifier = machineIdentifier;
+    this._taskLockManager = taskLockManager;
+    this._registryPath = path.join(workspaceRoot, CONFIG_DIR, REGISTRY_FILENAME);
+    this._configDir = path.join(workspaceRoot, CONFIG_DIR);
+    this._multiAgentConfig = new MultiAgentConfig(workspaceRoot);
+  }
+
+  /**
+   * Read the registry file. Auto-creates an empty registry if it doesn't exist (Req 1.7).
+   * @returns {Promise<object>}
+   * @private
+   */
+  async _readRegistry() {
+    const exists = await fsUtils.pathExists(this._registryPath);
+    if (!exists) {
+      return { ...EMPTY_REGISTRY, agents: {} };
+    }
+    try {
+      const data = await fsUtils.readJSON(this._registryPath);
+      if (!data || typeof data.agents !== 'object') {
+        return { ...EMPTY_REGISTRY, agents: {} };
+      }
+      return data;
+    } catch (_err) {
+      // Corrupted file – rebuild empty registry
+      return { ...EMPTY_REGISTRY, agents: {} };
+    }
+  }
+
+  /**
+   * Persist the registry atomically.
+   * Ensures the config directory exists before writing (Req 1.7).
+   * @param {object} registry
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _writeRegistry(registry) {
+    await fsUtils.ensureDirectory(this._configDir);
+    await fsUtils.writeJSON(this._registryPath, registry);
+  }
+
+  /**
+   * Find the next available instanceIndex for a given machineId.
+   * Scans existing agents with the same machineId and picks the lowest unused index.
+   * @param {object} agents - Current agents map
+   * @param {string} machineId
+   * @returns {number}
+   * @private
+   */
+  _nextInstanceIndex(agents, machineId) {
+    const usedIndices = new Set();
+    for (const record of Object.values(agents)) {
+      if (record.machineId === machineId) {
+        usedIndices.add(record.instanceIndex);
+      }
+    }
+    let index = 0;
+    while (usedIndices.has(index)) {
+      index++;
+    }
+    return index;
+  }
+
+  /**
+   * Register a new Agent. Generates a unique AgentID based on MachineIdentifier.
+   *
+   * @param {object} [options={}]
+   * @param {object|null} [options.currentTask] - Optional initial task assignment
+   * @returns {Promise<{agentId: string, registeredAt: string}>}
+   */
+  async register(options = {}) {
+    const machineInfo = await this._machineIdentifier.getMachineId();
+    const registry = await this._readRegistry();
+
+    const instanceIndex = this._nextInstanceIndex(registry.agents, machineInfo.id);
+    const agentId = `${machineInfo.id}:${instanceIndex}`;
+    const now = new Date().toISOString();
+
+    registry.agents[agentId] = {
+      agentId,
+      machineId: machineInfo.id,
+      instanceIndex,
+      hostname: machineInfo.hostname,
+      registeredAt: now,
+      lastHeartbeat: now,
+      status: 'active',
+      currentTask: options.currentTask || null,
+    };
+
+    await this._writeRegistry(registry);
+
+    return { agentId, registeredAt: now };
+  }
+
+  /**
+   * Deregister an Agent. Removes the record and releases associated resources.
+   *
+   * @param {string} agentId
+   * @returns {Promise<{success: boolean, releasedLocks: Array<{specName: string, taskId: string}>}>}
+   */
+  async deregister(agentId) {
+    const registry = await this._readRegistry();
+
+    if (!registry.agents[agentId]) {
+      return { success: false, releasedLocks: [] };
+    }
+
+    delete registry.agents[agentId];
+    await this._writeRegistry(registry);
+
+    // Release all task locks held by this agent (Req 1.6)
+    let releasedLocks = [];
+    if (this._taskLockManager) {
+      const result = await this._taskLockManager.releaseAllLocks(agentId);
+      releasedLocks = result.released;
+    }
+
+    return { success: true, releasedLocks };
+  }
+
+  /**
+   * Update heartbeat timestamp for an Agent.
+   *
+   * @param {string} agentId
+   * @returns {Promise<{success: boolean, lastHeartbeat: string|null}>}
+   */
+  async heartbeat(agentId) {
+    const registry = await this._readRegistry();
+    const agent = registry.agents[agentId];
+
+    if (!agent) {
+      return { success: false, lastHeartbeat: null };
+    }
+
+    const now = new Date().toISOString();
+    agent.lastHeartbeat = now;
+    agent.status = 'active';
+
+    await this._writeRegistry(registry);
+
+    return { success: true, lastHeartbeat: now };
+  }
+
+  /**
+   * Get all agents with status 'active'.
+   * @returns {Promise<object[]>}
+   */
+  async getActiveAgents() {
+    const registry = await this._readRegistry();
+    return Object.values(registry.agents).filter((a) => a.status === 'active');
+  }
+
+  /**
+   * Get a specific Agent record by ID.
+   * @param {string} agentId
+   * @returns {Promise<object|null>}
+   */
+  async getAgent(agentId) {
+    const registry = await this._readRegistry();
+    return registry.agents[agentId] || null;
+  }
+
+  /**
+   * Detect and clean up inactive Agents whose heartbeat has timed out.
+   * Uses heartbeatTimeoutMs from MultiAgentConfig (default 180 000 ms).
+   * Releases all task locks held by each inactive Agent (Req 1.4, 2.4).
+   *
+   * @returns {Promise<{cleaned: string[], releasedLocks: Array<{specName: string, taskId: string}>}>}
+   */
+  async cleanupInactive() {
+    const config = await this._multiAgentConfig.getConfig();
+    const timeoutMs = config.heartbeatTimeoutMs;
+    const now = Date.now();
+
+    const registry = await this._readRegistry();
+    const cleaned = [];
+
+    for (const agent of Object.values(registry.agents)) {
+      if (agent.status !== 'active') continue;
+
+      const lastBeat = new Date(agent.lastHeartbeat).getTime();
+      if (now - lastBeat > timeoutMs) {
+        agent.status = 'inactive';
+        cleaned.push(agent.agentId);
+      }
+    }
+
+    if (cleaned.length > 0) {
+      await this._writeRegistry(registry);
+    }
+
+    // Release all task locks for each cleaned agent (Req 1.4, 2.4)
+    const releasedLocks = [];
+    if (this._taskLockManager && cleaned.length > 0) {
+      for (const agentId of cleaned) {
+        const result = await this._taskLockManager.releaseAllLocks(agentId);
+        releasedLocks.push(...result.released);
+      }
+    }
+
+    return { cleaned, releasedLocks };
+  }
+
+  /** Absolute path to the registry file (useful for tests / diagnostics). */
+  get registryPath() {
+    return this._registryPath;
+  }
+}
+
+module.exports = { AgentRegistry, EMPTY_REGISTRY };

package/lib/collab/collab-manager.js

@@ -0,0 +1,285 @@
+const MetadataManager = require('./metadata-manager');
+const DependencyManager = require('./dependency-manager');
+const ContractManager = require('./contract-manager');
+const IntegrationManager = require('./integration-manager');
+const Visualizer = require('./visualizer');
+
+/**
+ * CollaborationManager orchestrates all collaboration operations
+ */
+class CollaborationManager {
+  constructor(workspaceRoot) {
+    this.workspaceRoot = workspaceRoot;
+    
+    // Initialize managers
+    this.metadataManager = new MetadataManager(workspaceRoot);
+    this.dependencyManager = new DependencyManager(this.metadataManager);
+    this.contractManager = new ContractManager(workspaceRoot, this.metadataManager);
+    this.integrationManager = new IntegrationManager(workspaceRoot, this.metadataManager);
+    this.visualizer = new Visualizer();
+  }
+
+  /**
+   * Initialize a Master Spec with Sub-Specs
+   * @param {string} masterName - Name of the master spec
+   * @param {Array<Object>} subSpecs - Array of {name, dependencies}
+   * @param {Object} options - Additional options
+   * @returns {Promise<Object>} Creation result
+   */
+  async initMasterSpec(masterName, subSpecs, options = {}) {
+    // Create master spec metadata
+    const masterMetadata = {
+      version: '1.0.0',
+      type: 'master',
+      subSpecs: subSpecs.map(s => s.name),
+      dependencies: [],
+      status: {
+        current: 'in-progress',
+        updatedAt: new Date().toISOString()
+      },
+      interfaces: {
+        provides: [],
+        consumes: []
+      }
+    };
+
+    await this.metadataManager.writeMetadata(masterName, masterMetadata);
+
+    // Create sub-spec metadata
+    const created = [];
+    for (const subSpec of subSpecs) {
+      const subMetadata = {
+        version: '1.0.0',
+        type: 'sub',
+        masterSpec: masterName,
+        dependencies: subSpec.dependencies || [],
+        status: {
+          current: 'not-started',
+          updatedAt: new Date().toISOString()
+        },
+        interfaces: {
+          provides: [],
+          consumes: []
+        }
+      };
+
+      await this.metadataManager.writeMetadata(subSpec.name, subMetadata);
+      created.push(subSpec.name);
+    }
+
+    // Validate dependencies
+    const graph = await this.dependencyManager.buildDependencyGraph();
+    const cycle = this.dependencyManager.detectCircularDependencies(graph);
+    
+    if (cycle) {
+      return {
+        success: false,
+        error: `Circular dependency detected: ${cycle.join(' → ')}`,
+        created: [masterName, ...created]
+      };
+    }
+
+    return {
+      success: true,
+      master: masterName,
+      subSpecs: created,
+      message: `Created master spec '${masterName}' with ${created.length} sub-specs`
+    };
+  }
+
+  /**
+   * Get collaboration status for all specs or a specific spec
+   * @param {string} specName - Optional spec name
+   * @returns {Promise<Object>} Status information
+   */
+  async getCollaborationStatus(specName = null) {
+    if (specName) {
+      const metadata = await this.metadataManager.readMetadata(specName);
+      if (!metadata) {
+        return {
+          found: false,
+          error: `Spec '${specName}' not found`
+        };
+      }
+
+      return {
+        found: true,
+        spec: specName,
+        metadata
+      };
+    }
+
+    // Get all specs
+    const allSpecs = await this.metadataManager.listAllMetadata();
+    const graph = await this.dependencyManager.buildDependencyGraph();
+    const ready = this.dependencyManager.getReadySpecs(graph);
+
+    return {
+      total: allSpecs.length,
+      specs: allSpecs,
+      ready,
+      graph
+    };
+  }
+
+  /**
+   * Assign a spec to a Kiro instance
+   * @param {string} specName - Name of the spec
+   * @param {string} kiroInstance - Kiro instance identifier
+   * @returns {Promise<Object>} Assignment result
+   */
+  async assignSpec(specName, kiroInstance) {
+    const metadata = await this.metadataManager.readMetadata(specName);
+    
+    if (!metadata) {
+      return {
+        success: false,
+        error: `Spec '${specName}' not found`
+      };
+    }
+
+    // Check if blocked
+    if (metadata.status.current === 'blocked') {
+      return {
+        success: false,
+        error: `Cannot assign blocked spec (reason: ${metadata.status.blockReason || 'unknown'})`
+      };
+    }
+
+    // Update assignment
+    const updated = await this.metadataManager.atomicUpdate(specName, (meta) => {
+      meta.assignment = {
+        kiroInstance,
+        assignedAt: new Date().toISOString()
+      };
+      return meta;
+    });
+
+    return {
+      success: true,
+      spec: specName,
+      kiroInstance,
+      message: `Assigned '${specName}' to '${kiroInstance}'`
+    };
+  }
+
+  /**
+   * Update spec status
+   * @param {string} specName - Name of the spec
+   * @param {string} status - New status
+   * @param {string} reason - Optional reason (for blocked status)
+   * @returns {Promise<Object>} Update result
+   */
+  async updateSpecStatus(specName, status, reason = null) {
+    const validStatuses = ['not-started', 'in-progress', 'completed', 'blocked'];
+    
+    if (!validStatuses.includes(status)) {
+      return {
+        success: false,
+        error: `Invalid status: ${status}`
+      };
+    }
+
+    const updated = await this.metadataManager.atomicUpdate(specName, (meta) => {
+      meta.status = {
+        current: status,
+        updatedAt: new Date().toISOString()
+      };
+      
+      if (status === 'blocked' && reason) {
+        meta.status.blockReason = reason;
+      }
+      
+      return meta;
+    });
+
+    // If completed, update dependent specs
+    if (status === 'completed') {
+      const nowReady = await this.dependencyManager.updateDependentSpecs(specName);
+      return {
+        success: true,
+        spec: specName,
+        status,
+        nowReady,
+        message: `Updated '${specName}' to '${status}'. ${nowReady.length} specs now ready.`
+      };
+    }
+
+    return {
+      success: true,
+      spec: specName,
+      status,
+      message: `Updated '${specName}' to '${status}'`
+    };
+  }
+
+  /**
+   * Verify contracts for a spec
+   * @param {string} specName - Name of the spec
+   * @returns {Promise<Object>} Verification result
+   */
+  async verifyContracts(specName) {
+    return await this.contractManager.verifyImplementation(specName);
+  }
+
+  /**
+   * Run integration tests
+   * @param {Array<string>} specNames - Specs to test
+   * @returns {Promise<Object>} Test results
+   */
+  async runIntegrationTests(specNames) {
+    return await this.integrationManager.runAllTests(specNames);
+  }
+
+  /**
+   * Generate dependency graph visualization
+   * @param {string} format - Format ('text' or 'mermaid')
+   * @param {Object} options - Visualization options
+   * @returns {Promise<string>} Graph visualization
+   */
+  async generateDependencyGraph(format = 'text', options = {}) {
+    const graph = await this.dependencyManager.buildDependencyGraph();
+    
+    if (format === 'mermaid') {
+      return this.visualizer.generateMermaidGraph(graph);
+    }
+    
+    return this.visualizer.generateTextGraph(graph, options);
+  }
+
+  /**
+   * Validate all dependencies
+   * @param {string} specName - Optional spec name to validate
+   * @returns {Promise<Object>} Validation result
+   */
+  async validateDependencies(specName = null) {
+    const graph = await this.dependencyManager.buildDependencyGraph(
+      specName ? [specName] : null
+    );
+    
+    const cycle = this.dependencyManager.detectCircularDependencies(graph);
+    
+    if (cycle) {
+      return {
+        valid: false,
+        error: `Circular dependency detected: ${cycle.join(' → ')}`
+      };
+    }
+
+    return {
+      valid: true,
+      message: 'All dependencies are valid'
+    };
+  }
+
+  /**
+   * Get ready specs (specs that can be started)
+   * @returns {Promise<Array<string>>} List of ready spec names
+   */
+  async getReadySpecs() {
+    const graph = await this.dependencyManager.buildDependencyGraph();
+    return this.dependencyManager.getReadySpecs(graph);
+  }
+}
+
+module.exports = CollaborationManager;