agentxchain 2.46.0 → 2.46.2

package/src/lib/governed-state.js

@@ -20,11 +20,15 @@ import { join, dirname } from 'path';
 import { randomBytes, createHash } from 'crypto';
 import { safeWriteJson } from './safe-write.js';
 import { validateStagedTurnResult } from './turn-result-validator.js';
-import { evaluatePhaseExit, evaluateRunCompletion } from './gate-evaluator.js';
+import { evaluatePhaseExit, evaluateRunCompletion, getNextPhase } from './gate-evaluator.js';
+import { evaluateApprovalPolicy } from './approval-policy.js';
 import { evaluatePolicies } from './policy-evaluator.js';
+import { buildTimeoutBlockedReason, evaluateTimeouts } from './timeout-evaluator.js';
 import {
   captureBaseline,
   observeChanges,
+  attributeObservedChangesToTurn,
+  buildConflictCandidateFiles,
   classifyObservedChanges,
   buildObservedArtifact,
   normalizeVerification,
@@ -57,6 +61,50 @@ function generateId(prefix) {
   return `${prefix}_${randomBytes(8).toString('hex')}`;
 }
 
+function normalizeGateFailure(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  return {
+    gate_type: value.gate_type === 'run_completion' ? 'run_completion' : 'phase_transition',
+    gate_id: typeof value.gate_id === 'string' && value.gate_id.length > 0 ? value.gate_id : null,
+    phase: typeof value.phase === 'string' && value.phase.length > 0 ? value.phase : 'unknown',
+    from_phase: typeof value.from_phase === 'string' && value.from_phase.length > 0 ? value.from_phase : null,
+    to_phase: typeof value.to_phase === 'string' && value.to_phase.length > 0 ? value.to_phase : null,
+    requested_by_turn: typeof value.requested_by_turn === 'string' && value.requested_by_turn.length > 0 ? value.requested_by_turn : null,
+    failed_at: typeof value.failed_at === 'string' && value.failed_at.length > 0 ? value.failed_at : null,
+    queued_request: value.queued_request === true,
+    reasons: Array.isArray(value.reasons) ? value.reasons.filter((reason) => typeof reason === 'string' && reason.length > 0) : [],
+    missing_files: Array.isArray(value.missing_files) ? value.missing_files.filter((path) => typeof path === 'string' && path.length > 0) : [],
+    missing_verification: value.missing_verification === true,
+  };
+}
+
+function buildGateFailureRecord({
+  gateType,
+  gateResult,
+  phase,
+  fromPhase = null,
+  toPhase = null,
+  requestedByTurn = null,
+  failedAt,
+  queuedRequest,
+}) {
+  return normalizeGateFailure({
+    gate_type: gateType,
+    gate_id: gateResult?.gate_id || null,
+    phase,
+    from_phase: fromPhase,
+    to_phase: toPhase,
+    requested_by_turn: requestedByTurn,
+    failed_at: failedAt,
+    queued_request: queuedRequest,
+    reasons: Array.isArray(gateResult?.reasons) ? gateResult.reasons : [],
+    missing_files: Array.isArray(gateResult?.missing_files) ? gateResult.missing_files : [],
+    missing_verification: gateResult?.missing_verification === true,
+  });
+}
+
 function emitBlockedNotification(root, config, state, details = {}, turn = null) {
   if (!config?.notifications?.webhooks?.length) {
     return;
@@ -608,6 +656,7 @@ function normalizeV1toV1_1(state) {
         : {},
     queued_phase_transition: state.queued_phase_transition ?? null,
     queued_run_completion: state.queued_run_completion ?? null,
+    last_gate_failure: normalizeGateFailure(state.last_gate_failure),
   };
 }
 
@@ -880,8 +929,8 @@ function cleanupTurnArtifacts(root, turnId) {
   } catch { /* best-effort */ }
 }
 
-function detectAcceptanceConflict(targetTurn, observedArtifact, historyEntries) {
-  const observedFiles = [...new Set(getObservedFiles({ observed_artifact: observedArtifact }))];
+function detectAcceptanceConflict(targetTurn, conflictFiles, historyEntries) {
+  const observedFiles = [...new Set(Array.isArray(conflictFiles) ? conflictFiles : [])];
   if (observedFiles.length === 0) {
     return null;
   }
@@ -1000,6 +1049,101 @@ function buildBlockedReason({ category, recovery, turnId, blockedAt = new Date()
   };
 }
 
+function buildTimeoutLedgerEntry(timeoutResult, timestamp, turnId, phase, type = 'timeout') {
+  return {
+    type,
+    scope: timeoutResult.scope,
+    phase: timeoutResult.phase || phase || null,
+    turn_id: turnId || null,
+    limit_minutes: timeoutResult.limit_minutes,
+    elapsed_minutes: timeoutResult.elapsed_minutes,
+    exceeded_by_minutes: timeoutResult.exceeded_by_minutes,
+    action: timeoutResult.action,
+    timestamp,
+  };
+}
+
+function attemptTimeoutPhaseSkip({ root, config, updatedState, nextHistoryEntries, historyEntry, timeoutResult, now }) {
+  const currentPhase = updatedState.phase;
+  const nextPhase = getNextPhase(currentPhase, config.routing || {});
+  if (!nextPhase) {
+    return {
+      ok: false,
+      error: `Phase "${currentPhase}" has no next phase to skip to`,
+    };
+  }
+
+  const syntheticTurn = {
+    ...historyEntry,
+    verification: historyEntry.verification || {},
+    phase_transition_request: nextPhase,
+  };
+  const postAcceptanceState = {
+    ...updatedState,
+    history: nextHistoryEntries,
+  };
+  const gateResult = evaluatePhaseExit({
+    state: postAcceptanceState,
+    config,
+    acceptedTurn: syntheticTurn,
+    root,
+  });
+
+  if (gateResult.action === 'advance') {
+    return {
+      ok: true,
+      gateResult,
+      updatedState: {
+        ...updatedState,
+        phase: gateResult.next_phase,
+        phase_entered_at: now,
+        last_gate_failure: null,
+        phase_gate_status: {
+          ...(updatedState.phase_gate_status || {}),
+          [gateResult.gate_id || 'no_gate']: 'passed',
+        },
+      },
+      ledgerEntry: {
+        ...buildTimeoutLedgerEntry(timeoutResult, now, historyEntry.turn_id, currentPhase, 'timeout_skip'),
+        from_phase: currentPhase,
+        to_phase: gateResult.next_phase,
+        gate_id: gateResult.gate_id || null,
+      },
+    };
+  }
+
+  const reasons = gateResult.action === 'awaiting_human_approval'
+    ? [`Gate "${gateResult.gate_id || 'unknown'}" still requires human approval; timeout skip cannot auto-advance`]
+    : Array.isArray(gateResult.reasons) && gateResult.reasons.length > 0
+      ? gateResult.reasons
+      : ['Timeout skip failed for an unknown reason'];
+  const gateFailure = buildGateFailureRecord({
+    gateType: 'phase_transition',
+    gateResult: {
+      ...gateResult,
+      reasons,
+    },
+    phase: currentPhase,
+    fromPhase: currentPhase,
+    toPhase: nextPhase,
+    requestedByTurn: historyEntry.turn_id,
+    failedAt: now,
+    queuedRequest: false,
+  });
+
+  return {
+    ok: false,
+    gateFailure,
+    ledgerEntry: {
+      ...buildTimeoutLedgerEntry(timeoutResult, now, historyEntry.turn_id, currentPhase, 'timeout_skip_failed'),
+      from_phase: currentPhase,
+      to_phase: nextPhase,
+      gate_id: gateResult.gate_id || null,
+      reasons,
+    },
+  };
+}
+
 function slugifyEscalationReason(reason) {
   if (typeof reason !== 'string') {
     return 'operator';
@@ -1410,6 +1554,15 @@ export function normalizeGovernedStateShape(state) {
     changed = true;
   }
 
+  const normalizedLastGateFailure = normalizeGateFailure(nextState.last_gate_failure);
+  if (JSON.stringify(nextState.last_gate_failure ?? null) !== JSON.stringify(normalizedLastGateFailure)) {
+    nextState = {
+      ...nextState,
+      last_gate_failure: normalizedLastGateFailure,
+    };
+    changed = true;
+  }
+
   return { state: stripLegacyCurrentTurn(nextState), changed };
 }
 
@@ -1627,9 +1780,12 @@ export function initializeGovernedRun(root, config) {
   }
 
   const runId = generateId('run');
+  const now = new Date().toISOString();
   const updatedState = {
     ...state,
     run_id: runId,
+    created_at: now,
+    phase_entered_at: now,
     status: 'active',
     blocked_on: null,
     blocked_reason: null,
@@ -2092,7 +2248,9 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const stagingFile = join(root, resolvedStagingPath);
   const now = new Date().toISOString();
   const baseline = currentTurn.baseline || null;
-  const observation = observeChanges(root, baseline);
+  const rawObservation = observeChanges(root, baseline);
+  const historyEntries = readJsonlEntries(root, HISTORY_PATH);
+  const observation = attributeObservedChangesToTurn(rawObservation, currentTurn, historyEntries);
   const role = config.roles?.[turnResult.role];
   const runtimeId = turnResult.runtime_id;
   const runtime = config.runtimes?.[runtimeId];
@@ -2125,7 +2283,6 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const normalizedVerification = normalizeVerification(turnResult.verification, runtimeType);
   const artifactType = turnResult.artifact?.type || 'review';
   const derivedRef = deriveAcceptedRef(observation, artifactType, state.accepted_integration_ref);
-  const historyEntries = readJsonlEntries(root, HISTORY_PATH);
 
   // Policy evaluation — declarative governance rules (spec: POLICY_ENGINE_SPEC.md)
   const policyResult = evaluatePolicies(config.policies || [], {
@@ -2203,7 +2360,11 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     };
   }
 
-  const conflict = detectAcceptanceConflict(currentTurn, observedArtifact, historyEntries);
+  const conflict = detectAcceptanceConflict(
+    currentTurn,
+    buildConflictCandidateFiles(rawObservation, observation, turnResult.files_changed || []),
+    historyEntries,
+  );
 
   if (conflict) {
     const detectionCount = (currentTurn.conflict_state?.detection_count || 0) + 1;
@@ -2338,6 +2499,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     cost: turnResult.cost || {},
     accepted_at: now,
   };
+  const nextHistoryEntries = [...historyEntries, historyEntry];
   // Build ledger entries for the journal
   const ledgerEntries = [];
   if (turnResult.decisions && turnResult.decisions.length > 0) {
@@ -2451,6 +2613,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
 
   let gateResult = null;
   let completionResult = null;
+  let timeoutResult = null;
   const hasRemainingTurns = Object.keys(remainingTurns).length > 0;
   if (turnResult.status !== 'needs_human') {
     if (hasRemainingTurns) {
@@ -2469,7 +2632,6 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         };
       }
     } else {
-      const nextHistoryEntries = [...historyEntries, historyEntry];
       const postAcceptanceState = {
         ...state,
         active_turns: remainingTurns,
@@ -2491,6 +2653,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         if (completionResult.action === 'complete') {
           updatedState.status = 'completed';
           updatedState.completed_at = now;
+          updatedState.last_gate_failure = null;
           if (completionResult.gate_id) {
             updatedState.phase_gate_status = {
               ...(updatedState.phase_gate_status || {}),
@@ -2500,16 +2663,71 @@ function _acceptGovernedTurnLocked(root, config, opts) {
           updatedState.queued_run_completion = null;
           updatedState.queued_phase_transition = null;
         } else if (completionResult.action === 'awaiting_human_approval') {
-          updatedState.status = 'paused';
-          updatedState.blocked_on = `human_approval:${completionResult.gate_id}`;
-          updatedState.blocked_reason = null;
-          updatedState.pending_run_completion = {
-            gate: completionResult.gate_id,
-            requested_by_turn: completionSource.turn_id,
-            requested_at: now,
-          };
+          // Evaluate approval policy — may auto-approve
+          const approvalResult = evaluateApprovalPolicy({
+            gateResult: completionResult,
+            gateType: 'run_completion',
+            state: { ...updatedState, history: nextHistoryEntries },
+            config,
+          });
+
+          if (approvalResult.action === 'auto_approve') {
+            updatedState.status = 'completed';
+            updatedState.completed_at = now;
+            updatedState.last_gate_failure = null;
+            if (completionResult.gate_id) {
+              updatedState.phase_gate_status = {
+                ...(updatedState.phase_gate_status || {}),
+                [completionResult.gate_id]: 'passed',
+              };
+            }
+            updatedState.queued_run_completion = null;
+            updatedState.queued_phase_transition = null;
+            ledgerEntries.push({
+              type: 'approval_policy',
+              gate_type: 'run_completion',
+              action: 'auto_approve',
+              matched_rule: approvalResult.matched_rule,
+              reason: approvalResult.reason,
+              gate_id: completionResult.gate_id,
+              timestamp: now,
+            });
+          } else {
+            updatedState.status = 'paused';
+            updatedState.blocked_on = `human_approval:${completionResult.gate_id}`;
+            updatedState.blocked_reason = null;
+            updatedState.last_gate_failure = null;
+            updatedState.pending_run_completion = {
+              gate: completionResult.gate_id,
+              requested_by_turn: completionSource.turn_id,
+              requested_at: now,
+            };
+            updatedState.queued_run_completion = null;
+            updatedState.queued_phase_transition = null;
+          }
+        } else if (completionResult.action === 'gate_failed') {
+          const gateFailure = buildGateFailureRecord({
+            gateType: 'run_completion',
+            gateResult: completionResult,
+            phase: state.phase,
+            fromPhase: state.phase,
+            toPhase: null,
+            requestedByTurn: completionSource?.turn_id || state.queued_run_completion?.requested_by_turn || null,
+            failedAt: now,
+            queuedRequest: Boolean(state.queued_run_completion && !turnResult.run_completion_request),
+          });
+          updatedState.last_gate_failure = gateFailure;
+          if (completionResult.gate_id) {
+            updatedState.phase_gate_status = {
+              ...(updatedState.phase_gate_status || {}),
+              [completionResult.gate_id]: 'failed',
+            };
+          }
           updatedState.queued_run_completion = null;
-          updatedState.queued_phase_transition = null;
+          ledgerEntries.push({
+            type: 'gate_failure',
+            ...gateFailure,
+          });
         } else if (state.queued_run_completion) {
           updatedState.queued_run_completion = null;
         }
@@ -2531,22 +2749,78 @@ function _acceptGovernedTurnLocked(root, config, opts) {
 
         if (gateResult.action === 'advance') {
           updatedState.phase = gateResult.next_phase;
+          updatedState.phase_entered_at = now;
+          updatedState.last_gate_failure = null;
           updatedState.phase_gate_status = {
             ...(updatedState.phase_gate_status || {}),
             [gateResult.gate_id || 'no_gate']: 'passed',
           };
           updatedState.queued_phase_transition = null;
         } else if (gateResult.action === 'awaiting_human_approval') {
-          updatedState.status = 'paused';
-          updatedState.blocked_on = `human_approval:${gateResult.gate_id}`;
-          updatedState.blocked_reason = null;
-          updatedState.pending_phase_transition = {
-            from: state.phase,
-            to: gateResult.next_phase,
-            gate: gateResult.gate_id,
-            requested_by_turn: phaseSource.turn_id,
-          };
+          // Evaluate approval policy — may auto-approve
+          const approvalResult = evaluateApprovalPolicy({
+            gateResult,
+            gateType: 'phase_transition',
+            state: { ...updatedState, history: nextHistoryEntries },
+            config,
+          });
+
+          if (approvalResult.action === 'auto_approve') {
+            updatedState.phase = gateResult.next_phase;
+            updatedState.phase_entered_at = now;
+            updatedState.last_gate_failure = null;
+            updatedState.phase_gate_status = {
+              ...(updatedState.phase_gate_status || {}),
+              [gateResult.gate_id || 'no_gate']: 'passed',
+            };
+            updatedState.queued_phase_transition = null;
+            ledgerEntries.push({
+              type: 'approval_policy',
+              gate_type: 'phase_transition',
+              action: 'auto_approve',
+              matched_rule: approvalResult.matched_rule,
+              from_phase: state.phase,
+              to_phase: gateResult.next_phase,
+              reason: approvalResult.reason,
+              gate_id: gateResult.gate_id,
+              timestamp: now,
+            });
+          } else {
+            updatedState.status = 'paused';
+            updatedState.blocked_on = `human_approval:${gateResult.gate_id}`;
+            updatedState.blocked_reason = null;
+            updatedState.last_gate_failure = null;
+            updatedState.pending_phase_transition = {
+              from: state.phase,
+              to: gateResult.next_phase,
+              gate: gateResult.gate_id,
+              requested_by_turn: phaseSource.turn_id,
+            };
+            updatedState.queued_phase_transition = null;
+          }
+        } else if (gateResult.action === 'gate_failed') {
+          const gateFailure = buildGateFailureRecord({
+            gateType: 'phase_transition',
+            gateResult,
+            phase: state.phase,
+            fromPhase: state.phase,
+            toPhase: gateResult.transition_request || state.queued_phase_transition?.to || null,
+            requestedByTurn: phaseSource?.turn_id || state.queued_phase_transition?.requested_by_turn || null,
+            failedAt: now,
+            queuedRequest: Boolean(state.queued_phase_transition && !turnResult.phase_transition_request),
+          });
+          updatedState.last_gate_failure = gateFailure;
+          if (gateResult.gate_id) {
+            updatedState.phase_gate_status = {
+              ...(updatedState.phase_gate_status || {}),
+              [gateResult.gate_id]: 'failed',
+            };
+          }
           updatedState.queued_phase_transition = null;
+          ledgerEntries.push({
+            type: 'gate_failure',
+            ...gateFailure,
+          });
         } else if (state.queued_phase_transition) {
           updatedState.queued_phase_transition = null;
         }
@@ -2554,6 +2828,77 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     }
   }
 
+  const timeoutEvaluation = evaluateTimeouts({
+    config,
+    state: updatedState,
+    turn: currentTurn,
+    turnResult,
+    now,
+  });
+  for (const warning of timeoutEvaluation.warnings) {
+    ledgerEntries.push(buildTimeoutLedgerEntry(warning, now, currentTurn.turn_id, updatedState.phase, 'timeout_warning'));
+  }
+
+  if (updatedState.status === 'active' && timeoutEvaluation.exceeded.length > 0) {
+    timeoutResult = timeoutEvaluation.exceeded[0];
+
+    if (timeoutResult.action === 'skip_phase' && timeoutResult.scope === 'phase') {
+      const skipAttempt = attemptTimeoutPhaseSkip({
+        root,
+        config,
+        updatedState,
+        nextHistoryEntries,
+        historyEntry,
+        timeoutResult,
+        now,
+      });
+
+      if (skipAttempt.ok) {
+        updatedState.phase = skipAttempt.updatedState.phase;
+        updatedState.phase_entered_at = skipAttempt.updatedState.phase_entered_at;
+        updatedState.last_gate_failure = skipAttempt.updatedState.last_gate_failure;
+        updatedState.phase_gate_status = skipAttempt.updatedState.phase_gate_status;
+        ledgerEntries.push(skipAttempt.ledgerEntry);
+      } else {
+        const escalatedTimeout = { ...timeoutResult, action: 'escalate' };
+        timeoutResult = escalatedTimeout;
+        updatedState.status = 'blocked';
+        updatedState.blocked_on = `timeout:${escalatedTimeout.scope}`;
+        updatedState.blocked_reason = buildBlockedReason({
+          ...buildTimeoutBlockedReason(escalatedTimeout, {
+            turnRetained: Object.keys(getActiveTurns(updatedState)).length > 0,
+          }),
+          turnId: currentTurn.turn_id,
+          blockedAt: now,
+        });
+        updatedState.last_gate_failure = skipAttempt.gateFailure || null;
+        if (skipAttempt.gateFailure?.gate_id) {
+          updatedState.phase_gate_status = {
+            ...(updatedState.phase_gate_status || {}),
+            [skipAttempt.gateFailure.gate_id]: 'failed',
+          };
+          ledgerEntries.push({
+            type: 'gate_failure',
+            ...skipAttempt.gateFailure,
+          });
+        }
+        ledgerEntries.push(skipAttempt.ledgerEntry);
+        ledgerEntries.push(buildTimeoutLedgerEntry(escalatedTimeout, now, currentTurn.turn_id, updatedState.phase));
+      }
+    } else if (timeoutResult.action === 'escalate') {
+      updatedState.status = 'blocked';
+      updatedState.blocked_on = `timeout:${timeoutResult.scope}`;
+      updatedState.blocked_reason = buildBlockedReason({
+        ...buildTimeoutBlockedReason(timeoutResult, {
+          turnRetained: Object.keys(getActiveTurns(updatedState)).length > 0,
+        }),
+        turnId: currentTurn.turn_id,
+        blockedAt: now,
+      });
+      ledgerEntries.push(buildTimeoutLedgerEntry(timeoutResult, now, currentTurn.turn_id, updatedState.phase));
+    }
+  }
+
   // ── Transaction journal: prepare before committing writes ──────────────
   const transactionId = generateId('txn');
   const journal = {
@@ -2974,9 +3319,11 @@ export function approvePhaseTransition(root, config) {
   const updatedState = {
     ...state,
     phase: transition.to,
+    phase_entered_at: new Date().toISOString(),
     status: 'active',
     blocked_on: null,
     blocked_reason: null,
+    last_gate_failure: null,
     pending_phase_transition: null,
     phase_gate_status: {
       ...(state.phase_gate_status || {}),
@@ -3071,6 +3418,7 @@ export function approveRunCompletion(root, config) {
     completed_at: new Date().toISOString(),
     blocked_on: null,
     blocked_reason: null,
+    last_gate_failure: null,
     pending_run_completion: null,
     phase_gate_status: {
       ...(state.phase_gate_status || {}),