kiro-spec-engine 1.47.12 → 1.47.14

package/README.md

@@ -413,6 +413,12 @@ Tip: `kse spec bootstrap|pipeline run|gate run --specs ...` now defaults to this
   "maxParallel": 3,
   "timeoutSeconds": 900,
   "maxRetries": 2,
+  "rateLimitMaxRetries": 6,
+  "rateLimitBackoffBaseMs": 1000,
+  "rateLimitBackoffMaxMs": 30000,
+  "rateLimitAdaptiveParallel": true,
+  "rateLimitParallelFloor": 1,
+  "rateLimitCooldownMs": 30000,
   "apiKeyEnvVar": "CODEX_API_KEY",
   "codexArgs": ["--skip-git-repo-check"],
   "codexCommand": "npx @openai/codex"
@@ -420,6 +426,7 @@ Tip: `kse spec bootstrap|pipeline run|gate run --specs ...` now defaults to this
 ```
 
 If Codex CLI is globally installed, you can set `"codexCommand": "codex"`.
+Use the `rateLimit*` settings to absorb transient 429/too-many-requests failures without stalling orchestration.
 
 ### 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

package/README.zh.md

@@ -367,6 +367,12 @@ kse orchestrate stop
   "maxParallel": 3,
   "timeoutSeconds": 900,
   "maxRetries": 2,
+  "rateLimitMaxRetries": 6,
+  "rateLimitBackoffBaseMs": 1000,
+  "rateLimitBackoffMaxMs": 30000,
+  "rateLimitAdaptiveParallel": true,
+  "rateLimitParallelFloor": 1,
+  "rateLimitCooldownMs": 30000,
   "apiKeyEnvVar": "CODEX_API_KEY",
   "codexArgs": ["--skip-git-repo-check"],
   "codexCommand": "npx @openai/codex"
@@ -374,6 +380,7 @@ kse orchestrate stop
 ```
 
 如果你已全局安装 Codex CLI，可将 `"codexCommand"` 改为 `"codex"`。
+可通过 `rateLimit*` 配置吸收 429/too-many-requests 等限流抖动，避免编排流程卡死。
 
 ### Spec 级 Steering 与上下文同步 🚀 v1.44.0 新增
 - **Spec Steering (L4)**: 每个 Spec 独立的 `steering.md`，包含约束、注意事项、决策记录 — 跨 Agent 零冲突

package/docs/command-reference.md

@@ -787,12 +787,20 @@ Recommended `.kiro/config/orchestrator.json`:
   "maxParallel": 3,
   "timeoutSeconds": 900,
   "maxRetries": 2,
+  "rateLimitMaxRetries": 6,
+  "rateLimitBackoffBaseMs": 1000,
+  "rateLimitBackoffMaxMs": 30000,
+  "rateLimitAdaptiveParallel": true,
+  "rateLimitParallelFloor": 1,
+  "rateLimitCooldownMs": 30000,
   "apiKeyEnvVar": "CODEX_API_KEY",
   "codexArgs": ["--skip-git-repo-check"],
   "codexCommand": "npx @openai/codex"
 }
 ```
 
+`rateLimit*` settings provide dedicated retry/backoff and adaptive parallel throttling when providers return 429 / too-many-requests errors.
+
 ### Scene Template Engine
 
 ```bash

package/lib/commands/orchestrate.js

@@ -124,6 +124,9 @@ async function runOrchestration(options = {}, dependencies = {}) {
     'spec:start',
     'spec:complete',
     'spec:failed',
+    'spec:rate-limited',
+    'parallel:throttled',
+    'parallel:recovered',
     'orchestration:complete'
   ];
 
@@ -322,6 +325,17 @@ function _printStatus(status) {
   if (status.currentBatch !== undefined && status.totalBatches !== undefined) {
     console.log(`Batch: ${status.currentBatch} / ${status.totalBatches}`);
   }
+  if (status.parallel) {
+    const effective = status.parallel.effectiveMaxParallel ?? '-';
+    const max = status.parallel.maxParallel ?? '-';
+    const adaptive = status.parallel.adaptive === false ? 'off' : 'on';
+    console.log(`Parallel: ${effective} / ${max} (adaptive: ${adaptive})`);
+  }
+  if (status.rateLimit) {
+    const signals = status.rateLimit.signalCount || 0;
+    const backoff = status.rateLimit.totalBackoffMs || 0;
+    console.log(`Rate-limit: ${signals} signal(s), total backoff ${backoff}ms`);
+  }
   if (status.specs) {
     console.log('');
     for (const [name, info] of Object.entries(status.specs)) {

package/lib/orchestrator/orchestration-engine.js

@@ -463,6 +463,12 @@ class OrchestrationEngine extends EventEmitter {
         : 0;
       if (retryDelayMs > 0) {
         this._onRateLimitSignal();
+        this._updateStatusMonitorRateLimit({
+          specName,
+          retryCount,
+          retryDelayMs,
+          error: resolvedError,
+        });
         this.emit('spec:rate-limited', {
           specName,
           retryCount,
@@ -650,6 +656,15 @@ class OrchestrationEngine extends EventEmitter {
     this._baseMaxParallel = boundedMax;
     this._effectiveMaxParallel = boundedMax;
     this._rateLimitCooldownUntil = 0;
+    this._updateStatusMonitorParallelTelemetry({
+      adaptive: this._isAdaptiveParallelEnabled(),
+      maxParallel: boundedMax,
+      effectiveMaxParallel: boundedMax,
+      floor: Math.min(
+        boundedMax,
+        this._toPositiveInteger(this._rateLimitParallelFloor, DEFAULT_RATE_LIMIT_PARALLEL_FLOOR)
+      ),
+    });
   }
 
   /**
@@ -659,20 +674,35 @@ class OrchestrationEngine extends EventEmitter {
    */
   _getEffectiveMaxParallel(maxParallel) {
     const boundedMax = this._toPositiveInteger(maxParallel, 1);
+    const floor = Math.min(
+      boundedMax,
+      this._toPositiveInteger(this._rateLimitParallelFloor, DEFAULT_RATE_LIMIT_PARALLEL_FLOOR)
+    );
+
     if (!this._isAdaptiveParallelEnabled()) {
       this._baseMaxParallel = boundedMax;
+      this._effectiveMaxParallel = boundedMax;
+      this._updateStatusMonitorParallelTelemetry({
+        adaptive: false,
+        maxParallel: boundedMax,
+        effectiveMaxParallel: boundedMax,
+        floor,
+      });
       return boundedMax;
     }
 
     this._baseMaxParallel = boundedMax;
     this._maybeRecoverParallelLimit(boundedMax);
 
-    const floor = Math.min(
-      boundedMax,
-      this._toPositiveInteger(this._rateLimitParallelFloor, DEFAULT_RATE_LIMIT_PARALLEL_FLOOR)
-    );
     const effective = this._toPositiveInteger(this._effectiveMaxParallel, boundedMax);
-    return Math.max(floor, Math.min(boundedMax, effective));
+    const resolved = Math.max(floor, Math.min(boundedMax, effective));
+    this._updateStatusMonitorParallelTelemetry({
+      adaptive: true,
+      maxParallel: boundedMax,
+      effectiveMaxParallel: resolved,
+      floor,
+    });
+    return resolved;
   }
 
   /**
@@ -693,6 +723,14 @@ class OrchestrationEngine extends EventEmitter {
 
     if (next < current) {
       this._effectiveMaxParallel = next;
+      this._updateStatusMonitorParallelTelemetry({
+        event: 'throttled',
+        reason: 'rate-limit',
+        adaptive: true,
+        maxParallel: base,
+        effectiveMaxParallel: next,
+        floor,
+      });
       this.emit('parallel:throttled', {
         reason: 'rate-limit',
         previousMaxParallel: current,
@@ -730,6 +768,12 @@ class OrchestrationEngine extends EventEmitter {
     if (next > current) {
       this._effectiveMaxParallel = next;
       this._rateLimitCooldownUntil = this._getNow() + this._rateLimitCooldownMs;
+      this._updateStatusMonitorParallelTelemetry({
+        event: 'recovered',
+        adaptive: true,
+        maxParallel: boundedMax,
+        effectiveMaxParallel: next,
+      });
       this.emit('parallel:recovered', {
         previousMaxParallel: current,
         effectiveMaxParallel: next,
@@ -841,6 +885,40 @@ class OrchestrationEngine extends EventEmitter {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
+  /**
+   * Safely update StatusMonitor rate-limit telemetry.
+   *
+   * @param {object} payload
+   * @private
+   */
+  _updateStatusMonitorRateLimit(payload) {
+    const handler = this._statusMonitor && this._statusMonitor.recordRateLimitEvent;
+    if (typeof handler === 'function') {
+      try {
+        handler.call(this._statusMonitor, payload);
+      } catch (_err) {
+        // Non-fatal status telemetry update.
+      }
+    }
+  }
+
+  /**
+   * Safely update StatusMonitor adaptive parallel telemetry.
+   *
+   * @param {object} payload
+   * @private
+   */
+  _updateStatusMonitorParallelTelemetry(payload) {
+    const handler = this._statusMonitor && this._statusMonitor.updateParallelTelemetry;
+    if (typeof handler === 'function') {
+      try {
+        handler.call(this._statusMonitor, payload);
+      } catch (_err) {
+        // Non-fatal status telemetry update.
+      }
+    }
+  }
+
   /**
    * Validate that all spec directories exist (Req 6.4).
    *

package/lib/orchestrator/status-monitor.js

@@ -56,6 +56,37 @@ class StatusMonitor {
      * @type {Map<string, {status: string, batch: number, agentId: string|null, retryCount: number, error: string|null, turnCount: number}>}
      */
     this._specs = new Map();
+
+    /**
+     * Rate-limit telemetry summary.
+     * @type {{signalCount: number, retryCount: number, totalBackoffMs: number, lastSignalAt: string|null, lastSpecName: string|null, lastRetryCount: number, lastDelayMs: number, lastError: string|null}}
+     */
+    this._rateLimit = {
+      signalCount: 0,
+      retryCount: 0,
+      totalBackoffMs: 0,
+      lastSignalAt: null,
+      lastSpecName: null,
+      lastRetryCount: 0,
+      lastDelayMs: 0,
+      lastError: null,
+    };
+
+    /**
+     * Parallelism telemetry summary.
+     * @type {{adaptive: boolean|null, maxParallel: number|null, effectiveMaxParallel: number|null, floor: number|null, throttledCount: number, recoveredCount: number, lastReason: string|null, lastThrottledAt: string|null, lastRecoveredAt: string|null}}
+     */
+    this._parallel = {
+      adaptive: null,
+      maxParallel: null,
+      effectiveMaxParallel: null,
+      floor: null,
+      throttledCount: 0,
+      recoveredCount: 0,
+      lastReason: null,
+      lastThrottledAt: null,
+      lastRecoveredAt: null,
+    };
   }
 
   // ---------------------------------------------------------------------------
@@ -125,6 +156,80 @@ class StatusMonitor {
     }
   }
 
+  /**
+   * Record a rate-limit retry/backoff signal.
+   *
+   * @param {object} data
+   * @param {string} [data.specName]
+   * @param {number} [data.retryCount]
+   * @param {number} [data.retryDelayMs]
+   * @param {string} [data.error]
+   */
+  recordRateLimitEvent(data = {}) {
+    const delay = Number(data.retryDelayMs);
+    const retryCount = Number(data.retryCount);
+
+    this._rateLimit.signalCount++;
+    this._rateLimit.retryCount++;
+    this._rateLimit.totalBackoffMs += Number.isFinite(delay) && delay > 0 ? Math.round(delay) : 0;
+    this._rateLimit.lastSignalAt = new Date().toISOString();
+
+    if (typeof data.specName === 'string' && data.specName.trim()) {
+      this._rateLimit.lastSpecName = data.specName.trim();
+    }
+    if (Number.isFinite(retryCount) && retryCount >= 0) {
+      this._rateLimit.lastRetryCount = Math.floor(retryCount);
+    }
+    this._rateLimit.lastDelayMs = Number.isFinite(delay) && delay > 0 ? Math.round(delay) : 0;
+    if (data.error !== undefined && data.error !== null) {
+      this._rateLimit.lastError = `${data.error}`;
+    }
+  }
+
+  /**
+   * Update adaptive parallel telemetry.
+   *
+   * @param {object} data
+   * @param {'throttled'|'recovered'} [data.event]
+   * @param {string} [data.reason]
+   * @param {number} [data.maxParallel]
+   * @param {number} [data.effectiveMaxParallel]
+   * @param {number} [data.floor]
+   * @param {boolean} [data.adaptive]
+   */
+  updateParallelTelemetry(data = {}) {
+    if (typeof data.adaptive === 'boolean') {
+      this._parallel.adaptive = data.adaptive;
+    }
+
+    const maxParallel = Number(data.maxParallel);
+    if (Number.isFinite(maxParallel) && maxParallel > 0) {
+      this._parallel.maxParallel = Math.floor(maxParallel);
+    }
+
+    const effective = Number(data.effectiveMaxParallel);
+    if (Number.isFinite(effective) && effective > 0) {
+      this._parallel.effectiveMaxParallel = Math.floor(effective);
+    }
+
+    const floor = Number(data.floor);
+    if (Number.isFinite(floor) && floor > 0) {
+      this._parallel.floor = Math.floor(floor);
+    }
+
+    if (typeof data.reason === 'string' && data.reason.trim()) {
+      this._parallel.lastReason = data.reason.trim();
+    }
+
+    if (data.event === 'throttled') {
+      this._parallel.throttledCount++;
+      this._parallel.lastThrottledAt = new Date().toISOString();
+    } else if (data.event === 'recovered') {
+      this._parallel.recoveredCount++;
+      this._parallel.lastRecoveredAt = new Date().toISOString();
+    }
+  }
+
   /**
    * Set the overall orchestration state.
    *
@@ -219,6 +324,8 @@ class StatusMonitor {
       currentBatch: this._currentBatch,
       totalBatches: this._totalBatches,
       specs,
+      rateLimit: { ...this._rateLimit },
+      parallel: { ...this._parallel },
     };
   }
 

package/package.json

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