kiro-spec-engine 1.45.12 → 1.45.13

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.45.13] - 2026-02-13
+
+### Fixed
+- **Windows prompt guard hardening**: `AgentSpawner.spawn()` now validates bootstrap prompt both right after prompt build and after Windows prompt extraction, failing fast before any temp file write when prompt is missing/empty.
+- **Windows temp filename safety**: prompt temp filename generation now sanitizes full Windows-invalid character set (including `/`, `\`, control chars, and trailing dot/space cases) to prevent invalid path/stream edge cases.
+- **Codex command fallback**: when `codexCommand` is not configured, spawner now auto-detects `codex` and falls back to `npx @openai/codex` when global `codex` is unavailable.
+
+### Added
+- **Regression tests**: added unit tests for undefined/empty prompt guardrails, Windows agentId filename sanitization, and codex→npx command fallback path.
+- **Codex orchestration docs**: added recommended Codex-only orchestrator configuration examples in README, README.zh, `.kiro/README.md`, and command reference.
+
 ## [1.45.12] - 2026-02-13
 
 ### Fixed

package/README.md

@@ -340,7 +340,7 @@ Structure your work with Requirements → Design → Tasks workflow
 - **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`
+- **Configurable**: Codex command, args, parallelism, timeout, retries via `.kiro/config/orchestrator.json`
 
 **Quick Start**:
 ```bash
@@ -354,6 +354,21 @@ kse orchestrate status
 kse orchestrate stop
 ```
 
+**Recommended Codex-Orchestrator config (`.kiro/config/orchestrator.json`)**:
+```json
+{
+  "agentBackend": "codex",
+  "maxParallel": 3,
+  "timeoutSeconds": 900,
+  "maxRetries": 2,
+  "apiKeyEnvVar": "CODEX_API_KEY",
+  "codexArgs": ["--skip-git-repo-check"],
+  "codexCommand": "npx @openai/codex"
+}
+```
+
+If Codex CLI is globally installed, you can set `"codexCommand": "codex"`.
+
 ### 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
@@ -650,5 +665,5 @@ A deep conversation about AI development trends, Neo-Confucian philosophy, and s
 
 ---
 
-**Version**: 1.45.0  
-**Last Updated**: 2026-02-12
+**Version**: 1.45.13  
+**Last Updated**: 2026-02-13

package/README.zh.md

@@ -296,7 +296,7 @@ sequenceDiagram
 - **重试机制**: 可配置的失败自动重试
 - **实时监控**: 跟踪每个 Spec 状态和整体编排进度
 - **优雅终止**: 干净停止所有子 Agent（SIGTERM → SIGKILL）
-- **可配置**: 通过 `.kiro/config/orchestrator.json` 配置 Agent 后端、并行度、超时、重试次数
+- **可配置**: 通过 `.kiro/config/orchestrator.json` 配置 Codex 命令、参数、并行度、超时、重试次数
 
 **快速开始**:
 ```bash
@@ -310,6 +310,21 @@ kse orchestrate status
 kse orchestrate stop
 ```
 
+**推荐 Codex 编排配置（`.kiro/config/orchestrator.json`）**:
+```json
+{
+  "agentBackend": "codex",
+  "maxParallel": 3,
+  "timeoutSeconds": 900,
+  "maxRetries": 2,
+  "apiKeyEnvVar": "CODEX_API_KEY",
+  "codexArgs": ["--skip-git-repo-check"],
+  "codexCommand": "npx @openai/codex"
+}
+```
+
+如果你已全局安装 Codex CLI，可将 `"codexCommand"` 改为 `"codex"`。
+
 ### Spec 级 Steering 与上下文同步 🚀 v1.44.0 新增
 - **Spec Steering (L4)**: 每个 Spec 独立的 `steering.md`，包含约束、注意事项、决策记录 — 跨 Agent 零冲突
 - **Steering 加载器**: 统一 L1-L4 四层 Steering 加载，优先级合并
@@ -513,5 +528,5 @@ kse create-spec 01-00-my-first-feature
 
 ---
 
-**版本**：1.45.0  
-**最后更新**：2026-02-12
+**版本**：1.45.13  
+**最后更新**：2026-02-13

package/docs/command-reference.md

@@ -2,8 +2,8 @@
 
 > Quick reference for all kse commands
 
-**Version**: 1.42.0  
-**Last Updated**: 2026-02-11
+**Version**: 1.45.13  
+**Last Updated**: 2026-02-13
 
 ---
 
@@ -198,6 +198,33 @@ kse repo exec "<command>" [--dry-run]
 kse repo health [--json]
 ```
 
+### Agent Orchestration (Codex)
+
+```bash
+# Start orchestration for multiple specs
+kse orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3
+
+# Show orchestration status
+kse orchestrate status [--json]
+
+# Stop all running sub-agents
+kse orchestrate stop
+```
+
+Recommended `.kiro/config/orchestrator.json`:
+
+```json
+{
+  "agentBackend": "codex",
+  "maxParallel": 3,
+  "timeoutSeconds": 900,
+  "maxRetries": 2,
+  "apiKeyEnvVar": "CODEX_API_KEY",
+  "codexArgs": ["--skip-git-repo-check"],
+  "codexCommand": "npx @openai/codex"
+}
+```
+
 ### Scene Template Engine
 
 ```bash

package/lib/orchestrator/agent-spawner.js

@@ -12,7 +12,7 @@
  */
 
 const { EventEmitter } = require('events');
-const { spawn } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -30,6 +30,7 @@ class AgentSpawner extends EventEmitter {
     this._orchestratorConfig = orchestratorConfig;
     this._agentRegistry = agentRegistry;
     this._bootstrapPromptBuilder = bootstrapPromptBuilder;
+    this._commandAvailabilityCache = new Map();
     /** @type {Map<string, import('./agent-spawner').SpawnedAgent>} */
     this._agents = new Map();
   }
@@ -63,6 +64,7 @@ class AgentSpawner extends EventEmitter {
 
     // Build the bootstrap prompt (Req 2.1-2.3)
     const prompt = await this._bootstrapPromptBuilder.buildPrompt(specName);
+    this._assertValidBootstrapPrompt(prompt, specName, 'BootstrapPromptBuilder.buildPrompt()');
 
     // Register in AgentRegistry (Req 1.7)
     const { agentId } = await this._agentRegistry.register({
@@ -119,15 +121,7 @@ class AgentSpawner extends EventEmitter {
       // Remove the prompt (last element of args portion) from command line
       // and deliver it via stdin to avoid cmd.exe length limit.
       stdinPrompt = finalArgs.pop(); // remove prompt
-      
-      // Validate stdinPrompt before proceeding
-      if (!stdinPrompt || typeof stdinPrompt !== 'string' || stdinPrompt.length === 0) {
-        throw new Error(
-          `Invalid bootstrap prompt: expected non-empty string, got ${typeof stdinPrompt} ` +
-          `with length ${stdinPrompt ? stdinPrompt.length : 0}. ` +
-          `This may indicate BootstrapPromptBuilder.buildPrompt() failed or args array is malformed.`
-        );
-      }
+      this._assertValidBootstrapPrompt(stdinPrompt, specName, 'Windows prompt extraction');
       
       // If the prompt was quoted by the escaping above, unwrap it
       if (stdinPrompt.startsWith('"') && stdinPrompt.endsWith('"')) {
@@ -144,8 +138,8 @@ class AgentSpawner extends EventEmitter {
     // write prompt → pass file path via shell read.
     let promptTmpFile = null;
     if (useStdinPrompt) {
-      // Sanitize agentId for use in filename - remove Windows reserved characters: < > : " | ? *
-      const safeAgentId = agentId.replace(/[:<>"|?*]/g, '-');
+      // Sanitize agentId for use in filename to avoid Windows invalid path characters.
+      const safeAgentId = this._sanitizeWindowsFilenamePart(agentId);
       promptTmpFile = path.join(os.tmpdir(), `kse-prompt-${safeAgentId}-${Date.now()}.txt`);
       fs.writeFileSync(promptTmpFile, stdinPrompt, 'utf-8');
     }
@@ -258,6 +252,39 @@ class AgentSpawner extends EventEmitter {
   // Private helpers
   // ---------------------------------------------------------------------------
 
+  /**
+   * Ensure bootstrap prompt is a non-empty string before using it in spawn args.
+   * @param {unknown} prompt
+   * @param {string} specName
+   * @param {string} source
+   * @private
+   */
+  _assertValidBootstrapPrompt(prompt, specName, source) {
+    const isString = typeof prompt === 'string';
+    const length = isString ? prompt.length : 0;
+    const hasContent = isString && prompt.trim().length > 0;
+    if (!hasContent) {
+      throw new Error(
+        `Invalid bootstrap prompt for spec "${specName}" from ${source}: ` +
+        `expected non-empty string, got ${typeof prompt} with length ${length}.`
+      );
+    }
+  }
+
+  /**
+   * Convert an arbitrary identifier into a Windows-safe filename segment.
+   * @param {string} value
+   * @returns {string}
+   * @private
+   */
+  _sanitizeWindowsFilenamePart(value) {
+    const sanitized = String(value)
+      .replace(/[<>:"/\\|?*\x00-\x1F]/g, '-')
+      .replace(/[. ]+$/g, '')
+      .slice(0, 120);
+    return sanitized || 'agent';
+  }
+
   /**
    * Parse stdout line-by-line for JSON Lines events.
    * @param {object} agent
@@ -538,13 +565,55 @@ class AgentSpawner extends EventEmitter {
    * @private
    */
   _resolveCodexCommand(config) {
-    const raw = config.codexCommand || 'codex';
+    let raw = config.codexCommand;
+    if (!raw) {
+      if (this._isCommandAvailable('codex')) {
+        raw = 'codex';
+      } else if (this._isCommandAvailable('npx')) {
+        raw = 'npx @openai/codex';
+      } else {
+        // Keep historical default to preserve error semantics on misconfigured hosts.
+        raw = 'codex';
+      }
+    }
+
     const parts = raw.trim().split(/\s+/);
     return {
       command: parts[0],
       prependArgs: parts.slice(1),
     };
   }
+
+  /**
+   * Best-effort command availability probe.
+   * Uses `where` on Windows and `which` on POSIX systems.
+   *
+   * @param {string} command
+   * @returns {boolean}
+   * @private
+   */
+  _isCommandAvailable(command) {
+    if (!command || typeof command !== 'string') {
+      return false;
+    }
+    if (this._commandAvailabilityCache.has(command)) {
+      return this._commandAvailabilityCache.get(command);
+    }
+
+    try {
+      const lookupCmd = process.platform === 'win32' ? 'where' : 'which';
+      const result = spawnSync(lookupCmd, [command], {
+        windowsHide: true,
+        stdio: 'ignore',
+      });
+      const available = result.status === 0;
+      this._commandAvailabilityCache.set(command, available);
+      return available;
+    } catch (_err) {
+      this._commandAvailabilityCache.set(command, false);
+      return false;
+    }
+  }
 }
 
 module.exports = { AgentSpawner };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.45.12",
+  "version": "1.45.13",
   "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": {