scene-capability-engine 3.6.32 → 3.6.36

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

@@ -0,0 +1,191 @@
+async function executeCloseLoopRecoveryCycle(input = {}, dependencies = {}) {
+  const {
+    projectPath,
+    sourceSummary,
+    baseOptions,
+    recoverAutonomousEnabled,
+    resumeStrategy,
+    recoverUntilComplete,
+    recoverMaxRounds,
+    recoverMaxDurationMs,
+    recoveryMemoryTtlDays,
+    recoveryMemoryScope,
+    actionCandidate
+  } = input;
+  const {
+    pruneCloseLoopRecoveryMemory,
+    loadCloseLoopRecoveryMemory,
+    normalizeRecoveryMemoryToken,
+    buildRecoveryMemorySignature,
+    getRecoveryMemoryEntry,
+    resolveRecoveryActionSelection,
+    applyRecoveryActionPatch,
+    buildCloseLoopBatchGoalsFromSummaryPayload,
+    executeCloseLoopBatch,
+    loadCloseLoopBatchSummaryPayload,
+    updateCloseLoopRecoveryMemory,
+    now = () => Date.now()
+  } = dependencies;
+
+  let resolvedSourceSummary = sourceSummary && typeof sourceSummary === 'object'
+    ? {
+      file: typeof sourceSummary.file === 'string' && sourceSummary.file.trim()
+        ? sourceSummary.file
+        : '(in-memory-summary)',
+      payload: sourceSummary.payload && typeof sourceSummary.payload === 'object'
+        ? sourceSummary.payload
+        : {}
+    }
+    : {
+      file: '(in-memory-summary)',
+      payload: {}
+    };
+
+  if (recoveryMemoryTtlDays !== null && recoveryMemoryTtlDays !== undefined) {
+    await pruneCloseLoopRecoveryMemory(projectPath, {
+      olderThanDays: recoveryMemoryTtlDays,
+      dryRun: false
+    });
+  }
+  const recoveryMemory = await loadCloseLoopRecoveryMemory(projectPath);
+  const resolvedRecoveryScope = normalizeRecoveryMemoryToken(recoveryMemoryScope || '') || 'default-scope';
+  const recoverySignature = buildRecoveryMemorySignature(resolvedSourceSummary.payload, {
+    scope: resolvedRecoveryScope
+  });
+  const recoveryMemoryEntry = getRecoveryMemoryEntry(recoveryMemory.payload, recoverySignature);
+  const pinnedActionSelection = resolveRecoveryActionSelection(
+    resolvedSourceSummary.payload,
+    actionCandidate,
+    { recoveryMemoryEntry }
+  );
+
+  let finalSummary = null;
+  let finalRecoveryOptions = null;
+  const recoveryHistory = [];
+  const startedAt = Number(now());
+  let budgetExhausted = false;
+  for (let round = 1; round <= recoverMaxRounds; round += 1) {
+    if (recoverMaxDurationMs !== null && recoverMaxDurationMs !== undefined) {
+      const elapsedBeforeRound = Number(now()) - startedAt;
+      if (elapsedBeforeRound >= recoverMaxDurationMs && finalSummary) {
+        budgetExhausted = true;
+        break;
+      }
+    }
+
+    const recoveryOptions = applyRecoveryActionPatch({
+      ...baseOptions,
+      batchAutonomous: recoverAutonomousEnabled
+    }, pinnedActionSelection.selectedAction);
+
+    if (
+      recoverUntilComplete &&
+      typeof recoveryOptions.batchSessionId === 'string' &&
+      recoveryOptions.batchSessionId.trim()
+    ) {
+      recoveryOptions.batchSessionId = `${recoveryOptions.batchSessionId.trim()}-r${round}`;
+    }
+
+    const goalsResult = await buildCloseLoopBatchGoalsFromSummaryPayload(
+      resolvedSourceSummary.payload,
+      resolvedSourceSummary.file,
+      projectPath,
+      'auto',
+      resumeStrategy
+    );
+    const summary = await executeCloseLoopBatch(
+      goalsResult,
+      recoveryOptions,
+      projectPath,
+      'auto-close-loop-recover'
+    );
+
+    summary.recovered_from_summary = {
+      file: resolvedSourceSummary.file,
+      source_mode: resolvedSourceSummary.payload.mode || null,
+      source_status: resolvedSourceSummary.payload.status || null,
+      resume_strategy: resumeStrategy,
+      selected_action_index: pinnedActionSelection.selectedIndex,
+      selected_action: pinnedActionSelection.selectedAction || null,
+      round
+    };
+    summary.recovery_plan = {
+      remediation_actions: pinnedActionSelection.availableActions,
+      applied_patch: pinnedActionSelection.appliedPatch,
+      selection_source: pinnedActionSelection.selectionSource,
+      selection_explain: pinnedActionSelection.selectionExplain || null
+    };
+
+    recoveryHistory.push({
+      round,
+      source_summary: resolvedSourceSummary.file,
+      status: summary.status,
+      processed_goals: summary.processed_goals,
+      completed_goals: summary.completed_goals,
+      failed_goals: summary.failed_goals,
+      batch_session_file: summary.batch_session && summary.batch_session.file
+        ? summary.batch_session.file
+        : null
+    });
+
+    finalSummary = summary;
+    finalRecoveryOptions = recoveryOptions;
+
+    if (!recoverUntilComplete || summary.status === 'completed') {
+      break;
+    }
+
+    resolvedSourceSummary = summary.batch_session && summary.batch_session.file
+      ? await loadCloseLoopBatchSummaryPayload(projectPath, summary.batch_session.file)
+      : {
+        file: '(derived-from-summary)',
+        payload: summary
+      };
+  }
+
+  if (!finalSummary) {
+    throw new Error('Recovery cycle did not produce a summary.');
+  }
+
+  finalSummary.recovery_cycle = {
+    enabled: recoverUntilComplete,
+    max_rounds: recoverMaxRounds,
+    performed_rounds: recoveryHistory.length,
+    converged: finalSummary.status === 'completed',
+    exhausted: ((recoverUntilComplete && recoveryHistory.length >= recoverMaxRounds && finalSummary.status !== 'completed') || budgetExhausted),
+    time_budget_minutes: recoverMaxDurationMs ? Number((recoverMaxDurationMs / 60000).toFixed(2)) : null,
+    elapsed_ms: Number(now()) - startedAt,
+    budget_exhausted: budgetExhausted,
+    history: recoveryHistory
+  };
+
+  const memoryUpdate = await updateCloseLoopRecoveryMemory(
+    projectPath,
+    recoveryMemory,
+    recoverySignature,
+    pinnedActionSelection.selectedIndex,
+    pinnedActionSelection.selectedAction,
+    finalSummary.status,
+    { scope: resolvedRecoveryScope }
+  );
+  finalSummary.recovery_memory = {
+    file: memoryUpdate.file,
+    signature: memoryUpdate.signature,
+    scope: memoryUpdate.scope,
+    action_key: memoryUpdate.action_key,
+    selected_action_index: pinnedActionSelection.selectedIndex,
+    selection_source: pinnedActionSelection.selectionSource,
+    selection_explain: pinnedActionSelection.selectionExplain || null,
+    action_stats: memoryUpdate.entry
+  };
+
+  return {
+    summary: finalSummary,
+    options: finalRecoveryOptions || baseOptions,
+    pinnedActionSelection
+  };
+}
+
+module.exports = {
+  executeCloseLoopRecoveryCycle
+};

package/lib/auto/close-loop-session-storage-service.js

@@ -0,0 +1,50 @@
+const path = require('path');
+
+function getCloseLoopSessionDir(projectPath) {
+  return path.join(projectPath, '.sce', 'auto', 'close-loop-sessions');
+}
+
+async function readCloseLoopSessionEntries(projectPath, dependencies = {}) {
+  const { fs } = dependencies;
+  const sessionDir = getCloseLoopSessionDir(projectPath);
+  if (!(await fs.pathExists(sessionDir))) {
+    return [];
+  }
+
+  const files = (await fs.readdir(sessionDir)).filter((item) => item.toLowerCase().endsWith('.json'));
+  const sessions = [];
+  for (const file of files) {
+    const filePath = path.join(sessionDir, file);
+    const stats = await fs.stat(filePath);
+    const fallbackTimestamp = new Date(stats.mtimeMs).toISOString();
+    const fallbackId = path.basename(file, '.json');
+    let payload = null;
+    let parseError = null;
+
+    try {
+      payload = await fs.readJson(filePath);
+    } catch (error) {
+      parseError = error;
+    }
+
+    sessions.push({
+      id: payload && payload.session_id ? payload.session_id : fallbackId,
+      file: filePath,
+      status: payload && typeof payload.status === 'string' ? payload.status : (parseError ? 'invalid' : 'unknown'),
+      goal: payload && typeof payload.goal === 'string' ? payload.goal : null,
+      master_spec: payload && payload.portfolio && typeof payload.portfolio.master_spec === 'string' ? payload.portfolio.master_spec : null,
+      sub_spec_count: payload && payload.portfolio && Array.isArray(payload.portfolio.sub_specs) ? payload.portfolio.sub_specs.length : null,
+      updated_at: payload && typeof payload.updated_at === 'string' ? payload.updated_at : fallbackTimestamp,
+      parse_error: parseError ? parseError.message : null,
+      mtime_ms: stats.mtimeMs
+    });
+  }
+
+  sessions.sort((a, b) => b.mtime_ms - a.mtime_ms);
+  return sessions;
+}
+
+module.exports = {
+  getCloseLoopSessionDir,
+  readCloseLoopSessionEntries
+};

package/lib/auto/controller-lock-service.js

@@ -0,0 +1,55 @@
+function buildControllerLockPayload(lockToken) {
+  return {
+    token: lockToken,
+    pid: process.pid,
+    host: process.env.COMPUTERNAME || process.env.HOSTNAME || null,
+    acquired_at: new Date().toISOString(),
+    touched_at: new Date().toISOString()
+  };
+}
+
+function resolveControllerLockFile(pathModule, projectPath, queueFilePath, lockFileCandidate) {
+  const normalized = typeof lockFileCandidate === 'string' && lockFileCandidate.trim()
+    ? lockFileCandidate.trim()
+    : `${queueFilePath}.lock`;
+  return pathModule.isAbsolute(normalized)
+    ? normalized
+    : pathModule.join(projectPath, normalized);
+}
+
+async function readControllerLockPayload(fs, lockFile) {
+  if (!(await fs.pathExists(lockFile))) {
+    return null;
+  }
+  try {
+    return await fs.readJson(lockFile);
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function writeControllerLockPayload(pathModule, fs, lockFile, payload, mode = 'overwrite') {
+  await fs.ensureDir(pathModule.dirname(lockFile));
+  if (mode === 'create') {
+    await fs.writeFile(lockFile, JSON.stringify(payload, null, 2), {
+      encoding: 'utf8',
+      flag: 'wx'
+    });
+    return;
+  }
+  await fs.writeJson(lockFile, payload, { spaces: 2 });
+}
+
+function isControllerLockStale(stats, ttlSeconds, now = Date.now()) {
+  const mtimeMs = Number(stats && stats.mtimeMs) || 0;
+  const ttlMs = Math.max(1, ttlSeconds) * 1000;
+  return mtimeMs > 0 && (now - mtimeMs) > ttlMs;
+}
+
+module.exports = {
+  buildControllerLockPayload,
+  resolveControllerLockFile,
+  readControllerLockPayload,
+  writeControllerLockPayload,
+  isControllerLockStale
+};

package/lib/auto/controller-output.js

@@ -0,0 +1,32 @@
+function printCloseLoopControllerSummary(chalk, summary) {
+  console.log(chalk.blue('Autonomous close-loop controller summary'));
+  console.log(chalk.gray(`  Status: ${summary.status}`));
+  console.log(chalk.gray(`  Cycles: ${summary.cycles_performed}/${summary.max_cycles}`));
+  console.log(chalk.gray(`  Processed goals: ${summary.processed_goals}`));
+  console.log(chalk.gray(`  Completed: ${summary.completed_goals}`));
+  console.log(chalk.gray(`  Failed: ${summary.failed_goals}`));
+  console.log(chalk.gray(`  Pending queue goals: ${summary.pending_goals}`));
+  if (summary.dedupe_enabled) {
+    console.log(chalk.gray(`  Dedupe dropped: ${summary.dedupe_dropped_goals || 0}`));
+  }
+  console.log(chalk.gray(`  Stop reason: ${summary.stop_reason}`));
+  if (summary.lock_enabled && summary.lock_file) {
+    console.log(chalk.gray(`  Lock: ${summary.lock_file}`));
+  }
+  if (summary.controller_session && summary.controller_session.file) {
+    console.log(chalk.gray(`  Session: ${summary.controller_session.file}`));
+  }
+  if (summary.done_archive_file) {
+    console.log(chalk.gray(`  Done archive: ${summary.done_archive_file}`));
+  }
+  if (summary.failed_archive_file) {
+    console.log(chalk.gray(`  Failed archive: ${summary.failed_archive_file}`));
+  }
+  if (summary.output_file) {
+    console.log(chalk.gray(`  Output: ${summary.output_file}`));
+  }
+}
+
+module.exports = {
+  printCloseLoopControllerSummary
+};

package/lib/auto/controller-queue-service.js

@@ -0,0 +1,127 @@
+function resolveControllerQueueFile(pathModule, projectPath, queueFileCandidate) {
+  const normalized = typeof queueFileCandidate === 'string' && queueFileCandidate.trim()
+    ? queueFileCandidate.trim()
+    : '.sce/auto/close-loop-controller-goals.lines';
+  return pathModule.isAbsolute(normalized)
+    ? normalized
+    : pathModule.join(projectPath, normalized);
+}
+
+function resolveControllerQueueFormat(normalizeBatchFormat, resolvedQueueFile, formatCandidate) {
+  const normalized = normalizeBatchFormat(formatCandidate);
+  if (normalized !== 'auto') {
+    return normalized;
+  }
+  return `${resolvedQueueFile}`.toLowerCase().endsWith('.json')
+    ? 'json'
+    : 'lines';
+}
+
+function dedupeControllerGoals(goals) {
+  const uniqueGoals = [];
+  const seen = new Set();
+  let duplicateCount = 0;
+  for (const item of Array.isArray(goals) ? goals : []) {
+    const normalized = `${item || ''}`.trim();
+    if (!normalized) {
+      continue;
+    }
+    const fingerprint = normalized.toLowerCase();
+    if (seen.has(fingerprint)) {
+      duplicateCount += 1;
+      continue;
+    }
+    seen.add(fingerprint);
+    uniqueGoals.push(normalized);
+  }
+  return {
+    goals: uniqueGoals,
+    duplicate_count: duplicateCount
+  };
+}
+
+async function loadControllerGoalQueue(pathModule, fs, parseGoalsFromJsonPayload, parseGoalsFromLines, projectPath, queueFileCandidate, formatCandidate, options = {}) {
+  const file = resolveControllerQueueFile(pathModule, projectPath, queueFileCandidate);
+  const format = resolveControllerQueueFormat(options.normalizeBatchFormat || ((value) => value || 'auto'), file, formatCandidate);
+  const dedupe = options.dedupe === true;
+  if (!(await fs.pathExists(file))) {
+    await fs.ensureDir(pathModule.dirname(file));
+    if (format === 'json') {
+      await fs.writeJson(file, { goals: [] }, { spaces: 2 });
+    } else {
+      await fs.writeFile(file, '', 'utf8');
+    }
+  }
+
+  let goals = [];
+  if (format === 'json') {
+    let payload = null;
+    try {
+      payload = await fs.readJson(file);
+    } catch (error) {
+      throw new Error(`Invalid controller queue JSON: ${file} (${error.message})`);
+    }
+    goals = parseGoalsFromJsonPayload(payload || {});
+  } else {
+    const content = await fs.readFile(file, 'utf8');
+    goals = parseGoalsFromLines(content);
+  }
+
+  const normalizedGoals = goals.map((item) => `${item || ''}`.trim()).filter(Boolean);
+  const dedupeResult = dedupe
+    ? dedupeControllerGoals(normalizedGoals)
+    : { goals: normalizedGoals, duplicate_count: 0 };
+
+  return {
+    file,
+    format,
+    goals: dedupeResult.goals,
+    duplicate_count: dedupeResult.duplicate_count,
+    dedupe_applied: dedupe
+  };
+}
+
+async function writeControllerGoalQueue(pathModule, fs, file, format, goals) {
+  const normalizedGoals = Array.isArray(goals)
+    ? goals.map((item) => `${item || ''}`.trim()).filter(Boolean)
+    : [];
+  await fs.ensureDir(pathModule.dirname(file));
+  if (format === 'json') {
+    await fs.writeJson(file, { goals: normalizedGoals }, { spaces: 2 });
+    return;
+  }
+  const content = normalizedGoals.length > 0
+    ? `${normalizedGoals.join('\n')}\n`
+    : '';
+  await fs.writeFile(file, content, 'utf8');
+}
+
+async function appendControllerGoalArchive(pathModule, fs, fileCandidate, projectPath, goal, metadata = {}) {
+  if (!fileCandidate) {
+    return null;
+  }
+  const resolvedFile = pathModule.isAbsolute(fileCandidate)
+    ? fileCandidate
+    : pathModule.join(projectPath, fileCandidate);
+  await fs.ensureDir(pathModule.dirname(resolvedFile));
+  const timestamp = new Date().toISOString();
+  const normalizedGoal = `${goal || ''}`.replace(/\r?\n/g, ' ').trim();
+  const fields = [
+    timestamp,
+    `${metadata.status || ''}`.trim() || 'unknown',
+    `${metadata.program_status || ''}`.trim() || 'unknown',
+    `${metadata.gate_passed === true ? 'gate-pass' : 'gate-fail'}`,
+    normalizedGoal
+  ];
+  await fs.appendFile(resolvedFile, `${fields.join('\t')}\n`, 'utf8');
+  return resolvedFile;
+}
+
+module.exports = {
+  resolveControllerQueueFile,
+  resolveControllerQueueFormat,
+  dedupeControllerGoals,
+  loadControllerGoalQueue,
+  writeControllerGoalQueue,
+  appendControllerGoalArchive
+};

package/lib/auto/controller-session-storage-service.js

@@ -0,0 +1,105 @@
+const path = require('path');
+
+async function readCloseLoopControllerSessionEntries(projectPath, dependencies = {}) {
+  const { getCloseLoopControllerSessionDir, fs } = dependencies;
+  const sessionDir = getCloseLoopControllerSessionDir(projectPath);
+  if (!(await fs.pathExists(sessionDir))) {
+    return [];
+  }
+
+  const files = (await fs.readdir(sessionDir)).filter((item) => item.toLowerCase().endsWith('.json'));
+  const sessions = [];
+  for (const file of files) {
+    const filePath = path.join(sessionDir, file);
+    const stats = await fs.stat(filePath);
+    const fallbackTimestamp = new Date(stats.mtimeMs).toISOString();
+    const fallbackId = path.basename(file, '.json');
+    let payload = null;
+    let parseError = null;
+
+    try {
+      payload = await fs.readJson(filePath);
+    } catch (error) {
+      parseError = error;
+    }
+
+    sessions.push({
+      id: payload && typeof payload.controller_session === 'object' && typeof payload.controller_session.id === 'string'
+        ? payload.controller_session.id
+        : fallbackId,
+      file: filePath,
+      status: payload && typeof payload.status === 'string'
+        ? payload.status
+        : parseError
+          ? 'invalid'
+          : 'unknown',
+      queue_file: payload && typeof payload.queue_file === 'string' ? payload.queue_file : null,
+      queue_format: payload && typeof payload.queue_format === 'string' ? payload.queue_format : null,
+      processed_goals: payload && Number.isFinite(Number(payload.processed_goals)) ? Number(payload.processed_goals) : null,
+      pending_goals: payload && Number.isFinite(Number(payload.pending_goals)) ? Number(payload.pending_goals) : null,
+      updated_at: payload && typeof payload.updated_at === 'string' ? payload.updated_at : fallbackTimestamp,
+      parse_error: parseError ? parseError.message : null,
+      mtime_ms: stats.mtimeMs
+    });
+  }
+
+  sessions.sort((a, b) => b.mtime_ms - a.mtime_ms);
+  return sessions;
+}
+
+async function resolveCloseLoopControllerSessionFile(projectPath, sessionCandidate, dependencies = {}) {
+  const { readCloseLoopControllerSessionEntries, getCloseLoopControllerSessionDir, sanitizeBatchSessionId, fs } = dependencies;
+  if (typeof sessionCandidate !== 'string' || !sessionCandidate.trim()) {
+    throw new Error('--controller-resume requires a session id/file or "latest".');
+  }
+
+  const normalizedCandidate = sessionCandidate.trim();
+  if (normalizedCandidate.toLowerCase() === 'latest') {
+    const sessions = await readCloseLoopControllerSessionEntries(projectPath, dependencies);
+    if (sessions.length === 0) {
+      throw new Error(`No controller sessions found in: ${getCloseLoopControllerSessionDir(projectPath)}`);
+    }
+    return sessions[0].file;
+  }
+
+  if (path.isAbsolute(normalizedCandidate)) {
+    return normalizedCandidate;
+  }
+  if (normalizedCandidate.includes('/') || normalizedCandidate.includes('\\') || normalizedCandidate.toLowerCase().endsWith('.json')) {
+    return path.join(projectPath, normalizedCandidate);
+  }
+
+  const byId = path.join(getCloseLoopControllerSessionDir(projectPath), `${sanitizeBatchSessionId(normalizedCandidate)}.json`);
+  if (await fs.pathExists(byId)) {
+    return byId;
+  }
+  return path.join(projectPath, normalizedCandidate);
+}
+
+async function loadCloseLoopControllerSessionPayload(projectPath, sessionCandidate, dependencies = {}) {
+  const { fs } = dependencies;
+  const sessionFile = await resolveCloseLoopControllerSessionFile(projectPath, sessionCandidate, dependencies);
+  if (!(await fs.pathExists(sessionFile))) {
+    throw new Error(`Controller session file not found: ${sessionFile}`);
+  }
+  let payload = null;
+  try {
+    payload = await fs.readJson(sessionFile);
+  } catch (error) {
+    throw new Error(`Invalid controller session JSON: ${sessionFile} (${error.message})`);
+  }
+  const sessionId = payload && payload.controller_session && payload.controller_session.id
+    ? payload.controller_session.id
+    : path.basename(sessionFile, '.json');
+  return {
+    id: sessionId,
+    file: sessionFile,
+    payload: payload || {}
+  };
+}
+
+module.exports = {
+  readCloseLoopControllerSessionEntries,
+  resolveCloseLoopControllerSessionFile,
+  loadCloseLoopControllerSessionPayload
+};