agentxchain 2.46.0 → 2.47.0

package/src/lib/run-provenance.js

@@ -0,0 +1,90 @@
+const VALID_TRIGGERS = new Set([
+  'manual',
+  'continuation',
+  'recovery',
+  'intake',
+  'schedule',
+  'coordinator',
+]);
+
+const VALID_CREATORS = new Set([
+  'operator',
+  'coordinator',
+]);
+
+function normalizeString(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function normalizeRunProvenance(value, { fallbackManual = false } = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return fallbackManual ? buildDefaultRunProvenance() : null;
+  }
+
+  const trigger = normalizeString(value.trigger);
+  const createdBy = normalizeString(value.created_by);
+  const normalized = {
+    trigger: VALID_TRIGGERS.has(trigger) ? trigger : (fallbackManual ? 'manual' : null),
+    parent_run_id: normalizeString(value.parent_run_id),
+    trigger_reason: normalizeString(value.trigger_reason),
+    intake_intent_id: normalizeString(value.intake_intent_id),
+    created_by: VALID_CREATORS.has(createdBy) ? createdBy : 'operator',
+  };
+
+  if (!normalized.trigger) {
+    return fallbackManual ? buildDefaultRunProvenance() : null;
+  }
+
+  return normalized;
+}
+
+export function buildDefaultRunProvenance(overrides = {}) {
+  return normalizeRunProvenance({
+    trigger: 'manual',
+    parent_run_id: null,
+    trigger_reason: null,
+    intake_intent_id: null,
+    created_by: 'operator',
+    ...overrides,
+  }, { fallbackManual: true });
+}
+
+export function getRunTriggerLabel(provenance) {
+  const normalized = normalizeRunProvenance(provenance);
+  return normalized?.trigger || 'legacy';
+}
+
+export function summarizeRunProvenance(provenance) {
+  const normalized = normalizeRunProvenance(provenance);
+  if (!normalized) return null;
+
+  const details = [];
+  if (normalized.parent_run_id) {
+    details.push(`from ${normalized.parent_run_id}`);
+  }
+  if (normalized.intake_intent_id) {
+    details.push(`intent ${normalized.intake_intent_id}`);
+  }
+
+  const base = details.length > 0
+    ? `${normalized.trigger} ${details.join(' ')}`
+    : normalized.trigger;
+  const creatorSuffix = normalized.created_by === 'coordinator'
+    ? ' (created by coordinator)'
+    : '';
+  const reasonSuffix = normalized.trigger_reason
+    ? ` ("${normalized.trigger_reason}")`
+    : '';
+
+  if (
+    normalized.trigger === 'manual'
+    && !normalized.parent_run_id
+    && !normalized.intake_intent_id
+    && !normalized.trigger_reason
+    && normalized.created_by !== 'coordinator'
+  ) {
+    return null;
+  }
+
+  return `${base}${creatorSuffix}${reasonSuffix}`;
+}

package/src/lib/schema.js

@@ -74,6 +74,12 @@ export function validateGovernedStateSchema(data) {
     errors.push(`status must be one of: ${VALID_RUN_STATUSES.join(', ')}`);
   }
   if (typeof data.phase !== 'string' || !data.phase.trim()) errors.push('phase must be a non-empty string');
+  if ('created_at' in data && data.created_at !== null && (typeof data.created_at !== 'string' || !data.created_at.trim())) {
+    errors.push('created_at must be a non-empty string or null');
+  }
+  if ('phase_entered_at' in data && data.phase_entered_at !== null && (typeof data.phase_entered_at !== 'string' || !data.phase_entered_at.trim())) {
+    errors.push('phase_entered_at must be a non-empty string or null');
+  }
 
   if (isV1_1) {
     if (hasLegacyCurrentTurn) {
@@ -96,6 +102,47 @@ export function validateGovernedStateSchema(data) {
   if ('phase_gate_status' in data && data.phase_gate_status !== null && typeof data.phase_gate_status !== 'object') {
     errors.push('phase_gate_status must be an object');
   }
+  if ('last_gate_failure' in data && data.last_gate_failure !== null) {
+    if (typeof data.last_gate_failure !== 'object' || Array.isArray(data.last_gate_failure)) {
+      errors.push('last_gate_failure must be an object or null');
+    } else {
+      const failure = data.last_gate_failure;
+      const validGateTypes = ['phase_transition', 'run_completion'];
+      if (typeof failure.gate_type !== 'string' || !validGateTypes.includes(failure.gate_type)) {
+        errors.push(`last_gate_failure.gate_type must be one of: ${validGateTypes.join(', ')}`);
+      }
+      if (failure.gate_id !== null && failure.gate_id !== undefined && typeof failure.gate_id !== 'string') {
+        errors.push('last_gate_failure.gate_id must be a string or null');
+      }
+      if (typeof failure.phase !== 'string' || !failure.phase.trim()) {
+        errors.push('last_gate_failure.phase must be a non-empty string');
+      }
+      if (failure.from_phase !== null && failure.from_phase !== undefined && typeof failure.from_phase !== 'string') {
+        errors.push('last_gate_failure.from_phase must be a string or null');
+      }
+      if (failure.to_phase !== null && failure.to_phase !== undefined && typeof failure.to_phase !== 'string') {
+        errors.push('last_gate_failure.to_phase must be a string or null');
+      }
+      if (failure.requested_by_turn !== null && failure.requested_by_turn !== undefined && typeof failure.requested_by_turn !== 'string') {
+        errors.push('last_gate_failure.requested_by_turn must be a string or null');
+      }
+      if (typeof failure.failed_at !== 'string' || !failure.failed_at.trim()) {
+        errors.push('last_gate_failure.failed_at must be a non-empty string');
+      }
+      if (typeof failure.queued_request !== 'boolean') {
+        errors.push('last_gate_failure.queued_request must be a boolean');
+      }
+      if (!Array.isArray(failure.reasons) || failure.reasons.some((reason) => typeof reason !== 'string')) {
+        errors.push('last_gate_failure.reasons must be an array of strings');
+      }
+      if (!Array.isArray(failure.missing_files) || failure.missing_files.some((file) => typeof file !== 'string')) {
+        errors.push('last_gate_failure.missing_files must be an array of strings');
+      }
+      if (typeof failure.missing_verification !== 'boolean') {
+        errors.push('last_gate_failure.missing_verification must be a boolean');
+      }
+    }
+  }
   if ('budget_status' in data && data.budget_status !== null && typeof data.budget_status !== 'object') {
     errors.push('budget_status must be an object');
   }

package/src/lib/timeout-evaluator.js

@@ -0,0 +1,234 @@
+/**
+ * Timeout evaluator for governed runs.
+ *
+ * Checks per-turn, per-phase, and per-run time limits at governance boundaries.
+ * Returns timeout results that callers use to escalate, warn, or skip.
+ */
+
+const VALID_TIMEOUT_ACTIONS = ['escalate', 'warn', 'skip_phase'];
+
+/**
+ * Evaluate all configured timeouts against the current state.
+ *
+ * @param {object} options
+ * @param {object} options.config - Normalized config with optional `timeouts` section
+ * @param {object} options.state - Current governed state
+ * @param {object} [options.turn] - Active turn metadata being accepted (for per-turn check)
+ * @param {object} [options.turnResult] - Accepted turn result (legacy fallback for tests)
+ * @param {Date|string} [options.now] - Override for current time (testing)
+ * @returns {{ exceeded: Array<TimeoutResult>, warnings: Array<TimeoutResult> }}
+ */
+export function evaluateTimeouts({ config, state, turn = null, turnResult = null, now = new Date() }) {
+  const timeouts = config.timeouts;
+  if (!timeouts) return { exceeded: [], warnings: [] };
+
+  const nowMs = typeof now === 'string' ? new Date(now).getTime() : now.getTime();
+  const exceeded = [];
+  const warnings = [];
+
+  // Per-turn timeout
+  if (timeouts.per_turn_minutes) {
+    const startedAt = turn?.started_at || turn?.assigned_at || turnResult?.dispatched_at || turnResult?.assigned_at;
+    if (startedAt) {
+      const dispatchMs = new Date(startedAt).getTime();
+      const limitMs = timeouts.per_turn_minutes * 60 * 1000;
+      const elapsedMs = nowMs - dispatchMs;
+      if (elapsedMs > limitMs) {
+        const result = {
+          scope: 'turn',
+          limit_minutes: timeouts.per_turn_minutes,
+          elapsed_minutes: Math.round(elapsedMs / 60000),
+          exceeded_by_minutes: Math.round((elapsedMs - limitMs) / 60000),
+          action: resolveAction(timeouts.action, 'turn'),
+        };
+        if (result.action === 'warn') {
+          warnings.push(result);
+        } else {
+          exceeded.push(result);
+        }
+      }
+    }
+  }
+
+  // Per-phase timeout
+  const phaseLimit = resolvePhaseLimit(timeouts, config.routing, state.phase);
+  const phaseAction = resolvePhaseAction(timeouts, config.routing, state.phase);
+  if (phaseLimit) {
+    const phaseEnteredAt = findPhaseEntryTime(state);
+    if (phaseEnteredAt) {
+      const entryMs = new Date(phaseEnteredAt).getTime();
+      const limitMs = phaseLimit * 60 * 1000;
+      const elapsedMs = nowMs - entryMs;
+      if (elapsedMs > limitMs) {
+        const result = {
+          scope: 'phase',
+          phase: state.phase,
+          limit_minutes: phaseLimit,
+          elapsed_minutes: Math.round(elapsedMs / 60000),
+          exceeded_by_minutes: Math.round((elapsedMs - limitMs) / 60000),
+          action: phaseAction,
+        };
+        if (result.action === 'warn') {
+          warnings.push(result);
+        } else {
+          exceeded.push(result);
+        }
+      }
+    }
+  }
+
+  // Per-run timeout
+  if (timeouts.per_run_minutes) {
+    const createdAt = state.created_at;
+    if (createdAt) {
+      const createMs = new Date(createdAt).getTime();
+      const limitMs = timeouts.per_run_minutes * 60 * 1000;
+      const elapsedMs = nowMs - createMs;
+      if (elapsedMs > limitMs) {
+        const result = {
+          scope: 'run',
+          limit_minutes: timeouts.per_run_minutes,
+          elapsed_minutes: Math.round(elapsedMs / 60000),
+          exceeded_by_minutes: Math.round((elapsedMs - limitMs) / 60000),
+          action: resolveAction(timeouts.action, 'run'),
+        };
+        if (result.action === 'warn') {
+          warnings.push(result);
+        } else {
+          exceeded.push(result);
+        }
+      }
+    }
+  }
+
+  return { exceeded, warnings };
+}
+
+/**
+ * Resolve the phase-level timeout limit.
+ * Per-phase routing override takes precedence over global per_phase_minutes.
+ */
+function resolvePhaseLimit(timeouts, routing, phase) {
+  if (routing && routing[phase] && typeof routing[phase].timeout_minutes === 'number') {
+    return routing[phase].timeout_minutes;
+  }
+  return timeouts.per_phase_minutes || null;
+}
+
+/**
+ * Resolve the phase-level timeout action.
+ * Per-phase routing override takes precedence over global action.
+ */
+function resolvePhaseAction(timeouts, routing, phase) {
+  if (routing && routing[phase] && routing[phase].timeout_action) {
+    return routing[phase].timeout_action;
+  }
+  return timeouts.action || 'escalate';
+}
+
+/**
+ * Resolve the effective action, enforcing that skip_phase is only valid for phase scope.
+ */
+function resolveAction(action, scope) {
+  if (action === 'skip_phase' && scope !== 'phase') {
+    return 'escalate';
+  }
+  return action || 'escalate';
+}
+
+/**
+ * Find when the current phase was entered.
+ * Uses phase_entered_at if available, otherwise falls back to created_at for the first phase.
+ */
+function findPhaseEntryTime(state) {
+  if (state.phase_entered_at) return state.phase_entered_at;
+  // Fallback for first phase: use run creation time
+  return state.created_at || null;
+}
+
+/**
+ * Validate the timeouts config section.
+ * Returns { ok, errors }.
+ */
+export function validateTimeoutsConfig(timeouts, routing) {
+  const errors = [];
+
+  if (timeouts === null || timeouts === undefined) {
+    return { ok: true, errors: [] };
+  }
+
+  if (typeof timeouts !== 'object' || Array.isArray(timeouts)) {
+    errors.push('timeouts must be an object');
+    return { ok: false, errors };
+  }
+
+  if ('per_turn_minutes' in timeouts) {
+    if (typeof timeouts.per_turn_minutes !== 'number' || timeouts.per_turn_minutes < 1) {
+      errors.push('timeouts.per_turn_minutes must be a number >= 1');
+    }
+  }
+
+  if ('per_phase_minutes' in timeouts) {
+    if (typeof timeouts.per_phase_minutes !== 'number' || timeouts.per_phase_minutes < 1) {
+      errors.push('timeouts.per_phase_minutes must be a number >= 1');
+    }
+  }
+
+  if ('per_run_minutes' in timeouts) {
+    if (typeof timeouts.per_run_minutes !== 'number' || timeouts.per_run_minutes < 1) {
+      errors.push('timeouts.per_run_minutes must be a number >= 1');
+    }
+  }
+
+  if ('action' in timeouts) {
+    if (!VALID_TIMEOUT_ACTIONS.includes(timeouts.action)) {
+      errors.push(`timeouts.action must be one of: escalate, warn`);
+    }
+    if (timeouts.action === 'skip_phase') {
+      // skip_phase is only valid as a per-phase override, not as a global default
+      // because it makes no sense for per-turn or per-run timeouts
+      errors.push('timeouts.action cannot be "skip_phase" at the global level — use per-phase timeout_action override in routing instead');
+    }
+  }
+
+  // Per-phase timeout overrides in routing
+  if (routing) {
+    for (const [phase, route] of Object.entries(routing)) {
+      if ('timeout_minutes' in route) {
+        if (typeof route.timeout_minutes !== 'number' || route.timeout_minutes < 1) {
+          errors.push(`Routing "${phase}": timeout_minutes must be a number >= 1`);
+        }
+      }
+      if ('timeout_action' in route) {
+        if (!VALID_TIMEOUT_ACTIONS.includes(route.timeout_action)) {
+          errors.push(`Routing "${phase}": timeout_action must be one of: ${VALID_TIMEOUT_ACTIONS.join(', ')}`);
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Build a blocked_reason descriptor for a timeout.
+ */
+export function buildTimeoutBlockedReason(timeoutResult, options = {}) {
+  const scopeLabel = timeoutResult.scope === 'turn'
+    ? 'Turn timeout'
+    : timeoutResult.scope === 'phase'
+      ? `Phase timeout (${timeoutResult.phase || 'unknown'})`
+      : 'Run timeout';
+  const turnRetained = options.turnRetained === true;
+
+  return {
+    category: 'timeout',
+    recovery: {
+      typed_reason: 'timeout',
+      owner: 'operator',
+      recovery_action: 'agentxchain resume',
+      turn_retained: turnRetained,
+      detail: `${scopeLabel}: limit was ${timeoutResult.limit_minutes}m, elapsed ${timeoutResult.elapsed_minutes}m (exceeded by ${timeoutResult.exceeded_by_minutes}m)`,
+    },
+  };
+}