agentxchain 2.46.0 → 2.46.2

package/src/lib/approval-policy.js

@@ -0,0 +1,139 @@
+/**
+ * Approval Policy evaluator — pure library for conditional auto-approval.
+ *
+ * Sits between the gate evaluator and the state machine. When a gate returns
+ * 'awaiting_human_approval', this module evaluates the configured approval_policy
+ * to determine whether the gate should auto-approve or pause for human approval.
+ *
+ * Invariants:
+ *   - Only evaluates when gateResult.action === 'awaiting_human_approval'
+ *   - Can only relax the human-approval requirement, never override gate failures
+ *   - --auto-approve on run overrides this entirely (handled in run.js)
+ *   - Absent approval_policy → always require_human (backwards compatible)
+ */
+
+/**
+ * Evaluate approval policy for a gate result.
+ *
+ * @param {object} params
+ * @param {object} params.gateResult - from evaluatePhaseExit or evaluateRunCompletion
+ * @param {'phase_transition'|'run_completion'} params.gateType
+ * @param {object} params.state - current run state
+ * @param {object} params.config - normalized config
+ * @returns {{ action: 'auto_approve'|'require_human', matched_rule: object|null, reason: string }}
+ */
+export function evaluateApprovalPolicy({ gateResult, gateType, state, config }) {
+  const policy = config?.approval_policy;
+
+  // No policy configured → always require human
+  if (!policy) {
+    return { action: 'require_human', matched_rule: null, reason: 'no approval_policy configured' };
+  }
+
+  if (gateType === 'run_completion') {
+    return evaluateRunCompletionPolicy({ gateResult, state, config, policy });
+  }
+
+  return evaluatePhaseTransitionPolicy({ gateResult, state, config, policy });
+}
+
+function evaluateRunCompletionPolicy({ gateResult, state, config, policy }) {
+  const rc = policy.run_completion;
+  if (!rc || !rc.action) {
+    return { action: 'require_human', matched_rule: null, reason: 'no run_completion policy' };
+  }
+
+  if (rc.action === 'require_human') {
+    return { action: 'require_human', matched_rule: rc, reason: 'run_completion policy requires human approval' };
+  }
+
+  // action === 'auto_approve' — check conditions
+  if (rc.when) {
+    const conditionResult = checkConditions(rc.when, { gateResult, state, config });
+    if (!conditionResult.ok) {
+      return { action: 'require_human', matched_rule: rc, reason: conditionResult.reason };
+    }
+  }
+
+  return { action: 'auto_approve', matched_rule: rc, reason: 'run_completion policy auto-approved' };
+}
+
+function evaluatePhaseTransitionPolicy({ gateResult, state, config, policy }) {
+  const pt = policy.phase_transitions;
+  if (!pt) {
+    return { action: 'require_human', matched_rule: null, reason: 'no phase_transitions policy' };
+  }
+
+  const fromPhase = state.phase;
+  const toPhase = gateResult.next_phase;
+
+  // Check rules (first match wins)
+  if (Array.isArray(pt.rules)) {
+    for (const rule of pt.rules) {
+      if (ruleMatches(rule, fromPhase, toPhase)) {
+        if (rule.action === 'require_human') {
+          return { action: 'require_human', matched_rule: rule, reason: `rule matched: ${fromPhase} → ${toPhase} requires human` };
+        }
+        // action === 'auto_approve' — check conditions
+        if (rule.when) {
+          const conditionResult = checkConditions(rule.when, { gateResult, state, config });
+          if (!conditionResult.ok) {
+            return { action: 'require_human', matched_rule: rule, reason: conditionResult.reason };
+          }
+        }
+        return { action: 'auto_approve', matched_rule: rule, reason: `rule matched: ${fromPhase} → ${toPhase} auto-approved` };
+      }
+    }
+  }
+
+  // No rule matched → use default
+  const defaultAction = pt.default || 'require_human';
+  return { action: defaultAction, matched_rule: null, reason: `default: ${defaultAction}` };
+}
+
+function ruleMatches(rule, fromPhase, toPhase) {
+  if (rule.from_phase && rule.from_phase !== fromPhase) return false;
+  if (rule.to_phase && rule.to_phase !== toPhase) return false;
+  return true;
+}
+
+/**
+ * Check when conditions. Returns { ok, reason }.
+ */
+function checkConditions(when, { gateResult, state, config }) {
+  // gate_passed: gate structural predicates must have passed
+  if (when.gate_passed === true && !gateResult.passed) {
+    return { ok: false, reason: 'condition gate_passed not met: gate did not pass structural predicates' };
+  }
+
+  // roles_participated: specified roles must have accepted turns in the current phase
+  if (Array.isArray(when.roles_participated) && when.roles_participated.length > 0) {
+    const phase = state.phase;
+    const history = Array.isArray(state.history) ? state.history : [];
+    for (const roleId of when.roles_participated) {
+      const participated = history.some(
+        turn => turn.phase === phase && turn.role === roleId,
+      );
+      if (!participated) {
+        return { ok: false, reason: `condition roles_participated not met: role "${roleId}" has no accepted turn in phase "${phase}"` };
+      }
+    }
+  }
+
+  // all_phases_visited: every routing phase must appear in history
+  if (when.all_phases_visited === true) {
+    const routingPhases = Object.keys(config.routing || {});
+    const visitedPhases = new Set(
+      (Array.isArray(state.history) ? state.history : []).map(t => t.phase),
+    );
+    // Also include current phase
+    visitedPhases.add(state.phase);
+    for (const phase of routingPhases) {
+      if (!visitedPhases.has(phase)) {
+        return { ok: false, reason: `condition all_phases_visited not met: phase "${phase}" never visited` };
+      }
+    }
+  }
+
+  return { ok: true, reason: 'all conditions met' };
+}

package/src/lib/blocked-state.js

@@ -182,6 +182,17 @@ export function deriveRecoveryDescriptor(state, config = null) {
     };
   }
 
+  if (state.blocked_on.startsWith('timeout:')) {
+    const scope = state.blocked_on.slice('timeout:'.length).trim() || 'unknown';
+    return {
+      typed_reason: 'timeout',
+      owner: 'operator',
+      recovery_action: 'agentxchain resume',
+      turn_retained: false,
+      detail: `${scope} timeout exceeded`,
+    };
+  }
+
   return {
     typed_reason: 'unknown_block',
     owner: 'human',

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

@@ -18,8 +18,10 @@ import { readResource } from './state-reader.js';
 import { FileWatcher } from './file-watcher.js';
 import { approvePendingDashboardGate } from './actions.js';
 import { readCoordinatorBlockerSnapshot } from './coordinator-blockers.js';
+import { readCoordinatorTimeoutStatus } from './coordinator-timeout-status.js';
 import { readWorkflowKitArtifacts } from './workflow-kit-artifacts.js';
 import { readConnectorHealthSnapshot } from './connectors.js';
+import { readTimeoutStatus } from './timeout-status.js';
 import { queryRunHistory } from '../run-history.js';
 
 const MIME_TYPES = {
@@ -282,6 +284,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       return;
     }
 
+    if (pathname === '/api/coordinator/timeouts') {
+      const result = readCoordinatorTimeoutStatus(workspacePath);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     if (pathname === '/api/workflow-kit-artifacts') {
       const result = readWorkflowKitArtifacts(workspacePath);
       writeJson(res, result.status, result.body);
@@ -294,6 +302,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       return;
     }
 
+    if (pathname === '/api/timeouts') {
+      const result = readTimeoutStatus(workspacePath);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     if (pathname === '/api/run-history') {
       const url = new URL(req.url, `http://${req.headers.host}`);
       const limit = url.searchParams.get('limit') ? parseInt(url.searchParams.get('limit'), 10) : undefined;

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

@@ -0,0 +1,139 @@
+import { join } from 'path';
+import { loadProjectContext, loadProjectState } from '../config.js';
+import { loadCoordinatorConfig } from '../coordinator-config.js';
+import { loadCoordinatorState } from '../coordinator-state.js';
+import { readJsonlFile } from './state-reader.js';
+import { buildTimeoutConfigSummary, evaluateDashboardTimeoutPressure, extractTimeoutEvents } from './timeout-status.js';
+
+function getCoordinatorConfigErrorResponse(errors) {
+  const issueList = Array.isArray(errors) ? errors : [];
+  const missing = issueList.some((error) => typeof error === 'string' && error.startsWith('config_missing:'));
+
+  return {
+    ok: false,
+    status: missing ? 404 : 422,
+    body: {
+      ok: false,
+      code: missing ? 'coordinator_config_missing' : 'coordinator_config_invalid',
+      error: missing
+        ? 'Coordinator config not found. Run `agentxchain multi init` first.'
+        : 'Coordinator config is invalid.',
+      errors: issueList,
+    },
+  };
+}
+
+function emptyLiveTimeouts() {
+  return { exceeded: [], warnings: [] };
+}
+
+function readRepoTimeoutSnapshot(repoId, repo, repoRun) {
+  const context = loadProjectContext(repo.resolved_path);
+  if (!context) {
+    return {
+      repo_id: repoId,
+      path: repo.path,
+      run_id: repoRun?.run_id ?? null,
+      status: repoRun?.status ?? null,
+      phase: repoRun?.phase ?? null,
+      configured: false,
+      config: null,
+      live: null,
+      events: [],
+      error: {
+        code: 'repo_config_missing',
+        error: `Repo "${repoId}" config could not be loaded.`,
+      },
+    };
+  }
+
+  const state = loadProjectState(context.root, context.config);
+  const agentxchainDir = join(context.root, '.agentxchain');
+  const events = extractTimeoutEvents(readJsonlFile(agentxchainDir, 'decision-ledger.jsonl'));
+  const configured = Boolean(context.config.timeouts);
+
+  if (!state) {
+    return {
+      repo_id: repoId,
+      path: repo.path,
+      run_id: repoRun?.run_id ?? null,
+      status: repoRun?.status ?? null,
+      phase: repoRun?.phase ?? null,
+      configured,
+      config: buildTimeoutConfigSummary(context.config.timeouts, context.config.routing),
+      live: configured ? emptyLiveTimeouts() : null,
+      events,
+      error: {
+        code: 'repo_state_missing',
+        error: `Repo "${repoId}" governed state is missing.`,
+      },
+    };
+  }
+
+  const live = configured
+    ? evaluateDashboardTimeoutPressure(context.config, state, new Date())
+    : null;
+
+  return {
+    repo_id: repoId,
+    path: repo.path,
+    run_id: state.run_id ?? repoRun?.run_id ?? null,
+    status: state.status ?? repoRun?.status ?? null,
+    phase: state.phase ?? repoRun?.phase ?? null,
+    configured,
+    config: buildTimeoutConfigSummary(context.config.timeouts, context.config.routing),
+    live,
+    events,
+    error: null,
+  };
+}
+
+export function readCoordinatorTimeoutStatus(workspacePath) {
+  const configResult = loadCoordinatorConfig(workspacePath);
+  if (!configResult.ok) {
+    return getCoordinatorConfigErrorResponse(configResult.errors);
+  }
+
+  const coordinatorState = loadCoordinatorState(workspacePath);
+  if (!coordinatorState) {
+    return {
+      ok: false,
+      status: 404,
+      body: {
+        ok: false,
+        code: 'coordinator_state_missing',
+        error: 'Coordinator state not found. Run `agentxchain multi init` first.',
+      },
+    };
+  }
+
+  const coordinatorDir = join(workspacePath, '.agentxchain', 'multirepo');
+  const coordinatorEvents = extractTimeoutEvents(readJsonlFile(coordinatorDir, 'decision-ledger.jsonl'));
+  const repos = configResult.config.repo_order.map((repoId) => (
+    readRepoTimeoutSnapshot(repoId, configResult.config.repos[repoId], coordinatorState.repo_runs?.[repoId] ?? null)
+  ));
+
+  const summary = {
+    repo_count: repos.length,
+    configured_repo_count: repos.filter((repo) => repo.configured).length,
+    repos_with_live_exceeded: repos.filter((repo) => (repo.live?.exceeded?.length || 0) > 0).length,
+    repos_with_live_warnings: repos.filter((repo) => (repo.live?.warnings?.length || 0) > 0).length,
+    repo_event_count: repos.reduce((sum, repo) => sum + repo.events.length, 0),
+    coordinator_event_count: coordinatorEvents.length,
+  };
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      ok: true,
+      super_run_id: coordinatorState.super_run_id ?? null,
+      status: coordinatorState.status ?? null,
+      phase: coordinatorState.phase ?? null,
+      blocked_reason: coordinatorState.blocked_reason ?? null,
+      summary,
+      coordinator_events: coordinatorEvents,
+      repos,
+    },
+  };
+}

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

@@ -0,0 +1,201 @@
+/**
+ * Timeout status — computed dashboard endpoint.
+ *
+ * Reads agentxchain.json config, .agentxchain/state.json, and the decision
+ * ledger to derive live timeout pressure and persisted timeout events.
+ *
+ * See: TIMEOUT_DASHBOARD_SURFACE_SPEC.md
+ */
+
+import { join } from 'path';
+import { loadProjectContext, loadProjectState } from '../config.js';
+import { evaluateTimeouts } from '../timeout-evaluator.js';
+import { readJsonlFile } from './state-reader.js';
+
+/**
+ * Extract timeout events from raw decision-ledger entries.
+ * Mirrors the shape of report.js extractTimeoutEventDigest but operates
+ * on in-memory ledger array rather than export artifacts.
+ */
+export function extractTimeoutEvents(ledgerEntries) {
+  if (!Array.isArray(ledgerEntries) || ledgerEntries.length === 0) return [];
+  return ledgerEntries
+    .filter((d) => typeof d?.type === 'string' && d.type.startsWith('timeout'))
+    .map((d) => ({
+      type: d.type,
+      scope: d.scope || null,
+      phase: d.phase || null,
+      turn_id: d.turn_id || null,
+      limit_minutes: typeof d.limit_minutes === 'number' ? d.limit_minutes : null,
+      elapsed_minutes: typeof d.elapsed_minutes === 'number' ? d.elapsed_minutes : null,
+      exceeded_by_minutes: typeof d.exceeded_by_minutes === 'number' ? d.exceeded_by_minutes : null,
+      action: d.action || null,
+      timestamp: d.timestamp || null,
+    }));
+}
+
+/**
+ * Flatten per-phase routing timeout overrides into a display-friendly array.
+ */
+export function flattenPhaseOverrides(routing) {
+  if (!routing) return [];
+  const overrides = [];
+  for (const [phase, route] of Object.entries(routing)) {
+    if (route.timeout_minutes || route.timeout_action) {
+      overrides.push({
+        phase,
+        limit_minutes: typeof route.timeout_minutes === 'number' ? route.timeout_minutes : null,
+        action: route.timeout_action || null,
+      });
+    }
+  }
+  return overrides;
+}
+
+/**
+ * Read timeout status for the dashboard.
+ *
+ * @param {string} workspacePath — project root (parent of .agentxchain/)
+ * @returns {{ ok: boolean, status: number, body: object }}
+ */
+export function buildTimeoutConfigSummary(timeouts, routing) {
+  if (!timeouts) return null;
+  return {
+    per_turn_minutes: timeouts.per_turn_minutes || null,
+    per_phase_minutes: timeouts.per_phase_minutes || null,
+    per_run_minutes: timeouts.per_run_minutes || null,
+    action: timeouts.action || 'escalate',
+    phase_overrides: flattenPhaseOverrides(routing),
+  };
+}
+
+function emptyLiveTimeouts() {
+  return { exceeded: [], warnings: [] };
+}
+
+function getActiveTurns(state) {
+  if (!state?.active_turns || typeof state.active_turns !== 'object' || Array.isArray(state.active_turns)) {
+    return [];
+  }
+  return Object.values(state.active_turns).filter((turn) => turn && typeof turn === 'object');
+}
+
+function annotateTurnTimeout(result, state, turn) {
+  return {
+    ...result,
+    phase: result.phase || state?.phase || null,
+    turn_id: turn?.turn_id || null,
+    role_id: turn?.assigned_role || null,
+  };
+}
+
+export function evaluateDashboardTimeoutPressure(config, state, now = new Date()) {
+  if (!config?.timeouts || state?.status !== 'active') {
+    return emptyLiveTimeouts();
+  }
+
+  const base = evaluateTimeouts({ config, state, now });
+  const live = {
+    exceeded: [...base.exceeded],
+    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));
+      }
+    }
+    for (const item of turnEval.warnings) {
+      if (item.scope === 'turn') {
+        live.warnings.push(annotateTurnTimeout(item, state, turn));
+      }
+    }
+  }
+
+  return live;
+}
+
+function loadDashboardTimeoutContext(workspacePath) {
+  const context = loadProjectContext(workspacePath);
+  if (!context || context.config?.protocol_mode !== 'governed') {
+    return {
+      ok: false,
+      status: 404,
+      body: {
+        ok: false,
+        code: 'config_missing',
+        error: 'Project config not found. Run `agentxchain init --governed` first.',
+      },
+    };
+  }
+
+  const { root, config } = context;
+  const state = loadProjectState(root, config);
+  const agentxchainDir = join(root, '.agentxchain');
+  if (!state) {
+    return {
+      ok: false,
+      status: 404,
+      body: {
+        ok: false,
+        code: 'state_missing',
+        error: 'Run state not found. Run `agentxchain init --governed` first.',
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    root,
+    config,
+    state,
+    agentxchainDir,
+  };
+}
+
+export function readTimeoutStatus(workspacePath) {
+  const contextResult = loadDashboardTimeoutContext(workspacePath);
+  if (!contextResult.ok) {
+    return contextResult;
+  }
+
+  const { config, state, agentxchainDir } = contextResult;
+  const timeouts = config.timeouts;
+  if (!timeouts) {
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        ok: true,
+        configured: false,
+        config: null,
+        live: null,
+        events: [],
+      },
+    };
+  }
+
+  // Config summary
+  const configSummary = buildTimeoutConfigSummary(timeouts, config.routing);
+
+  // Live timeout evaluation — only meaningful when the run is active
+  const live = evaluateDashboardTimeoutPressure(config, state, new Date());
+
+  // Persisted timeout events from the decision ledger
+  const ledger = readJsonlFile(agentxchainDir, 'decision-ledger.jsonl');
+  const events = extractTimeoutEvents(ledger);
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      ok: true,
+      configured: true,
+      config: configSummary,
+      live,
+      events,
+    },
+  };
+}