agentxchain 2.108.0 → 2.110.0

package/src/lib/dashboard/bridge-server.js

@@ -26,6 +26,9 @@ import { readWorkflowKitArtifacts } from './workflow-kit-artifacts.js';
 import { readConnectorHealthSnapshot } from './connectors.js';
 import { readTimeoutStatus } from './timeout-status.js';
 import { queryRunHistory } from '../run-history.js';
+import { loadProjectContext, loadProjectState } from '../config.js';
+import { evaluateApprovalSlaReminders } from '../notification-runner.js';
+import { readGateActionSnapshot } from './gate-action-reader.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -214,6 +217,40 @@ function resolveDashboardAssetPath(dashboardDir, pathname) {
   return { blocked: false, filePath };
 }
 
+function readDashboardPollStatus(workspacePath, replayMode) {
+  const body = {
+    ok: true,
+    polled_at: new Date().toISOString(),
+    replay_mode: replayMode,
+    governed_project_detected: false,
+    state_available: false,
+    reminder_evaluation: {
+      reminders_sent: [],
+      notifications_emitted: 0,
+    },
+  };
+
+  if (replayMode) {
+    return { ok: true, status: 200, body };
+  }
+
+  const context = loadProjectContext(workspacePath);
+  if (!context || context.config?.protocol_mode !== 'governed') {
+    return { ok: true, status: 200, body };
+  }
+
+  body.governed_project_detected = true;
+
+  const state = loadProjectState(context.root, context.config);
+  if (!state) {
+    return { ok: true, status: 200, body };
+  }
+
+  body.state_available = true;
+  body.reminder_evaluation = evaluateApprovalSlaReminders(context.root, context.config, state);
+  return { ok: true, status: 200, body };
+}
+
 // ── Bridge Server ───────────────────────────────────────────────────────────
 
 export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847, replayMode = false }) {
@@ -315,6 +352,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847,
       return;
     }
 
+    if (pathname === '/api/poll') {
+      const result = readDashboardPollStatus(workspacePath, replayMode);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     if (pathname === '/api/actions/approve-gate') {
       if (replayMode) {
         writeJson(res, 403, { ok: false, code: 'replay_mode', error: 'Replay mode: gate approval is not available on exported snapshots.' });
@@ -419,6 +462,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847,
       return;
     }
 
+    if (pathname === '/api/gate-actions') {
+      const result = readGateActionSnapshot(workspacePath);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     // API routes
     if (pathname.startsWith('/api/')) {
       const result = readResource(agentxchainDir, pathname);

package/src/lib/dashboard/gate-action-reader.js

@@ -0,0 +1,58 @@
+/**
+ * Gate-action reader — reads gate-action config and latest attempt for the dashboard.
+ *
+ * Follows the same pattern as other dashboard readers (connectors.js, timeout-status.js):
+ * returns { status, body } for the bridge server to serialize.
+ *
+ * Per DEC-DASHBOARD-GATE-ACTIONS-001: repo-local only, read-only.
+ */
+
+import { loadProjectContext, loadProjectState } from '../config.js';
+import { getGateActions, summarizeLatestGateActionAttempt } from '../gate-actions.js';
+
+/**
+ * Read gate-action snapshot for the current pending gate (if any).
+ *
+ * @param {string} workspacePath — project root
+ * @returns {{ status: number, body: object }}
+ */
+export function readGateActionSnapshot(workspacePath) {
+  const context = loadProjectContext(workspacePath);
+  if (!context || context.config?.protocol_mode !== 'governed') {
+    return { status: 200, body: { configured: [], latest_attempt: null } };
+  }
+
+  const state = loadProjectState(context.root, context.config);
+  if (!state) {
+    return { status: 200, body: { configured: [], latest_attempt: null } };
+  }
+
+  const pendingTransition = state.pending_phase_transition || null;
+  const pendingCompletion = state.pending_run_completion || null;
+
+  let gateType = null;
+  let gateId = null;
+
+  if (pendingTransition?.gate) {
+    gateType = 'phase_transition';
+    gateId = pendingTransition.gate;
+  } else if (pendingCompletion?.gate) {
+    gateType = 'run_completion';
+    gateId = pendingCompletion.gate;
+  }
+
+  if (!gateId) {
+    return { status: 200, body: { configured: [], latest_attempt: null } };
+  }
+
+  const configured = getGateActions(context.config, gateId);
+  const latestAttempt = summarizeLatestGateActionAttempt(context.root, gateType, gateId);
+
+  return {
+    status: 200,
+    body: {
+      configured,
+      latest_attempt: latestAttempt,
+    },
+  };
+}

package/src/lib/dashboard/timeout-status.js

@@ -73,6 +73,30 @@ function emptyLiveTimeouts() {
   return { exceeded: [], warnings: [] };
 }
 
+function buildLiveContext(state) {
+  const pendingPhase = state?.pending_phase_transition;
+  const pendingCompletion = state?.pending_run_completion;
+  if (pendingPhase) {
+    return {
+      awaiting_approval: true,
+      pending_gate_type: 'phase_transition',
+      requested_at: typeof pendingPhase.requested_at === 'string' ? pendingPhase.requested_at : null,
+    };
+  }
+  if (pendingCompletion) {
+    return {
+      awaiting_approval: true,
+      pending_gate_type: 'run_completion',
+      requested_at: typeof pendingCompletion.requested_at === 'string' ? pendingCompletion.requested_at : null,
+    };
+  }
+  return {
+    awaiting_approval: false,
+    pending_gate_type: null,
+    requested_at: null,
+  };
+}
+
 function getActiveTurns(state) {
   if (!state?.active_turns || typeof state.active_turns !== 'object' || Array.isArray(state.active_turns)) {
     return [];
@@ -90,7 +114,8 @@ function annotateTurnTimeout(result, state, turn) {
 }
 
 export function evaluateDashboardTimeoutPressure(config, state, now = new Date()) {
-  if (!config?.timeouts || state?.status !== 'active') {
+  const approvalPending = Boolean(state?.pending_phase_transition || state?.pending_run_completion);
+  if (!config?.timeouts || (state?.status !== 'active' && !approvalPending)) {
     return emptyLiveTimeouts();
   }
 
@@ -100,16 +125,18 @@ export function evaluateDashboardTimeoutPressure(config, state, now = new Date()
     warnings: [...base.warnings],
   };
 
-  for (const turn of getActiveTurns(state)) {
-    const turnEval = evaluateTimeouts({ config, state, turn, now });
-    for (const item of turnEval.exceeded) {
-      if (item.scope === 'turn') {
-        live.exceeded.push(annotateTurnTimeout(item, state, turn));
+  if (state?.status === 'active') {
+    for (const turn of getActiveTurns(state)) {
+      const turnEval = evaluateTimeouts({ config, state, turn, now });
+      for (const item of turnEval.exceeded) {
+        if (item.scope === 'turn') {
+          live.exceeded.push(annotateTurnTimeout(item, state, turn));
+        }
       }
-    }
-    for (const item of turnEval.warnings) {
-      if (item.scope === 'turn') {
-        live.warnings.push(annotateTurnTimeout(item, state, turn));
+      for (const item of turnEval.warnings) {
+        if (item.scope === 'turn') {
+          live.warnings.push(annotateTurnTimeout(item, state, turn));
+        }
       }
     }
   }
@@ -172,6 +199,7 @@ export function readTimeoutStatus(workspacePath) {
         configured: false,
         config: null,
         live: null,
+        live_context: null,
         events: [],
       },
     };
@@ -190,12 +218,13 @@ export function readTimeoutStatus(workspacePath) {
   return {
     ok: true,
     status: 200,
-    body: {
-      ok: true,
-      configured: true,
-      config: configSummary,
-      live,
-      events,
-    },
-  };
+      body: {
+        ok: true,
+        configured: true,
+        config: configSummary,
+        live,
+        live_context: buildLiveContext(state),
+        events,
+      },
+    };
 }

package/src/lib/gate-actions.js

@@ -0,0 +1,263 @@
+import { randomBytes } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+
+const LEDGER_PATH = '.agentxchain/decision-ledger.jsonl';
+const MAX_OUTPUT_TAIL_CHARS = 1200;
+export const DEFAULT_GATE_ACTION_TIMEOUT_MS = 15 * 60 * 1000;
+const MIN_GATE_ACTION_TIMEOUT_MS = 1000;
+const MAX_GATE_ACTION_TIMEOUT_MS = 60 * 60 * 1000;
+
+function normalizeGateActionTimeoutMs(action) {
+  if (Number.isInteger(action?.timeout_ms)) {
+    return action.timeout_ms;
+  }
+  return DEFAULT_GATE_ACTION_TIMEOUT_MS;
+}
+
+export function validateGateActionsConfig(gates, errors) {
+  if (!gates || typeof gates !== 'object' || Array.isArray(gates)) {
+    errors.push('gates must be an object');
+    return;
+  }
+
+  for (const [gateId, gate] of Object.entries(gates)) {
+    if (!gate || typeof gate !== 'object' || Array.isArray(gate)) {
+      errors.push(`Gate "${gateId}" must be an object`);
+      continue;
+    }
+
+    if (!('gate_actions' in gate)) {
+      continue;
+    }
+
+    if (!Array.isArray(gate.gate_actions) || gate.gate_actions.length === 0) {
+      errors.push(`Gate "${gateId}": gate_actions must be a non-empty array when provided`);
+      continue;
+    }
+
+    if (gate.requires_human_approval !== true) {
+      errors.push(`Gate "${gateId}": gate_actions require requires_human_approval: true`);
+    }
+
+    for (let i = 0; i < gate.gate_actions.length; i++) {
+      const action = gate.gate_actions[i];
+      const prefix = `gates.${gateId}.gate_actions[${i}]`;
+      if (!action || typeof action !== 'object' || Array.isArray(action)) {
+        errors.push(`${prefix} must be an object`);
+        continue;
+      }
+      if (typeof action.run !== 'string' || !action.run.trim()) {
+        errors.push(`${prefix}.run must be a non-empty string`);
+      }
+      if ('label' in action && (typeof action.label !== 'string' || !action.label.trim())) {
+        errors.push(`${prefix}.label must be a non-empty string when provided`);
+      }
+      if ('timeout_ms' in action) {
+        if (!Number.isInteger(action.timeout_ms)
+          || action.timeout_ms < MIN_GATE_ACTION_TIMEOUT_MS
+          || action.timeout_ms > MAX_GATE_ACTION_TIMEOUT_MS) {
+          errors.push(
+            `${prefix}.timeout_ms must be an integer between ${MIN_GATE_ACTION_TIMEOUT_MS} and ${MAX_GATE_ACTION_TIMEOUT_MS} when provided`,
+          );
+        }
+      }
+    }
+  }
+}
+
+export function getGateActions(config, gateId) {
+  const actions = config?.gates?.[gateId]?.gate_actions;
+  if (!Array.isArray(actions) || actions.length === 0) {
+    return [];
+  }
+
+  return actions
+    .filter((action) => action && typeof action === 'object' && typeof action.run === 'string' && action.run.trim())
+    .map((action, index) => ({
+      index: index + 1,
+      label: typeof action.label === 'string' && action.label.trim() ? action.label.trim() : null,
+      run: action.run.trim(),
+      timeout_ms: normalizeGateActionTimeoutMs(action),
+    }));
+}
+
+function trimOutputTail(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (trimmed.length <= MAX_OUTPUT_TAIL_CHARS) {
+    return trimmed;
+  }
+  return trimmed.slice(-MAX_OUTPUT_TAIL_CHARS);
+}
+
+function buildGateActionEntry(action, meta, runtimeResult, status) {
+  const timedOut = runtimeResult?.error?.code === 'ETIMEDOUT';
+  const stderrTail = trimOutputTail(runtimeResult?.stderr) || (timedOut ? `Timed out after ${action.timeout_ms}ms` : null);
+  const spawnError = timedOut
+    ? `Timed out after ${action.timeout_ms}ms`
+    : runtimeResult?.error?.message || null;
+  return {
+    type: 'gate_action',
+    timestamp: new Date().toISOString(),
+    attempt_id: meta.attemptId,
+    gate_id: meta.gateId,
+    gate_type: meta.gateType,
+    phase: meta.phase || null,
+    requested_by_turn: meta.requestedByTurn || null,
+    trigger_command: meta.triggerCommand || null,
+    action_index: action.index,
+    action_label: action.label,
+    command: action.run,
+    timeout_ms: action.timeout_ms,
+    status,
+    exit_code: Number.isInteger(runtimeResult?.status) ? runtimeResult.status : null,
+    signal: runtimeResult?.signal || null,
+    stdout_tail: trimOutputTail(runtimeResult?.stdout),
+    stderr_tail: stderrTail,
+    spawn_error: spawnError,
+    timed_out: timedOut,
+  };
+}
+
+export function executeGateActions(root, config, meta, opts = {}) {
+  const actions = getGateActions(config, meta.gateId);
+  if (actions.length === 0) {
+    return { ok: true, dry_run: Boolean(opts.dryRun), actions: [] };
+  }
+
+  if (opts.dryRun) {
+    return { ok: true, dry_run: true, actions };
+  }
+
+  const attemptId = `ga_${Date.now()}_${randomBytes(4).toString('hex')}`;
+  const results = [];
+
+  for (const action of actions) {
+    const runtimeResult = spawnSync('/bin/sh', ['-lc', action.run], {
+      cwd: root,
+      env: {
+        ...process.env,
+        AGENTXCHAIN_GATE_ID: meta.gateId,
+        AGENTXCHAIN_GATE_TYPE: meta.gateType,
+        AGENTXCHAIN_PHASE: meta.phase || '',
+        AGENTXCHAIN_REQUESTED_BY_TURN: meta.requestedByTurn || '',
+        AGENTXCHAIN_TRIGGER_COMMAND: meta.triggerCommand || '',
+      },
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: action.timeout_ms,
+      killSignal: 'SIGTERM',
+    });
+
+    const status = runtimeResult.error || runtimeResult.status !== 0 ? 'failed' : 'succeeded';
+    const entry = buildGateActionEntry(action, { ...meta, attemptId }, runtimeResult, status);
+    results.push(entry);
+
+    if (status === 'failed') {
+      return {
+        ok: false,
+        attempt_id: attemptId,
+        actions: results,
+        failed_action: entry,
+        error: `Gate action failed for "${meta.gateId}": ${action.label || action.run}`,
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    attempt_id: attemptId,
+    actions: results,
+  };
+}
+
+export function normalizeGateActionEntry(entry) {
+  if (!entry || entry.type !== 'gate_action') {
+    return null;
+  }
+
+  return {
+    attempt_id: entry.attempt_id || null,
+    gate_id: entry.gate_id || null,
+    gate_type: entry.gate_type || null,
+    phase: entry.phase || null,
+    requested_by_turn: entry.requested_by_turn || null,
+    trigger_command: entry.trigger_command || null,
+    action_index: Number.isInteger(entry.action_index) ? entry.action_index : null,
+    action_label: entry.action_label || null,
+    command: entry.command || null,
+    status: entry.status || 'unknown',
+    exit_code: Number.isInteger(entry.exit_code) ? entry.exit_code : null,
+    signal: entry.signal || null,
+    stdout_tail: entry.stdout_tail || null,
+    stderr_tail: entry.stderr_tail || null,
+    spawn_error: entry.spawn_error || null,
+    timeout_ms: Number.isInteger(entry.timeout_ms) ? entry.timeout_ms : null,
+    timed_out: entry.timed_out === true,
+    timestamp: entry.timestamp || null,
+  };
+}
+
+export function extractGateActionDigest(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return [];
+  }
+
+  return entries
+    .map(normalizeGateActionEntry)
+    .filter(Boolean)
+    .sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
+}
+
+export function readGateActionEntries(root) {
+  const filePath = join(root, LEDGER_PATH);
+  if (!existsSync(filePath)) {
+    return [];
+  }
+
+  const raw = readFileSync(filePath, 'utf8').trim();
+  if (!raw) {
+    return [];
+  }
+
+  const entries = raw
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  return extractGateActionDigest(entries);
+}
+
+export function summarizeLatestGateActionAttempt(root, gateType, gateId) {
+  const entries = readGateActionEntries(root)
+    .filter((entry) => entry.gate_type === gateType && entry.gate_id === gateId);
+
+  if (entries.length === 0) {
+    return null;
+  }
+
+  const latest = entries[entries.length - 1];
+  const attemptEntries = entries.filter((entry) => entry.attempt_id === latest.attempt_id);
+  return {
+    attempt_id: latest.attempt_id,
+    gate_id: gateId,
+    gate_type: gateType,
+    status: attemptEntries.some((entry) => entry.status === 'failed') ? 'failed' : 'succeeded',
+    attempted_at: latest.timestamp || null,
+    actions: attemptEntries,
+  };
+}