scene-capability-engine 3.6.32 → 3.6.36

package/lib/auto/close-loop-controller-service.js

@@ -0,0 +1,287 @@
+async function runCloseLoopController(queueFile, options = {}, context = {}, dependencies = {}) {
+  const {
+    loadControllerGoalQueue,
+    normalizeControllerMaxCycles,
+    normalizeControllerMaxMinutes,
+    normalizeControllerPollSeconds,
+    normalizeControllerDequeueLimit,
+    writeControllerGoalQueue,
+    acquireControllerLock,
+    refreshControllerLock,
+    releaseControllerLock,
+    sleepForMs,
+    executeCloseLoopProgramGoal,
+    appendControllerGoalArchive,
+    maybePersistCloseLoopControllerSummary,
+    maybeWriteOutput,
+    now = () => Date.now()
+  } = dependencies;
+
+  const clock = typeof now === 'function' ? now : () => Date.now();
+  const projectPath = context.projectPath || process.cwd();
+  const resumedSession = context.resumedSession || null;
+  const queueInput = typeof queueFile === 'string' && queueFile.trim()
+    ? queueFile.trim()
+    : resumedSession && resumedSession.payload && typeof resumedSession.payload.queue_file === 'string'
+      ? resumedSession.payload.queue_file
+      : null;
+  const queueFormatCandidate = (
+    options.queueFormat === 'auto' &&
+    resumedSession &&
+    resumedSession.payload &&
+    typeof resumedSession.payload.queue_format === 'string' &&
+    resumedSession.payload.queue_format.trim()
+  )
+    ? resumedSession.payload.queue_format
+    : options.queueFormat;
+  const queuePayload = await loadControllerGoalQueue(projectPath, queueInput, queueFormatCandidate, {
+    dedupe: options.controllerDedupe !== false
+  });
+  const maxCycles = normalizeControllerMaxCycles(options.maxCycles);
+  const maxMinutes = normalizeControllerMaxMinutes(options.maxMinutes);
+  const maxDurationMs = maxMinutes * 60 * 1000;
+  const pollSeconds = normalizeControllerPollSeconds(options.pollSeconds);
+  const dequeueLimit = normalizeControllerDequeueLimit(options.dequeueLimit);
+  const waitOnEmpty = Boolean(options.waitOnEmpty);
+  const stopOnGoalFailure = Boolean(options.stopOnGoalFailure);
+  const startedAtMs = clock();
+  const startedAtIso = new Date(startedAtMs).toISOString();
+  const history = [];
+  const results = [];
+  let performedCycles = 0;
+  let stopReason = 'completed';
+  let exhausted = false;
+  let haltRequested = false;
+  let doneArchiveFile = null;
+  let failedArchiveFile = null;
+  let dedupeDroppedGoals = Number(queuePayload.duplicate_count) || 0;
+  let lockState = null;
+
+  if (options.controllerDedupe !== false && queuePayload.duplicate_count > 0) {
+    await writeControllerGoalQueue(queuePayload.file, queuePayload.format, queuePayload.goals);
+  }
+
+  lockState = await acquireControllerLock(projectPath, queuePayload.file, options);
+
+  try {
+    for (let cycle = 1; cycle <= maxCycles; cycle += 1) {
+      if ((clock() - startedAtMs) >= maxDurationMs) {
+        exhausted = true;
+        stopReason = 'time-budget-exhausted';
+        break;
+      }
+
+      await refreshControllerLock(lockState);
+
+      const currentQueue = await loadControllerGoalQueue(projectPath, queuePayload.file, queuePayload.format, {
+        dedupe: options.controllerDedupe !== false
+      });
+      const pendingGoals = currentQueue.goals;
+      dedupeDroppedGoals += Number(currentQueue.duplicate_count) || 0;
+
+      if (options.controllerDedupe !== false && currentQueue.duplicate_count > 0) {
+        await writeControllerGoalQueue(currentQueue.file, currentQueue.format, pendingGoals);
+      }
+
+      if (pendingGoals.length === 0) {
+        history.push({
+          cycle,
+          queue_before: 0,
+          dequeued: 0,
+          queue_after: 0,
+          status: waitOnEmpty ? 'idle-wait' : 'empty-stop'
+        });
+        performedCycles += 1;
+        if (!waitOnEmpty) {
+          stopReason = 'queue-empty';
+          break;
+        }
+        await sleepForMs(pollSeconds * 1000);
+        continue;
+      }
+
+      const effectiveDequeueLimit = dequeueLimit === null ? pendingGoals.length : dequeueLimit;
+      const dequeuedGoals = pendingGoals.slice(0, effectiveDequeueLimit);
+      const remainingGoals = pendingGoals.slice(dequeuedGoals.length);
+      await writeControllerGoalQueue(currentQueue.file, currentQueue.format, remainingGoals);
+
+      const cycleRecord = {
+        cycle,
+        queue_before: pendingGoals.length,
+        dequeued: dequeuedGoals.length,
+        queue_after: remainingGoals.length,
+        processed: 0,
+        completed: 0,
+        failed: 0,
+        status: 'processed'
+      };
+
+      for (let index = 0; index < dequeuedGoals.length; index += 1) {
+        const goal = dequeuedGoals[index];
+        const goalStartedAt = clock();
+        let goalResult = {
+          cycle,
+          queue_index: index + 1,
+          goal,
+          status: 'failed',
+          error: null
+        };
+
+        try {
+          const perGoalOptions = {
+            ...options,
+            out: null,
+            programKpiOut: null,
+            programAuditOut: null,
+            json: false
+          };
+          const programResult = await executeCloseLoopProgramGoal(goal, perGoalOptions, {
+            projectPath,
+            printSummary: options.controllerPrintProgramSummary === true,
+            writeOutputs: false
+          });
+          const programSummary = programResult.summary || {};
+          const failed = programResult.exitCode !== 0;
+          goalResult = {
+            ...goalResult,
+            status: failed ? 'failed' : 'completed',
+            program_status: programSummary.status || null,
+            program_gate_passed: Boolean(
+              programSummary.program_gate_effective &&
+              programSummary.program_gate_effective.passed
+            ),
+            governance_stop_reason: programSummary.program_governance
+              ? programSummary.program_governance.stop_reason
+              : null,
+            batch_session_file: programSummary.batch_session && programSummary.batch_session.file
+              ? programSummary.batch_session.file
+              : null
+          };
+        } catch (error) {
+          goalResult.error = error.message;
+        }
+
+        goalResult.elapsed_ms = Math.max(0, clock() - goalStartedAt);
+        results.push(goalResult);
+        cycleRecord.processed += 1;
+
+        if (goalResult.status === 'completed') {
+          cycleRecord.completed += 1;
+          doneArchiveFile = await appendControllerGoalArchive(
+            options.controllerDoneFile,
+            projectPath,
+            goal,
+            {
+              status: 'completed',
+              program_status: goalResult.program_status,
+              gate_passed: goalResult.program_gate_passed
+            }
+          ) || doneArchiveFile;
+        } else {
+          cycleRecord.failed += 1;
+          failedArchiveFile = await appendControllerGoalArchive(
+            options.controllerFailedFile,
+            projectPath,
+            goal,
+            {
+              status: 'failed',
+              program_status: goalResult.program_status,
+              gate_passed: goalResult.program_gate_passed
+            }
+          ) || failedArchiveFile;
+          if (stopOnGoalFailure) {
+            haltRequested = true;
+          }
+        }
+
+        if (haltRequested) {
+          break;
+        }
+      }
+
+      if (haltRequested) {
+        cycleRecord.status = 'stopped-on-goal-failure';
+        stopReason = 'goal-failure';
+      }
+      history.push(cycleRecord);
+      performedCycles += 1;
+
+      if (haltRequested) {
+        break;
+      }
+    }
+  } finally {
+    await releaseControllerLock(lockState);
+  }
+
+  const finalQueue = await loadControllerGoalQueue(projectPath, queuePayload.file, queuePayload.format, {
+    dedupe: options.controllerDedupe !== false
+  });
+  const pendingGoals = finalQueue.goals.length;
+  dedupeDroppedGoals += Number(finalQueue.duplicate_count) || 0;
+  if (options.controllerDedupe !== false && finalQueue.duplicate_count > 0) {
+    await writeControllerGoalQueue(finalQueue.file, finalQueue.format, finalQueue.goals);
+  }
+
+  if (!exhausted && stopReason === 'completed') {
+    if (performedCycles >= maxCycles && (pendingGoals > 0 || waitOnEmpty)) {
+      exhausted = true;
+      stopReason = 'cycle-limit-reached';
+    } else if (pendingGoals === 0 && results.length === 0) {
+      stopReason = 'queue-empty';
+    }
+  }
+
+  const completedGoals = results.filter(item => item.status === 'completed').length;
+  const failedGoals = results.filter(item => item.status !== 'completed').length;
+  const status = failedGoals === 0
+    ? 'completed'
+    : completedGoals === 0
+      ? 'failed'
+      : 'partial-failed';
+  const summary = {
+    mode: 'auto-close-loop-controller',
+    status,
+    queue_file: queuePayload.file,
+    queue_format: queuePayload.format,
+    started_at: startedAtIso,
+    completed_at: new Date(clock()).toISOString(),
+    elapsed_ms: Math.max(0, clock() - startedAtMs),
+    wait_on_empty: waitOnEmpty,
+    poll_seconds: pollSeconds,
+    dequeue_limit: dequeueLimit === null ? 'all' : dequeueLimit,
+    max_cycles: maxCycles,
+    max_minutes: maxMinutes,
+    cycles_performed: performedCycles,
+    exhausted,
+    stop_reason: stopReason,
+    processed_goals: results.length,
+    completed_goals: completedGoals,
+    failed_goals: failedGoals,
+    pending_goals: pendingGoals,
+    dedupe_enabled: options.controllerDedupe !== false,
+    dedupe_dropped_goals: dedupeDroppedGoals,
+    lock_enabled: options.controllerLock !== false,
+    lock_file: lockState && lockState.file ? lockState.file : null,
+    lock_ttl_seconds: lockState && Number.isInteger(lockState.ttl_seconds) ? lockState.ttl_seconds : null,
+    resumed_from_controller_session: resumedSession
+      ? {
+          id: resumedSession.id,
+          file: resumedSession.file || null,
+          created_at: resumedSession.created_at || null
+        }
+      : null,
+    done_archive_file: doneArchiveFile,
+    failed_archive_file: failedArchiveFile,
+    history,
+    results
+  };
+
+  await maybePersistCloseLoopControllerSummary(summary, options, projectPath);
+  await maybeWriteOutput(summary, options.controllerOut, projectPath);
+  return summary;
+}
+
+module.exports = {
+  runCloseLoopController
+};

package/lib/auto/close-loop-program-service.js

@@ -0,0 +1,283 @@
+async function executeCloseLoopProgramGoal(goal, options = {}, context = {}, dependencies = {}) {
+  const {
+    normalizeRecoverMaxRounds,
+    normalizeRecoverMaxMinutes,
+    normalizeResumeStrategy,
+    normalizeProgramGovernMaxRounds,
+    normalizeProgramGovernMaxMinutes,
+    normalizeProgramGovernAnomalyWeeks,
+    normalizeAutoKpiTrendPeriod,
+    normalizeProgramGovernUseAction,
+    resolveProgramGatePolicy,
+    normalizeProgramGateFallbackProfile,
+    resolveProgramGateFallbackChain,
+    resolveRecoveryMemoryScope,
+    normalizeBatchRetryMaxRounds,
+    normalizeBatchSessionKeep,
+    normalizeBatchSessionOlderThanDays,
+    normalizeSpecKeep,
+    normalizeOlderThanDays,
+    normalizeSpecSessionProtectWindowDays,
+    normalizeSpecSessionMaxTotal,
+    normalizeSpecSessionMaxCreated,
+    normalizeSpecSessionMaxCreatedPerGoal,
+    normalizeSpecSessionMaxDuplicateGoals,
+    sanitizeBatchSessionId,
+    buildCloseLoopBatchGoalsFromGoal,
+    executeCloseLoopBatch,
+    executeCloseLoopRecoveryCycle,
+    mergeProgramRecoveryIntoProgramSummary,
+    buildProgramKpiSnapshot,
+    buildProgramDiagnostics,
+    buildProgramCoordinationSnapshot,
+    maybeWriteProgramKpi,
+    maybeWriteOutput,
+    maybePersistCloseLoopBatchSummary,
+    applyProgramGateOutcome,
+    runProgramGovernanceLoop,
+    isSpecSessionBudgetHardFailure,
+    isSpecSessionGrowthGuardHardFailure,
+    maybeWriteProgramAudit,
+    printCloseLoopBatchSummary,
+    now = () => Date.now(),
+    cwd = () => process.cwd()
+  } = dependencies;
+
+  const programStartedAt = now();
+  const projectPath = context.projectPath || cwd();
+  const shouldPrintSummary = context.printSummary !== false;
+  const writeOutputs = context.writeOutputs !== false;
+  const programAutonomousEnabled = options.batchAutonomous !== false;
+  const programAutoRecoverEnabled = options.programAutoRecover !== false;
+  const programRecoverMaxRounds = normalizeRecoverMaxRounds(options.programRecoverMaxRounds);
+  const programRecoverMaxMinutes = normalizeRecoverMaxMinutes(options.programRecoverMaxMinutes, '--program-recover-max-minutes');
+  const programRecoverResumeStrategy = normalizeResumeStrategy(options.programRecoverResumeStrategy);
+  const programGovernUntilStable = Boolean(options.programGovernUntilStable);
+  const programGovernMaxRounds = normalizeProgramGovernMaxRounds(options.programGovernMaxRounds);
+  const programGovernMaxMinutes = normalizeProgramGovernMaxMinutes(options.programGovernMaxMinutes);
+  const programGovernAnomalyEnabled = options.programGovernAnomaly !== false;
+  const programGovernAnomalyWeeks = normalizeProgramGovernAnomalyWeeks(options.programGovernAnomalyWeeks);
+  const programGovernAnomalyPeriod = normalizeAutoKpiTrendPeriod(options.programGovernAnomalyPeriod);
+  const programGovernUseAction = normalizeProgramGovernUseAction(options.programGovernUseAction);
+  const programGovernAutoActionEnabled = options.programGovernAutoAction !== false;
+  const programGatePolicy = resolveProgramGatePolicy({
+    profile: options.programGateProfile,
+    minSuccessRate: options.programMinSuccessRate,
+    maxRiskLevel: options.programMaxRiskLevel,
+    maxElapsedMinutes: options.programMaxElapsedMinutes,
+    maxAgentBudget: options.programMaxAgentBudget,
+    maxTotalSubSpecs: options.programMaxTotalSubSpecs
+  });
+  const gateFallbackProfile = normalizeProgramGateFallbackProfile(options.programGateFallbackProfile);
+  const gateFallbackChain = resolveProgramGateFallbackChain(options.programGateFallbackChain, gateFallbackProfile);
+  const recoveryMemoryScope = await resolveRecoveryMemoryScope(projectPath, options.recoveryMemoryScope);
+  if (options.resume) {
+    throw new Error('--resume is not supported in close-loop-program. Use close-loop --resume or remove --resume.');
+  }
+  if (options.sessionId) {
+    throw new Error('--session-id is not supported in close-loop-program. Session ids are generated per goal.');
+  }
+  if (
+    options.batchRetryMaxRounds !== undefined &&
+    options.batchRetryMaxRounds !== null &&
+    !options.batchRetryUntilComplete &&
+    !programAutonomousEnabled
+  ) {
+    throw new Error('--batch-retry-max-rounds requires --batch-retry-until-complete.');
+  }
+  if (options.batchRetryMaxRounds !== undefined && options.batchRetryMaxRounds !== null) {
+    normalizeBatchRetryMaxRounds(options.batchRetryMaxRounds);
+  }
+  if (options.batchSessionKeep !== undefined && options.batchSessionKeep !== null) {
+    normalizeBatchSessionKeep(options.batchSessionKeep);
+  }
+  if (options.batchSessionOlderThanDays !== undefined && options.batchSessionOlderThanDays !== null) {
+    normalizeBatchSessionOlderThanDays(options.batchSessionOlderThanDays);
+  }
+  if (options.specSessionKeep !== undefined && options.specSessionKeep !== null) {
+    normalizeSpecKeep(options.specSessionKeep);
+  }
+  if (options.specSessionOlderThanDays !== undefined && options.specSessionOlderThanDays !== null) {
+    normalizeOlderThanDays(options.specSessionOlderThanDays);
+  }
+  if (options.specSessionProtectWindowDays !== undefined && options.specSessionProtectWindowDays !== null) {
+    normalizeSpecSessionProtectWindowDays(options.specSessionProtectWindowDays);
+  }
+  if (options.specSessionMaxTotal !== undefined && options.specSessionMaxTotal !== null) {
+    normalizeSpecSessionMaxTotal(options.specSessionMaxTotal);
+  }
+  if (options.specSessionMaxCreated !== undefined && options.specSessionMaxCreated !== null) {
+    normalizeSpecSessionMaxCreated(options.specSessionMaxCreated);
+  }
+  if (options.specSessionMaxCreatedPerGoal !== undefined && options.specSessionMaxCreatedPerGoal !== null) {
+    normalizeSpecSessionMaxCreatedPerGoal(options.specSessionMaxCreatedPerGoal);
+  }
+  if (options.specSessionMaxDuplicateGoals !== undefined && options.specSessionMaxDuplicateGoals !== null) {
+    normalizeSpecSessionMaxDuplicateGoals(options.specSessionMaxDuplicateGoals);
+  }
+  if (options.batchSessionId !== undefined && options.batchSessionId !== null) {
+    const sanitizedBatchSessionId = sanitizeBatchSessionId(options.batchSessionId);
+    if (!sanitizedBatchSessionId) {
+      throw new Error('--batch-session-id is invalid after sanitization.');
+    }
+  }
+
+  const goalsResult = buildCloseLoopBatchGoalsFromGoal(goal, options.programGoals, {
+    minQualityScore: options.programMinQualityScore,
+    enforceQualityGate: Boolean(options.programQualityGate)
+  });
+  const programOptions = {
+    ...options,
+    batchAutonomous: programAutonomousEnabled
+  };
+  const initialSummary = await executeCloseLoopBatch(goalsResult, programOptions, projectPath, 'auto-close-loop-program');
+  let summary = {
+    ...initialSummary,
+    auto_recovery: {
+      enabled: programAutoRecoverEnabled,
+      triggered: false,
+      converged: initialSummary.status === 'completed',
+      source_status: initialSummary.status
+    }
+  };
+
+  if (programAutoRecoverEnabled && initialSummary.status !== 'completed') {
+    const recoveryResult = await executeCloseLoopRecoveryCycle({
+      projectPath,
+      sourceSummary: {
+        file: initialSummary.batch_session && initialSummary.batch_session.file
+          ? initialSummary.batch_session.file
+          : '(auto-close-loop-program-in-memory)',
+        payload: initialSummary
+      },
+      baseOptions: {
+        ...programOptions,
+        useAction: options.programRecoverUseAction
+      },
+      recoverAutonomousEnabled: true,
+      resumeStrategy: programRecoverResumeStrategy,
+      recoverUntilComplete: true,
+      recoverMaxRounds: programRecoverMaxRounds,
+      recoverMaxDurationMs: programRecoverMaxMinutes === null ? null : programRecoverMaxMinutes * 60 * 1000,
+      recoveryMemoryScope,
+      actionCandidate: options.programRecoverUseAction
+    });
+
+    summary = mergeProgramRecoveryIntoProgramSummary(
+      initialSummary,
+      recoveryResult.summary,
+      {
+        enabled: true,
+        triggered: true,
+        recover_until_complete: true,
+        recover_max_rounds: programRecoverMaxRounds,
+        recover_max_minutes: programRecoverMaxMinutes,
+        resume_strategy: programRecoverResumeStrategy
+      }
+    );
+    summary.program_kpi = buildProgramKpiSnapshot(summary);
+    summary.program_diagnostics = buildProgramDiagnostics(summary);
+    summary.program_coordination = buildProgramCoordinationSnapshot(summary);
+    if (writeOutputs) {
+      await maybeWriteProgramKpi(summary, options.programKpiOut, projectPath);
+      await maybeWriteOutput(summary, options.out, projectPath);
+    }
+    if (programOptions.batchSession !== false) {
+      await maybePersistCloseLoopBatchSummary(summary, programOptions, projectPath);
+    }
+  }
+
+  const programCompletedAt = now();
+  summary.program_started_at = new Date(programStartedAt).toISOString();
+  summary.program_completed_at = new Date(programCompletedAt).toISOString();
+  summary.program_elapsed_ms = Math.max(0, programCompletedAt - programStartedAt);
+
+  await applyProgramGateOutcome(summary, {
+    projectPath,
+    options: programOptions,
+    programGatePolicy,
+    gateFallbackChain,
+    enableAutoRemediation: options.programGateAutoRemediate !== false
+  });
+
+  if (programGovernUntilStable) {
+    const governanceResult = await runProgramGovernanceLoop({
+      enabled: true,
+      summary,
+      projectPath,
+      programOptions,
+      baseGoalsResult: goalsResult,
+      maxRounds: programGovernMaxRounds,
+      maxMinutes: programGovernMaxMinutes,
+      anomalyEnabled: programGovernAnomalyEnabled,
+      anomalyWeeks: programGovernAnomalyWeeks,
+      anomalyPeriod: programGovernAnomalyPeriod,
+      programGatePolicy,
+      gateFallbackChain,
+      recoveryMemoryScope,
+      recoverResumeStrategy: programRecoverResumeStrategy,
+      recoverMaxRounds: programRecoverMaxRounds,
+      recoverMaxMinutes: programRecoverMaxMinutes,
+      programRecoverUseAction: options.programRecoverUseAction,
+      programGateAutoRemediate: options.programGateAutoRemediate !== false,
+      governUseAction: programGovernUseAction,
+      governAutoActionEnabled: programGovernAutoActionEnabled
+    });
+    summary = governanceResult.summary;
+    summary.program_governance = governanceResult.governance;
+  } else {
+    summary.program_governance = {
+      enabled: false,
+      anomaly_enabled: programGovernAnomalyEnabled,
+      anomaly_weeks: programGovernAnomalyWeeks,
+      anomaly_period: programGovernAnomalyPeriod,
+      auto_action_enabled: programGovernAutoActionEnabled,
+      action_selection_enabled: false,
+      pinned_action_index: programGovernUseAction,
+      max_rounds: programGovernMaxRounds,
+      max_minutes: programGovernMaxMinutes,
+      performed_rounds: 0,
+      converged: Boolean(
+        summary &&
+        summary.program_gate_effective &&
+        summary.program_gate_effective.passed &&
+        !isSpecSessionBudgetHardFailure(summary) &&
+        !isSpecSessionGrowthGuardHardFailure(summary)
+      ),
+      exhausted: false,
+      stop_reason: 'disabled',
+      history: []
+    };
+  }
+
+  const finalProgramCompletedAt = now();
+  summary.program_completed_at = new Date(finalProgramCompletedAt).toISOString();
+  summary.program_elapsed_ms = Math.max(0, finalProgramCompletedAt - programStartedAt);
+
+  if (writeOutputs) {
+    await maybeWriteProgramKpi(summary, options.programKpiOut, projectPath);
+    await maybeWriteOutput(summary, options.out, projectPath);
+    await maybeWriteProgramAudit(summary, options.programAuditOut, projectPath);
+  }
+
+  if (shouldPrintSummary) {
+    printCloseLoopBatchSummary(summary, programOptions);
+  }
+
+  const exitCode = (
+    summary.status !== 'completed' ||
+    !summary.program_gate_effective.passed ||
+    isSpecSessionBudgetHardFailure(summary) ||
+    isSpecSessionGrowthGuardHardFailure(summary)
+  ) ? 1 : 0;
+
+  return {
+    summary,
+    options: programOptions,
+    exitCode
+  };
+}
+
+module.exports = {
+  executeCloseLoopProgramGoal
+};