kiro-spec-engine 1.44.0 → 1.45.2

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.45.2] - 2026-02-13
+
+### Fixed
+- **AgentSpawner auth fallback**: Added `~/.codex/auth.json` fallback when `CODEX_API_KEY` env var is not set, supporting users who configured auth via `codex auth`
+- **AgentSpawner codex command**: Added `codexCommand` config option (e.g. `"npx @openai/codex"`) for users without global Codex CLI install
+- **OrchestratorConfig**: Added `codexCommand` to known config keys and defaults
+
+## [1.45.1] - 2026-02-12
+
+### Fixed
+- **StatusMonitor property test**: Replaced `fc.date()` with `fc.integer`-based timestamp generator to prevent `Invalid Date` during fast-check shrinking
+- **ExecutionLogger rotation test**: Replaced `Array(200000).fill() + JSON.stringify` with string repeat for large file generation, fixing CI timeout (10s → 45ms)
+
+## [1.45.0] - 2026-02-12
+
+### Added
+- **Agent Orchestrator**: Multi-agent parallel Spec execution via Codex CLI
+  - **OrchestratorConfig** (`lib/orchestrator/orchestrator-config.js`): Configuration management for orchestrator settings (agent backend, parallelism, timeout, retries)
+  - **BootstrapPromptBuilder** (`lib/orchestrator/bootstrap-prompt-builder.js`): Builds bootstrap prompts with Spec path, steering context, and execution instructions for sub-agents
+  - **AgentSpawner** (`lib/orchestrator/agent-spawner.js`): Process manager for Codex CLI sub-agents with timeout detection, graceful termination (SIGTERM → SIGKILL), and event emission
+  - **StatusMonitor** (`lib/orchestrator/status-monitor.js`): Codex JSON Lines event parsing, per-Spec status tracking, orchestration-level status aggregation
+  - **OrchestrationEngine** (`lib/orchestrator/orchestration-engine.js`): Core engine with DAG-based dependency analysis, batch scheduling, parallel execution (≤ maxParallel), failure propagation, and retry mechanism
+  - **CLI Commands** (`kse orchestrate`):
+    - `kse orchestrate run --specs "spec-a,spec-b" --max-parallel 3` — Start multi-agent orchestration
+    - `kse orchestrate status` — View orchestration progress
+    - `kse orchestrate stop` — Gracefully stop all sub-agents
+  - 11 correctness properties verified via property-based testing (fast-check)
+  - 236+ new tests across unit, property, and integration test suites
+
+### Fixed
+- **StatusMonitor property test**: Fixed `fc.date()` generating invalid dates causing `RangeError: Invalid time value` in `toISOString()` — constrained date range to 2000-2100
+
 ## [1.44.0] - 2026-02-12
 
 ### Added

package/README.md

@@ -332,6 +332,28 @@ Structure your work with Requirements → Design → Tasks workflow
 
 [Learn more about Multi-Agent Coordination →](docs/multi-agent-coordination-guide.md)
 
+### Agent Orchestrator 🚀 NEW in v1.45.0
+- **Automated Multi-Agent Spec Execution**: Replace manual multi-terminal workflows with a single command
+- **DAG-Based Scheduling**: Analyze Spec dependencies, compute execution batches via topological sort
+- **Parallel Execution**: Run up to N Specs simultaneously via Codex CLI sub-agents (`--max-parallel`)
+- **Failure Propagation**: Failed Spec's dependents automatically marked as skipped
+- **Retry Mechanism**: Configurable automatic retry for failed Specs
+- **Real-Time Monitoring**: Track per-Spec status and overall orchestration progress
+- **Graceful Termination**: Stop all sub-agents cleanly (SIGTERM → SIGKILL)
+- **Configurable**: Agent backend, parallelism, timeout, retries via `.kiro/config/orchestrator.json`
+
+**Quick Start**:
+```bash
+# Run 3 Specs in parallel via Codex CLI
+kse orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3
+
+# Check orchestration progress
+kse orchestrate status
+
+# Stop all sub-agents
+kse orchestrate stop
+```
+
 ### Spec-Level Steering & Context Sync 🚀 NEW in v1.44.0
 - **Spec Steering (L4)**: Independent `steering.md` per Spec with constraints, notes, and decisions — zero cross-agent conflict
 - **Steering Loader**: Unified L1-L4 four-layer steering loader with priority-based merging
@@ -500,6 +522,11 @@ kse scene ontology lineage --ref <ref>         # Show data lineage
 kse scene ontology agent-info --package <path> # Show agent hints
 kse scene contribute --package <path>          # One-stop validate → lint → score → publish
 
+# Agent orchestration (NEW in v1.45.0)
+kse orchestrate run --specs "<spec-list>" --max-parallel <N>  # Start multi-agent orchestration
+kse orchestrate status                         # View orchestration progress
+kse orchestrate stop                           # Stop all sub-agents
+
 # DevOps operations
 kse ops init <project-name>        # Initialize operations specs
 kse ops validate [<project>]       # Validate operations completeness
@@ -623,5 +650,5 @@ A deep conversation about AI development trends, Neo-Confucian philosophy, and s
 
 ---
 
-**Version**: 1.43.0  
-**Last Updated**: 2026-02-11
+**Version**: 1.45.0  
+**Last Updated**: 2026-02-12

package/README.zh.md

@@ -288,6 +288,28 @@ sequenceDiagram
 
 [了解更多多 Agent 协调 →](docs/multi-agent-coordination-guide.md)
 
+### Agent 编排器 🚀 v1.45.0 新增
+- **自动化多 Agent Spec 执行**: 一条命令替代手工开多个终端分配 Spec 给 Codex Agent
+- **DAG 依赖调度**: 分析 Spec 间依赖关系，拓扑排序计算执行批次
+- **并行执行**: 通过 Codex CLI 子进程同时运行多个 Spec（`--max-parallel` 控制并行度）
+- **失败传播**: 失败 Spec 的下游依赖自动标记为 skipped
+- **重试机制**: 可配置的失败自动重试
+- **实时监控**: 跟踪每个 Spec 状态和整体编排进度
+- **优雅终止**: 干净停止所有子 Agent（SIGTERM → SIGKILL）
+- **可配置**: 通过 `.kiro/config/orchestrator.json` 配置 Agent 后端、并行度、超时、重试次数
+
+**快速开始**:
+```bash
+# 并行运行 3 个 Spec
+kse orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3
+
+# 查看编排进度
+kse orchestrate status
+
+# 停止所有子 Agent
+kse orchestrate stop
+```
+
 ### Spec 级 Steering 与上下文同步 🚀 v1.44.0 新增
 - **Spec Steering (L4)**: 每个 Spec 独立的 `steering.md`，包含约束、注意事项、决策记录 — 跨 Agent 零冲突
 - **Steering 加载器**: 统一 L1-L4 四层 Steering 加载，优先级合并
@@ -403,6 +425,11 @@ kse scene ontology actions --ref <ref>         # 显示 Action Abstraction
 kse scene ontology lineage --ref <ref>         # 显示数据血缘
 kse scene ontology agent-info --package <path> # 显示 Agent Hints
 
+# Agent 编排 (v1.45.0 新增)
+kse orchestrate run --specs "<spec列表>" --max-parallel <N>  # 启动多 Agent 编排
+kse orchestrate status                         # 查看编排进度
+kse orchestrate stop                           # 停止所有子 Agent
+
 # DevOps 运维
 kse ops init <project-name>        # 初始化运维 specs
 kse ops validate [<project>]       # 验证运维完整性
@@ -486,5 +513,5 @@ kse create-spec 01-00-my-first-feature
 
 ---
 
-**版本**：1.43.0  
-**最后更新**：2026-02-11
+**版本**：1.45.0  
+**最后更新**：2026-02-12

package/bin/kiro-spec-engine.js

@@ -571,6 +571,10 @@ registerLockCommands(program);
 const { registerKnowledgeCommands } = require('../lib/commands/knowledge');
 registerKnowledgeCommands(program);
 
+// Orchestration commands
+const { registerOrchestrateCommands } = require('../lib/commands/orchestrate');
+registerOrchestrateCommands(program);
+
 // Template management commands
 const templatesCommand = require('../lib/commands/templates');
 

package/lib/commands/orchestrate.js

@@ -0,0 +1,315 @@
+/**
+ * CLI commands for Agent Orchestration
+ *
+ * Provides `kse orchestrate run|status|stop` subcommands for managing
+ * parallel Spec execution via Codex CLI sub-agents.
+ *
+ * Requirements: 6.1 (run), 6.2 (status), 6.3 (stop), 6.4 (spec validation), 6.5 (maxParallel validation)
+ */
+
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs-extra');
+
+const SPECS_DIR = '.kiro/specs';
+const STATUS_FILE = '.kiro/config/orchestration-status.json';
+
+/**
+ * Register orchestrate commands on the given Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerOrchestrateCommands(program) {
+  const orchestrate = program
+    .command('orchestrate')
+    .description('Manage agent orchestration for parallel Spec execution');
+
+  // ── kse orchestrate run ──────────────────────────────────────────
+  orchestrate
+    .command('run')
+    .description('Start orchestration for specified Specs')
+    .requiredOption('--specs <specs>', 'Comma-separated list of Spec names')
+    .option('--max-parallel <n>', 'Maximum parallel agents', parseInt)
+    .option('--json', 'Output in JSON format')
+    .action(async (options) => {
+      try {
+        const workspaceRoot = process.cwd();
+        const specNames = options.specs
+          .split(',')
+          .map(s => s.trim())
+          .filter(Boolean);
+
+        if (specNames.length === 0) {
+          _errorAndExit('No specs specified', options.json);
+        }
+
+        // Validate maxParallel
+        const maxParallel = options.maxParallel;
+        if (maxParallel !== undefined && (isNaN(maxParallel) || maxParallel < 1)) {
+          _errorAndExit('--max-parallel must be >= 1', options.json);
+        }
+
+        // Validate spec existence
+        const missing = await _validateSpecs(workspaceRoot, specNames);
+        if (missing.length > 0) {
+          _errorAndExit(
+            `Specs not found: ${missing.join(', ')}`,
+            options.json
+          );
+        }
+
+        // Lazy-require orchestrator modules
+        const { OrchestratorConfig } = require('../orchestrator/orchestrator-config');
+        const { BootstrapPromptBuilder } = require('../orchestrator/bootstrap-prompt-builder');
+        const { AgentSpawner } = require('../orchestrator/agent-spawner');
+        const { StatusMonitor } = require('../orchestrator/status-monitor');
+        const { OrchestrationEngine } = require('../orchestrator/orchestration-engine');
+
+        // Lazy-require collab modules
+        const DependencyManager = require('../collab/dependency-manager');
+        const MetadataManager = require('../collab/metadata-manager');
+        const { AgentRegistry } = require('../collab/agent-registry');
+        const { SpecLifecycleManager } = require('../collab/spec-lifecycle-manager');
+        const { MachineIdentifier } = require('../lock/machine-identifier');
+
+        // Optional: ContextSyncManager
+        let contextSyncManager = null;
+        try {
+          const { ContextSyncManager } = require('../steering/context-sync-manager');
+          contextSyncManager = new ContextSyncManager(workspaceRoot);
+        } catch (_err) {
+          // Non-fatal — status sync will be skipped
+        }
+
+        // Wire dependencies
+        const orchestratorConfig = new OrchestratorConfig(workspaceRoot);
+        const config = await orchestratorConfig.getConfig();
+        const effectiveMaxParallel = maxParallel || config.maxParallel;
+
+        const bootstrapPromptBuilder = new BootstrapPromptBuilder(workspaceRoot, orchestratorConfig);
+        const machineIdentifier = new MachineIdentifier(
+          path.join(workspaceRoot, '.kiro', 'config')
+        );
+        const agentRegistry = new AgentRegistry(workspaceRoot, machineIdentifier);
+        const agentSpawner = new AgentSpawner(
+          workspaceRoot, orchestratorConfig, agentRegistry, bootstrapPromptBuilder
+        );
+        const metadataManager = new MetadataManager(workspaceRoot);
+        const dependencyManager = new DependencyManager(metadataManager);
+        const specLifecycleManager = new SpecLifecycleManager(
+          workspaceRoot, contextSyncManager, agentRegistry
+        );
+        const statusMonitor = new StatusMonitor(specLifecycleManager, contextSyncManager);
+
+        const engine = new OrchestrationEngine(workspaceRoot, {
+          agentSpawner,
+          dependencyManager,
+          specLifecycleManager,
+          statusMonitor,
+          orchestratorConfig,
+          agentRegistry,
+        });
+
+        if (!options.json) {
+          console.log(
+            chalk.blue('🚀'),
+            `Starting orchestration for ${specNames.length} spec(s) (max-parallel: ${effectiveMaxParallel})...`
+          );
+        }
+
+        const result = await engine.start(specNames, { maxParallel: effectiveMaxParallel });
+
+        // Persist status for the `status` subcommand
+        await _writeStatus(workspaceRoot, engine.getStatus());
+
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          _printResult(result);
+        }
+
+        if (result.status === 'failed') {
+          process.exit(1);
+        }
+      } catch (err) {
+        _errorAndExit(err.message, options.json);
+      }
+    });
+
+  // ── kse orchestrate status ───────────────────────────────────────
+  orchestrate
+    .command('status')
+    .description('Show current orchestration status')
+    .option('--json', 'Output in JSON format')
+    .action(async (options) => {
+      try {
+        const workspaceRoot = process.cwd();
+        const status = await _readStatus(workspaceRoot);
+
+        if (!status) {
+          if (options.json) {
+            console.log(JSON.stringify({ status: 'idle', message: 'No orchestration data found' }));
+          } else {
+            console.log(chalk.gray('No orchestration data found. Run `kse orchestrate run` first.'));
+          }
+          return;
+        }
+
+        if (options.json) {
+          console.log(JSON.stringify(status, null, 2));
+        } else {
+          _printStatus(status);
+        }
+      } catch (err) {
+        _errorAndExit(err.message, options.json);
+      }
+    });
+
+  // ── kse orchestrate stop ─────────────────────────────────────────
+  orchestrate
+    .command('stop')
+    .description('Stop all running agents')
+    .action(async () => {
+      try {
+        const workspaceRoot = process.cwd();
+        const status = await _readStatus(workspaceRoot);
+
+        if (!status || status.status !== 'running') {
+          console.log(chalk.gray('No running orchestration to stop.'));
+          return;
+        }
+
+        // Write a stop signal into the status file
+        status.status = 'stopped';
+        status.completedAt = new Date().toISOString();
+        await _writeStatus(workspaceRoot, status);
+
+        console.log(chalk.yellow('⏹'), 'Stop signal sent. Running agents will be terminated.');
+      } catch (err) {
+        console.error(chalk.red('Error:'), err.message);
+        process.exit(1);
+      }
+    });
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Validate that all spec directories exist.
+ * @param {string} workspaceRoot
+ * @param {string[]} specNames
+ * @returns {Promise<string[]>} Missing spec names
+ */
+async function _validateSpecs(workspaceRoot, specNames) {
+  const missing = [];
+  for (const name of specNames) {
+    const specDir = path.join(workspaceRoot, SPECS_DIR, name);
+    const exists = await fs.pathExists(specDir);
+    if (!exists) {
+      missing.push(name);
+    }
+  }
+  return missing;
+}
+
+/**
+ * Read persisted orchestration status.
+ * @param {string} workspaceRoot
+ * @returns {Promise<object|null>}
+ */
+async function _readStatus(workspaceRoot) {
+  const statusPath = path.join(workspaceRoot, STATUS_FILE);
+  try {
+    return await fs.readJson(statusPath);
+  } catch (_err) {
+    return null;
+  }
+}
+
+/**
+ * Persist orchestration status to disk.
+ * @param {string} workspaceRoot
+ * @param {object} status
+ */
+async function _writeStatus(workspaceRoot, status) {
+  const statusPath = path.join(workspaceRoot, STATUS_FILE);
+  await fs.ensureDir(path.dirname(statusPath));
+  await fs.writeJson(statusPath, status, { spaces: 2 });
+}
+
+/**
+ * Print a human-readable orchestration result.
+ * @param {object} result
+ */
+function _printResult(result) {
+  const icon = result.status === 'completed' ? chalk.green('✓') : chalk.red('✗');
+  console.log(`${icon} Orchestration ${result.status}`);
+  if (result.totalSpecs !== undefined) {
+    console.log(chalk.gray(`  Total: ${result.totalSpecs}  Completed: ${result.completedSpecs}  Failed: ${result.failedSpecs}`));
+  }
+  if (result.specs) {
+    for (const [name, info] of Object.entries(result.specs)) {
+      const sym = _statusSymbol(info.status);
+      const extra = info.error ? chalk.gray(` — ${info.error}`) : '';
+      console.log(`  ${sym} ${name}${extra}`);
+    }
+  }
+}
+
+/**
+ * Print a human-readable orchestration status.
+ * @param {object} status
+ */
+function _printStatus(status) {
+  console.log(chalk.bold('Orchestration Status'));
+  console.log(chalk.gray('===================='));
+  console.log(`Status: ${_statusSymbol(status.status)} ${status.status}`);
+  if (status.totalSpecs !== undefined) {
+    console.log(`Total: ${status.totalSpecs}  Completed: ${status.completedSpecs || 0}  Failed: ${status.failedSpecs || 0}  Running: ${status.runningSpecs || 0}`);
+  }
+  if (status.currentBatch !== undefined && status.totalBatches !== undefined) {
+    console.log(`Batch: ${status.currentBatch} / ${status.totalBatches}`);
+  }
+  if (status.specs) {
+    console.log('');
+    for (const [name, info] of Object.entries(status.specs)) {
+      const sym = _statusSymbol(info.status);
+      const extra = info.error ? chalk.gray(` — ${info.error}`) : '';
+      console.log(`  ${sym} ${name}${extra}`);
+    }
+  }
+}
+
+/**
+ * Map status string to a coloured symbol.
+ * @param {string} status
+ * @returns {string}
+ */
+function _statusSymbol(status) {
+  const map = {
+    completed: chalk.green('✓'),
+    running: chalk.yellow('⧗'),
+    pending: chalk.gray('○'),
+    failed: chalk.red('✗'),
+    timeout: chalk.red('⏱'),
+    skipped: chalk.gray('⊘'),
+    idle: chalk.gray('○'),
+    stopped: chalk.yellow('⏹'),
+  };
+  return map[status] || '?';
+}
+
+/**
+ * Print an error and exit. Respects --json mode.
+ * @param {string} message
+ * @param {boolean} [json]
+ */
+function _errorAndExit(message, json) {
+  if (json) {
+    console.log(JSON.stringify({ error: message }));
+  } else {
+    console.error(chalk.red('Error:'), message);
+  }
+  process.exit(1);
+}
+
+module.exports = { registerOrchestrateCommands };