agentxchain 2.6.0 → 2.8.0

package/src/lib/governed-state.js

@@ -34,6 +34,7 @@ import {
 import { getMaxConcurrentTurns } from './normalized-config.js';
 import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir } from './turn-paths.js';
 import { runHooks } from './hook-runner.js';
+import { emitNotifications } from './notification-runner.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -53,6 +54,29 @@ function generateId(prefix) {
   return `${prefix}_${randomBytes(8).toString('hex')}`;
 }
 
+function emitBlockedNotification(root, config, state, details = {}, turn = null) {
+  if (!config?.notifications?.webhooks?.length) {
+    return;
+  }
+
+  const recovery = state?.blocked_reason?.recovery || details.recovery || null;
+  emitNotifications(root, config, state, 'run_blocked', {
+    category: state?.blocked_reason?.category || details.category || 'unknown_block',
+    blocked_on: state?.blocked_on || details.blockedOn || null,
+    typed_reason: recovery?.typed_reason || null,
+    owner: recovery?.owner || null,
+    recovery_action: recovery?.recovery_action || null,
+    detail: recovery?.detail || null,
+  }, turn);
+}
+
+function emitPendingLifecycleNotification(root, config, state, eventType, payload, turn = null) {
+  if (!config?.notifications?.webhooks?.length) {
+    return;
+  }
+  emitNotifications(root, config, state, eventType, payload, turn);
+}
+
 function normalizeActiveTurns(activeTurns) {
   if (!activeTurns || typeof activeTurns !== 'object' || Array.isArray(activeTurns)) {
     return {};
@@ -555,6 +579,22 @@ function buildBlockedReason({ category, recovery, turnId, blockedAt = new Date()
   };
 }
 
+function slugifyEscalationReason(reason) {
+  if (typeof reason !== 'string') {
+    return 'operator';
+  }
+  const slug = reason
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'operator';
+}
+
+function isOperatorEscalationBlockedOn(blockedOn) {
+  return typeof blockedOn === 'string' && blockedOn.startsWith('escalation:operator:');
+}
+
 function canApprovePendingGate(state) {
   return state?.status === 'paused' || state?.status === 'blocked';
 }
@@ -599,7 +639,7 @@ function deriveHookRecovery(state, { phase, hookName, detail, errorCode, turnId,
   };
 }
 
-function blockRunForHookIssue(root, state, { phase, turnId, hookName, detail, errorCode, turnRetained }) {
+function blockRunForHookIssue(root, state, { phase, turnId, hookName, detail, errorCode, turnRetained, notificationConfig }) {
   const blockedAt = new Date().toISOString();
   const typedReason = errorCode?.includes('_tamper') ? 'hook_tamper' : 'hook_block';
   const recovery = deriveHookRecovery(state, {
@@ -622,6 +662,11 @@ function blockRunForHookIssue(root, state, { phase, turnId, hookName, detail, er
     }),
   };
   writeState(root, blockedState);
+  emitBlockedNotification(root, notificationConfig, blockedState, {
+    category: typedReason,
+    blockedOn: blockedState.blocked_on,
+    recovery,
+  }, turnId ? getActiveTurns(blockedState)[turnId] || null : null);
   return attachLegacyCurrentTurnAlias(blockedState);
 }
 
@@ -694,14 +739,18 @@ function inferBlockedReasonFromState(state) {
   }
 
   if (state.blocked_on.startsWith('escalation:')) {
+    const isOperatorEscalation = isOperatorEscalationBlockedOn(state.blocked_on) || state.escalation?.source === 'operator';
+    const recoveryAction = turnRetained
+      ? 'Resolve the escalation, then run agentxchain step --resume'
+      : 'Resolve the escalation, then run agentxchain step';
     return buildBlockedReason({
-      category: 'retries_exhausted',
+      category: isOperatorEscalation ? 'operator_escalation' : 'retries_exhausted',
       recovery: {
-        typed_reason: 'retries_exhausted',
+        typed_reason: isOperatorEscalation ? 'operator_escalation' : 'retries_exhausted',
         owner: 'human',
-        recovery_action: 'Resolve the escalation, then run agentxchain step --resume',
+        recovery_action: recoveryAction,
         turn_retained: turnRetained,
-        detail: state.blocked_on,
+        detail: state.escalation?.detail || state.escalation?.reason || state.blocked_on,
       },
       turnId: activeTurn?.turn_id ?? null,
     });
@@ -819,6 +868,12 @@ export function markRunBlocked(root, details) {
 
   writeState(root, updatedState);
 
+  emitBlockedNotification(root, details.notificationConfig, updatedState, {
+    category: details.category,
+    blockedOn: details.blockedOn,
+    recovery: details.recovery,
+  }, turnId ? getActiveTurns(updatedState)[turnId] || null : null);
+
   // Fire on_escalation hooks (advisory-only) after blocked state is persisted.
   // Only fire for non-hook-caused blocks to prevent circular invocations.
   if (details.hooksConfig?.on_escalation?.length > 0) {
@@ -837,6 +892,141 @@ export function markRunBlocked(root, details) {
   return { ok: true, state: updatedState };
 }
 
+export function raiseOperatorEscalation(root, config, details) {
+  const state = readState(root);
+  if (!state) {
+    return { ok: false, error: 'No governed state.json found' };
+  }
+
+  const reason = typeof details.reason === 'string' ? details.reason.trim() : '';
+  if (!reason) {
+    return { ok: false, error: 'Escalation reason is required.' };
+  }
+
+  if (state.status !== 'active') {
+    return { ok: false, error: `Cannot escalate run: status is "${state.status}", expected "active"` };
+  }
+
+  const activeTurns = getActiveTurns(state);
+  let targetTurn = null;
+  if (details.turnId) {
+    targetTurn = activeTurns[details.turnId] || null;
+    if (!targetTurn) {
+      return { ok: false, error: `No active turn found for --turn ${details.turnId}` };
+    }
+  } else {
+    const turns = Object.values(activeTurns);
+    if (turns.length > 1) {
+      return { ok: false, error: 'Multiple active turns exist. Use --turn <id> to target the escalation.' };
+    }
+    targetTurn = turns[0] || null;
+  }
+
+  const turnRetained = Boolean(targetTurn);
+  const recoveryAction = details.action
+    || (turnRetained
+      ? 'Resolve the escalation, then run agentxchain step --resume'
+      : 'Resolve the escalation, then run agentxchain step');
+  const detail = typeof details.detail === 'string' && details.detail.trim()
+    ? details.detail.trim()
+    : reason;
+  const blockedOn = `escalation:operator:${slugifyEscalationReason(reason)}`;
+  const escalatedAt = new Date().toISOString();
+
+  const escalation = {
+    source: 'operator',
+    raised_by: 'human',
+    from_role: targetTurn?.assigned_role || null,
+    from_turn_id: targetTurn?.turn_id || null,
+    reason,
+    detail,
+    recovery_action: recoveryAction,
+    escalated_at: escalatedAt,
+  };
+
+  const blocked = markRunBlocked(root, {
+    blockedOn,
+    category: 'operator_escalation',
+    recovery: {
+      typed_reason: 'operator_escalation',
+      owner: 'human',
+      recovery_action: recoveryAction,
+      turn_retained: turnRetained,
+      detail,
+    },
+    turnId: targetTurn?.turn_id || null,
+    escalation,
+    hooksConfig: config?.hooks || {},
+    notificationConfig: config,
+  });
+  if (!blocked.ok) {
+    return blocked;
+  }
+
+  appendJsonl(root, LEDGER_PATH, {
+    timestamp: escalatedAt,
+    decision: 'operator_escalated',
+    run_id: blocked.state.run_id,
+    phase: blocked.state.phase,
+    blocked_on: blockedOn,
+    escalation,
+  });
+
+  emitPendingLifecycleNotification(root, config, blocked.state, 'operator_escalation_raised', {
+    source: 'operator',
+    blocked_on: blockedOn,
+    reason,
+    detail,
+    recovery_action: recoveryAction,
+  }, targetTurn);
+
+  return {
+    ok: true,
+    state: attachLegacyCurrentTurnAlias(blocked.state),
+    escalation,
+  };
+}
+
+export function reactivateGovernedRun(root, state, details = {}) {
+  if (!state || typeof state !== 'object') {
+    return { ok: false, error: 'State is required.' };
+  }
+
+  const now = new Date().toISOString();
+  const wasEscalation = state.status === 'blocked' && typeof state.blocked_on === 'string' && state.blocked_on.startsWith('escalation:');
+  const nextState = {
+    ...state,
+    status: 'active',
+    blocked_on: null,
+    blocked_reason: null,
+    escalation: null,
+  };
+
+  writeState(root, nextState);
+
+  if (wasEscalation) {
+    appendJsonl(root, LEDGER_PATH, {
+      timestamp: now,
+      decision: 'escalation_resolved',
+      run_id: state.run_id,
+      phase: state.phase,
+      resolved_via: details.via || 'unknown',
+      blocked_on: state.blocked_on,
+      escalation: state.escalation || null,
+      turn_id: state.escalation?.from_turn_id ?? getActiveTurn(state)?.turn_id ?? null,
+      role: state.escalation?.from_role ?? getActiveTurn(state)?.assigned_role ?? null,
+    });
+
+    emitPendingLifecycleNotification(details.root || root, details.notificationConfig, nextState, 'escalation_resolved', {
+      blocked_on: state.blocked_on,
+      resolved_via: details.via || 'unknown',
+      previous_escalation: state.escalation || null,
+    }, state.escalation?.from_turn_id ? getActiveTurns(state)[state.escalation.from_turn_id] || getActiveTurn(state) : getActiveTurn(state));
+  }
+
+  return { ok: true, state: attachLegacyCurrentTurnAlias(nextState) };
+}
+
 // ── Core Operations ──────────────────────────────────────────────────────────
 
 /**
@@ -1014,6 +1204,7 @@ export function assignGovernedTurn(root, config, roleId) {
           detail,
           errorCode: beforeAssignmentHooks.tamper.error_code,
           turnRetained: activeCount > 0,
+          notificationConfig: config,
         });
         return {
           ok: false,
@@ -1240,6 +1431,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         detail,
         errorCode: beforeValidationHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: true,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -1281,6 +1473,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         detail,
         errorCode: afterValidationHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: true,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -1426,6 +1619,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         detail,
         errorCode: beforeAcceptanceHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: true,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -1698,6 +1892,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         detail,
         errorCode: hookResults.tamper?.error_code || 'hook_post_commit_error',
         turnRetained: Object.keys(getActiveTurns(updatedState)).length > 0,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -1713,6 +1908,39 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     }
   }
 
+  if (updatedState.status === 'blocked') {
+    emitBlockedNotification(root, config, updatedState, {
+      category: updatedState.blocked_reason?.category || 'needs_human',
+      blockedOn: updatedState.blocked_on,
+      recovery: updatedState.blocked_reason?.recovery || null,
+    }, currentTurn);
+  }
+
+  if (updatedState.pending_phase_transition) {
+    emitPendingLifecycleNotification(root, config, updatedState, 'phase_transition_pending', {
+      from: updatedState.pending_phase_transition.from,
+      to: updatedState.pending_phase_transition.to,
+      gate: updatedState.pending_phase_transition.gate,
+      requested_by_turn: updatedState.pending_phase_transition.requested_by_turn,
+    }, currentTurn);
+  }
+
+  if (updatedState.pending_run_completion) {
+    emitPendingLifecycleNotification(root, config, updatedState, 'run_completion_pending', {
+      gate: updatedState.pending_run_completion.gate,
+      requested_by_turn: updatedState.pending_run_completion.requested_by_turn,
+      requested_at: updatedState.pending_run_completion.requested_at,
+    }, currentTurn);
+  }
+
+  if (updatedState.status === 'completed') {
+    emitPendingLifecycleNotification(root, config, updatedState, 'run_completed', {
+      completed_at: updatedState.completed_at || now,
+      completed_via: completionResult?.action === 'complete' ? 'accept_turn' : 'accept_turn_direct',
+      requested_by_turn: completionResult?.requested_by_turn || turnResult.turn_id,
+    }, currentTurn);
+  }
+
   return {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),
@@ -1898,6 +2126,12 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
 
   writeState(root, updatedState);
 
+  emitBlockedNotification(root, config, updatedState, {
+    category: 'retries_exhausted',
+    blockedOn: updatedState.blocked_on,
+    recovery: updatedState.blocked_reason?.recovery || null,
+  }, updatedState.active_turns[currentTurn.turn_id]);
+
   // Fire on_escalation hooks (advisory-only) after blocked state is persisted.
   const hooksConfig = config?.hooks || {};
   if (hooksConfig.on_escalation?.length > 0) {
@@ -1977,6 +2211,7 @@ export function approvePhaseTransition(root, config) {
         detail,
         errorCode: gateHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: false,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -2067,6 +2302,7 @@ export function approveRunCompletion(root, config) {
         detail,
         errorCode: gateHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: false,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -2093,6 +2329,13 @@ export function approveRunCompletion(root, config) {
 
   writeState(root, updatedState);
 
+  emitPendingLifecycleNotification(root, config, updatedState, 'run_completed', {
+    completed_at: updatedState.completed_at,
+    completed_via: 'approve_run_completion',
+    gate: completion.gate,
+    requested_by_turn: completion.requested_by_turn || null,
+  }, completion.requested_by_turn ? getActiveTurns(state)[completion.requested_by_turn] || null : null);
+
   return {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),
@@ -2136,4 +2379,10 @@ function deriveNextRecommendedRole(turnResult, state, config) {
   return routing?.entry_role || null;
 }
 
-export { STATE_PATH, HISTORY_PATH, LEDGER_PATH, STAGING_PATH, TALK_PATH };
+export {
+  STATE_PATH,
+  HISTORY_PATH,
+  LEDGER_PATH,
+  STAGING_PATH,
+  TALK_PATH,
+};

package/src/lib/normalized-config.js

@@ -13,6 +13,7 @@
  */
 
 import { validateHooksConfig } from './hook-runner.js';
+import { validateNotificationsConfig } from './notification-runner.js';
 import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
@@ -425,6 +426,12 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...hookValidation.errors);
   }
 
+  // Notifications (optional but validated if present)
+  if (data.notifications) {
+    const notificationValidation = validateNotificationsConfig(data.notifications);
+    errors.push(...notificationValidation.errors);
+  }
+
   return { ok: errors.length === 0, errors };
 }
 
@@ -467,6 +474,7 @@ export function normalizeV3(raw) {
     routing: buildLegacyRouting(Object.keys(agents)),
     gates: {},
     hooks: {},
+    notifications: {},
     budget: null,
     retention: {
       talk_strategy: 'append_only',
@@ -526,6 +534,7 @@ export function normalizeV4(raw) {
     routing: raw.routing || {},
     gates: raw.gates || {},
     hooks: raw.hooks || {},
+    notifications: raw.notifications || {},
     budget: raw.budget || null,
     retention: raw.retention || {
       talk_strategy: 'append_only',