kiro-spec-engine 1.44.0 → 1.45.2

package/lib/orchestrator/orchestrator-config.js

@@ -0,0 +1,157 @@
+/**
+ * Orchestrator Configuration Manager
+ *
+ * Manages `.kiro/config/orchestrator.json` for the Agent Orchestrator.
+ * When the config file does not exist or contains invalid JSON,
+ * returns a default configuration so that orchestration can proceed
+ * with sensible defaults.
+ *
+ * Requirements: 7.1 (read from orchestrator.json), 7.2 (defaults when missing),
+ *               7.3 (supported config fields), 7.4 (invalid JSON fallback),
+ *               7.5 (unknown fields ignored)
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const fsUtils = require('../utils/fs-utils');
+
+const CONFIG_FILENAME = 'orchestrator.json';
+const CONFIG_DIR = '.kiro/config';
+
+/** Known configuration keys — anything else is silently ignored. */
+const KNOWN_KEYS = new Set([
+  'agentBackend',
+  'maxParallel',
+  'timeoutSeconds',
+  'maxRetries',
+  'apiKeyEnvVar',
+  'bootstrapTemplate',
+  'codexArgs',
+  'codexCommand',
+]);
+
+/** @type {import('./orchestrator-config').OrchestratorConfigData} */
+const DEFAULT_CONFIG = Object.freeze({
+  agentBackend: 'codex',
+  maxParallel: 3,
+  timeoutSeconds: 600,
+  maxRetries: 2,
+  apiKeyEnvVar: 'CODEX_API_KEY',
+  bootstrapTemplate: null,
+  codexArgs: [],
+  codexCommand: null,
+});
+
+class OrchestratorConfig {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   */
+  constructor(workspaceRoot) {
+    this._workspaceRoot = workspaceRoot;
+    this._configPath = path.join(workspaceRoot, CONFIG_DIR, CONFIG_FILENAME);
+    this._configDir = path.join(workspaceRoot, CONFIG_DIR);
+  }
+
+  /**
+   * Read the current configuration.
+   * Returns the default config when the file is missing or contains invalid JSON.
+   * Unknown fields in the file are silently ignored (Requirement 7.5).
+   *
+   * @returns {Promise<object>} Resolved configuration
+   */
+  async getConfig() {
+    const exists = await fsUtils.pathExists(this._configPath);
+    if (!exists) {
+      return { ...DEFAULT_CONFIG };
+    }
+
+    try {
+      const data = await fsUtils.readJSON(this._configPath);
+      return this._mergeWithDefaults(data);
+    } catch (_err) {
+      // Invalid JSON — fall back to defaults (Requirement 7.4)
+      console.warn(
+        `[OrchestratorConfig] Failed to parse ${this._configPath}, using default config`
+      );
+      return { ...DEFAULT_CONFIG };
+    }
+  }
+
+  /**
+   * Persist a (partial) configuration update.
+   * Merges the provided values with the current config and writes atomically.
+   * Auto-initialises the config directory on first write.
+   *
+   * @param {object} updates - Partial config values to merge
+   * @returns {Promise<object>} The full config after the update
+   */
+  async updateConfig(updates) {
+    await fsUtils.ensureDirectory(this._configDir);
+    const current = await this.getConfig();
+    const filtered = this._filterKnownKeys(updates);
+    const merged = { ...current, ...filtered };
+    await fsUtils.writeJSON(this._configPath, merged);
+    return merged;
+  }
+
+  /**
+   * Get the bootstrap prompt template.
+   * If a custom template path is configured, reads and returns its content.
+   * Otherwise returns null (callers should use the built-in default template).
+   *
+   * @returns {Promise<string|null>} Template content or null
+   */
+  async getBootstrapTemplate() {
+    const config = await this.getConfig();
+    if (!config.bootstrapTemplate) {
+      return null;
+    }
+
+    const templatePath = path.resolve(this._workspaceRoot, config.bootstrapTemplate);
+    try {
+      return await fs.readFile(templatePath, 'utf8');
+    } catch (_err) {
+      console.warn(
+        `[OrchestratorConfig] Failed to read bootstrap template at ${templatePath}, using default`
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Merge raw data with defaults, keeping only known keys.
+   * @param {object} data - Raw config data from file
+   * @returns {object} Merged config with only known keys
+   * @private
+   */
+  _mergeWithDefaults(data) {
+    const filtered = this._filterKnownKeys(data);
+    return { ...DEFAULT_CONFIG, ...filtered };
+  }
+
+  /**
+   * Filter an object to only include known configuration keys.
+   * @param {object} obj
+   * @returns {object}
+   * @private
+   */
+  _filterKnownKeys(obj) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+      return {};
+    }
+    const result = {};
+    for (const key of Object.keys(obj)) {
+      if (KNOWN_KEYS.has(key)) {
+        result[key] = obj[key];
+      }
+    }
+    return result;
+  }
+
+  /** Absolute path to the config file (useful for tests / diagnostics). */
+  get configPath() {
+    return this._configPath;
+  }
+}
+
+module.exports = { OrchestratorConfig, DEFAULT_CONFIG, KNOWN_KEYS };

package/lib/orchestrator/status-monitor.js

@@ -0,0 +1,438 @@
+/**
+ * Status Monitor — Orchestration State Tracker
+ *
+ * Parses Codex JSON Lines events, tracks per-Spec execution status,
+ * computes aggregate orchestration state, and synchronises progress
+ * to SpecLifecycleManager and ContextSyncManager.
+ *
+ * Requirements: 4.1 (maintain per-agent status), 4.2 (parse JSON Lines events),
+ *               4.3 (update SpecLifecycleManager on completion),
+ *               4.4 (update ContextSyncManager on completion),
+ *               4.5 (return summary report with statuses, progress, batch info)
+ */
+
+const VALID_SPEC_STATUSES = new Set([
+  'pending', 'running', 'completed', 'failed', 'timeout', 'skipped',
+]);
+
+const VALID_ORCHESTRATION_STATUSES = new Set([
+  'idle', 'running', 'completed', 'failed', 'stopped',
+]);
+
+/**
+ * Maps Codex JSON Lines event types to internal handling.
+ * item.* events are matched by prefix.
+ * @type {Set<string>}
+ */
+const KNOWN_EVENT_TYPES = new Set([
+  'thread.started',
+  'turn.started',
+  'turn.completed',
+  'error',
+]);
+
+class StatusMonitor {
+  /**
+   * @param {import('../collab/spec-lifecycle-manager').SpecLifecycleManager} specLifecycleManager
+   * @param {import('../steering/context-sync-manager').ContextSyncManager} contextSyncManager
+   */
+  constructor(specLifecycleManager, contextSyncManager) {
+    this._specLifecycleManager = specLifecycleManager;
+    this._contextSyncManager = contextSyncManager;
+
+    /** @type {'idle'|'running'|'completed'|'failed'|'stopped'} */
+    this._orchestrationStatus = 'idle';
+    /** @type {string|null} */
+    this._startedAt = null;
+    /** @type {string|null} */
+    this._completedAt = null;
+    /** @type {number} */
+    this._currentBatch = 0;
+    /** @type {number} */
+    this._totalBatches = 0;
+
+    /**
+     * Per-Spec execution status.
+     * @type {Map<string, {status: string, batch: number, agentId: string|null, retryCount: number, error: string|null, turnCount: number}>}
+     */
+    this._specs = new Map();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Register a Spec for tracking before execution begins.
+   *
+   * @param {string} specName
+   * @param {number} batch - Batch number this Spec belongs to
+   */
+  initSpec(specName, batch) {
+    this._specs.set(specName, {
+      status: 'pending',
+      batch: batch || 0,
+      agentId: null,
+      retryCount: 0,
+      error: null,
+      turnCount: 0,
+    });
+  }
+
+  /**
+   * Update the execution status of a specific Spec.
+   *
+   * @param {string} specName
+   * @param {string} status - One of VALID_SPEC_STATUSES
+   * @param {string|null} [agentId=null]
+   * @param {string|null} [error=null]
+   */
+  updateSpecStatus(specName, status, agentId = null, error = null) {
+    const entry = this._specs.get(specName);
+    if (!entry) {
+      // Unknown spec — initialise on the fly
+      this._specs.set(specName, {
+        status: VALID_SPEC_STATUSES.has(status) ? status : 'pending',
+        batch: 0,
+        agentId,
+        retryCount: 0,
+        error,
+        turnCount: 0,
+      });
+      return;
+    }
+
+    if (VALID_SPEC_STATUSES.has(status)) {
+      entry.status = status;
+    }
+    if (agentId !== null && agentId !== undefined) {
+      entry.agentId = agentId;
+    }
+    if (error !== null && error !== undefined) {
+      entry.error = error;
+    }
+  }
+
+  /**
+   * Increment the retry count for a Spec.
+   *
+   * @param {string} specName
+   */
+  incrementRetry(specName) {
+    const entry = this._specs.get(specName);
+    if (entry) {
+      entry.retryCount++;
+    }
+  }
+
+  /**
+   * Set the overall orchestration state.
+   *
+   * @param {'idle'|'running'|'completed'|'failed'|'stopped'} state
+   */
+  setOrchestrationState(state) {
+    if (!VALID_ORCHESTRATION_STATUSES.has(state)) {
+      return;
+    }
+    this._orchestrationStatus = state;
+
+    if (state === 'running' && !this._startedAt) {
+      this._startedAt = new Date().toISOString();
+    }
+    if (state === 'completed' || state === 'failed' || state === 'stopped') {
+      this._completedAt = new Date().toISOString();
+    }
+  }
+
+  /**
+   * Set batch progress information.
+   *
+   * @param {number} current - Current batch index (1-based)
+   * @param {number} total - Total number of batches
+   */
+  setBatchInfo(current, total) {
+    this._currentBatch = typeof current === 'number' ? current : 0;
+    this._totalBatches = typeof total === 'number' ? total : 0;
+  }
+
+  /**
+   * Handle a Codex JSON Lines event for a specific agent.
+   * Gracefully handles invalid/malformed events — never throws.
+   *
+   * Supported event types:
+   * - thread.started: marks the agent's Spec as running
+   * - turn.started / turn.completed: tracks turn progress
+   * - item.*: generic item events (logged)
+   * - error: records error information
+   *
+   * @param {string} agentId
+   * @param {*} event - Parsed or raw event (string or object)
+   */
+  handleEvent(agentId, event) {
+    try {
+      const parsed = this._parseEvent(event);
+      if (!parsed) return;
+
+      // Find the Spec associated with this agentId
+      const specName = this._findSpecByAgentId(agentId);
+
+      this._processEvent(specName, agentId, parsed);
+    } catch (_err) {
+      // Graceful handling — never throw (Req 4.2)
+    }
+  }
+
+  /**
+   * Return the full orchestration status report.
+   * Computes aggregate stats from the per-Spec map.
+   *
+   * @returns {object} OrchestrationStatus
+   */
+  getOrchestrationStatus() {
+    const specs = Object.create(null);
+    let completedSpecs = 0;
+    let failedSpecs = 0;
+    let runningSpecs = 0;
+
+    for (const [specName, entry] of this._specs) {
+      specs[specName] = {
+        status: entry.status,
+        batch: entry.batch,
+        agentId: entry.agentId,
+        retryCount: entry.retryCount,
+        error: entry.error,
+      };
+
+      if (entry.status === 'completed') completedSpecs++;
+      else if (entry.status === 'failed' || entry.status === 'timeout') failedSpecs++;
+      else if (entry.status === 'running') runningSpecs++;
+    }
+
+    return {
+      status: this._orchestrationStatus,
+      startedAt: this._startedAt,
+      completedAt: this._completedAt,
+      totalSpecs: this._specs.size,
+      completedSpecs,
+      failedSpecs,
+      runningSpecs,
+      currentBatch: this._currentBatch,
+      totalBatches: this._totalBatches,
+      specs,
+    };
+  }
+
+  /**
+   * Return the execution status of a specific Spec.
+   *
+   * @param {string} specName
+   * @returns {object|null} SpecExecutionStatus or null if not tracked
+   */
+  getSpecStatus(specName) {
+    const entry = this._specs.get(specName);
+    if (!entry) return null;
+
+    return {
+      status: entry.status,
+      batch: entry.batch,
+      agentId: entry.agentId,
+      retryCount: entry.retryCount,
+      error: entry.error,
+    };
+  }
+
+  /**
+   * Synchronise a Spec's completion status to external systems:
+   * - SpecLifecycleManager: transition Spec status
+   * - ContextSyncManager: update progress entry
+   *
+   * Failures are logged but do not propagate (non-fatal).
+   *
+   * @param {string} specName
+   * @param {string} status - 'completed' | 'failed' | 'timeout' etc.
+   * @returns {Promise<void>}
+   */
+  async syncExternalStatus(specName, status) {
+    // --- SpecLifecycleManager (Req 4.3) ---
+    if (this._specLifecycleManager) {
+      try {
+        const lifecycleStatus = this._mapToLifecycleStatus(status);
+        if (lifecycleStatus) {
+          await this._specLifecycleManager.transition(specName, lifecycleStatus);
+        }
+      } catch (err) {
+        console.warn(
+          `[StatusMonitor] Failed to update SpecLifecycleManager for ${specName}: ${err.message}`
+        );
+      }
+    }
+
+    // --- ContextSyncManager (Req 4.4) ---
+    if (this._contextSyncManager) {
+      try {
+        const progress = status === 'completed' ? 100 : 0;
+        const summary = this._buildProgressSummary(specName, status);
+        await this._contextSyncManager.updateSpecProgress(specName, {
+          status,
+          progress,
+          summary,
+        });
+      } catch (err) {
+        console.warn(
+          `[StatusMonitor] Failed to update ContextSyncManager for ${specName}: ${err.message}`
+        );
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Parse a raw event into a normalised object.
+   * Accepts both string (JSON) and pre-parsed objects.
+   * Returns null for invalid/unparseable input.
+   *
+   * @param {*} event
+   * @returns {object|null}
+   * @private
+   */
+  _parseEvent(event) {
+    if (!event) return null;
+
+    // Already an object
+    if (typeof event === 'object' && event !== null) {
+      return event.type ? event : null;
+    }
+
+    // String — attempt JSON parse
+    if (typeof event === 'string') {
+      try {
+        const parsed = JSON.parse(event);
+        return parsed && typeof parsed === 'object' && parsed.type ? parsed : null;
+      } catch (_err) {
+        return null;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Find the Spec name associated with a given agentId.
+   *
+   * @param {string} agentId
+   * @returns {string|null}
+   * @private
+   */
+  _findSpecByAgentId(agentId) {
+    for (const [specName, entry] of this._specs) {
+      if (entry.agentId === agentId) {
+        return specName;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Process a parsed event and update internal state.
+   *
+   * @param {string|null} specName
+   * @param {string} agentId
+   * @param {object} event
+   * @private
+   */
+  _processEvent(specName, agentId, event) {
+    const type = event.type;
+    if (!type || typeof type !== 'string') return;
+
+    if (type === 'thread.started') {
+      if (specName) {
+        this._updateEntryStatus(specName, 'running');
+      }
+    } else if (type === 'turn.started') {
+      // Track turn activity
+      if (specName) {
+        const entry = this._specs.get(specName);
+        if (entry) {
+          entry.turnCount++;
+        }
+      }
+    } else if (type === 'turn.completed') {
+      // Turn completed — no status change, just tracking
+    } else if (type === 'error') {
+      if (specName) {
+        const errorMsg = event.message || event.error || 'Unknown error';
+        const entry = this._specs.get(specName);
+        if (entry) {
+          entry.error = errorMsg;
+        }
+      }
+    } else if (type.startsWith('item.')) {
+      // item.* events — generic progress tracking, no status change
+    }
+    // Unknown event types are silently ignored
+  }
+
+  /**
+   * Update a Spec entry's status if the Spec is tracked.
+   *
+   * @param {string} specName
+   * @param {string} status
+   * @private
+   */
+  _updateEntryStatus(specName, status) {
+    const entry = this._specs.get(specName);
+    if (entry && VALID_SPEC_STATUSES.has(status)) {
+      entry.status = status;
+    }
+  }
+
+  /**
+   * Map an orchestrator status to a SpecLifecycleManager status.
+   * Returns null if no mapping exists.
+   *
+   * @param {string} status
+   * @returns {string|null}
+   * @private
+   */
+  _mapToLifecycleStatus(status) {
+    switch (status) {
+      case 'running':
+        return 'in-progress';
+      case 'completed':
+        return 'completed';
+      // failed/timeout/skipped have no direct lifecycle mapping
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Build a human-readable progress summary for ContextSyncManager.
+   *
+   * @param {string} specName
+   * @param {string} status
+   * @returns {string}
+   * @private
+   */
+  _buildProgressSummary(specName, status) {
+    switch (status) {
+      case 'completed':
+        return `Spec ${specName} completed successfully`;
+      case 'failed':
+        return `Spec ${specName} failed`;
+      case 'timeout':
+        return `Spec ${specName} timed out`;
+      case 'skipped':
+        return `Spec ${specName} skipped (dependency failed)`;
+      case 'running':
+        return `Spec ${specName} in progress`;
+      default:
+        return `Spec ${specName}: ${status}`;
+    }
+  }
+}
+
+module.exports = { StatusMonitor, VALID_SPEC_STATUSES, VALID_ORCHESTRATION_STATUSES };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.44.0",
+  "version": "1.45.2",
   "description": "kiro-spec-engine (kse) - A CLI tool and npm package for spec-driven development with AI coding assistants. NOT the Kiro IDE desktop application.",
   "main": "index.js",
   "bin": {

package/template/.kiro/README.md

@@ -19,7 +19,7 @@ This project uses **Spec-driven development** - a structured approach where:
 
 ---
 
-## 🚀 kse Capabilities (v1.44.x)
+## 🚀 kse Capabilities (v1.45.x)
 
 **IMPORTANT**: After installing or updating kse, read this section to understand all available capabilities. Using the right tool for the job ensures efficient, high-quality development.
 
@@ -91,6 +91,19 @@ Fourth steering layer (L4) and Spec lifecycle coordination for multi-agent scena
 - `kse auto status/resume/stop/config` — Manage autonomous execution
 - Intelligent error recovery, checkpoint system, learning from history
 
+### Agent Orchestrator — Multi-Agent Spec Execution (v1.45.0)
+Automate parallel Spec execution via Codex CLI sub-agents (replaces manual multi-terminal workflow):
+- `kse orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3` — Start multi-agent orchestration
+- `kse orchestrate status` — View orchestration progress (per-Spec status, overall state)
+- `kse orchestrate stop` — Gracefully stop all sub-agents
+- **OrchestratorConfig** (`lib/orchestrator`) — Configuration management (agent backend, parallelism, timeout, retries) via `.kiro/config/orchestrator.json`
+- **BootstrapPromptBuilder** (`lib/orchestrator`) — Builds bootstrap prompts with Spec path, steering context, execution instructions
+- **AgentSpawner** (`lib/orchestrator`) — Process manager for Codex CLI sub-agents with timeout detection, graceful termination (SIGTERM → SIGKILL)
+- **StatusMonitor** (`lib/orchestrator`) — Codex JSON Lines event parsing, per-Spec status tracking, orchestration-level aggregation
+- **OrchestrationEngine** (`lib/orchestrator`) — DAG-based dependency analysis, batch scheduling, parallel execution (≤ maxParallel), failure propagation, retry mechanism
+- Prerequisites: Codex CLI installed, `CODEX_API_KEY` environment variable set
+- 11 correctness properties verified via property-based testing
+
 ### Scene Runtime (Template Engine + Quality + ERP)
 - **Template Engine**: `kse scene template-validate/resolve/render` — Variable schema, multi-file rendering, 3-layer inheritance
 - **Package Registry**: `kse scene publish/unpublish/install/list/search/info/diff/version` — Local package management