agentxchain 2.47.0 → 2.49.0

package/src/commands/schedule.js

@@ -0,0 +1,265 @@
+import chalk from 'chalk';
+import { loadProjectContext } from '../lib/config.js';
+import {
+  SCHEDULE_STATE_PATH,
+  listSchedules,
+  updateScheduleState,
+  evaluateScheduleLaunchEligibility,
+} from '../lib/run-schedule.js';
+import { executeGovernedRun } from './run.js';
+
+function loadScheduleContext() {
+  const context = loadProjectContext();
+  if (!context) {
+    console.error(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exitCode = 1;
+    return null;
+  }
+  if (context.config.protocol_mode !== 'governed') {
+    console.error(chalk.red('The schedule command is only available for governed projects.'));
+    process.exitCode = 1;
+    return null;
+  }
+  return context;
+}
+
+function resolveScheduleEntries(context, scheduleId, at) {
+  const entries = listSchedules(context.root, context.config, { at });
+  if (!scheduleId) {
+    return { ok: true, entries };
+  }
+
+  const matched = entries.find((entry) => entry.id === scheduleId);
+  if (!matched) {
+    return { ok: false, error: `Unknown schedule: ${scheduleId}` };
+  }
+
+  return { ok: true, entries: [matched] };
+}
+
+function printScheduleTable(entries) {
+  if (entries.length === 0) {
+    console.log(chalk.dim('No schedules configured.'));
+    return;
+  }
+
+  const header = [
+    pad('Schedule', 24),
+    pad('Enabled', 8),
+    pad('Every', 8),
+    pad('Due', 6),
+    pad('Next Due', 24),
+    pad('Last Status', 18),
+    pad('Last Run', 14),
+  ].join(' ');
+  console.log(chalk.bold(header));
+  console.log(chalk.dim('─'.repeat(header.length)));
+
+  for (const entry of entries) {
+    console.log([
+      pad(entry.id, 24),
+      pad(entry.enabled ? 'yes' : 'no', 8),
+      pad(`${entry.every_minutes}m`, 8),
+      pad(entry.due ? 'yes' : 'no', 6),
+      pad(entry.next_due_at || '—', 24),
+      pad(entry.last_status || entry.last_skip_reason || '—', 18),
+      pad((entry.last_run_id || '—').slice(0, 12), 14),
+    ].join(' '));
+  }
+}
+
+function pad(value, width) {
+  return String(value || '').padEnd(width);
+}
+
+function buildScheduleProvenance(entry) {
+  return {
+    trigger: 'schedule',
+    created_by: 'operator',
+    trigger_reason: entry.trigger_reason || `schedule:${entry.id}`,
+  };
+}
+
+async function runDueSchedules(context, opts = {}) {
+  const resolved = resolveScheduleEntries(context, opts.schedule, opts.at);
+  if (!resolved.ok) {
+    return { ok: false, exitCode: 1, error: resolved.error, results: [] };
+  }
+
+  const nowIso = opts.at || new Date().toISOString();
+  const results = [];
+
+  for (const entry of resolved.entries) {
+    if (!entry.enabled) {
+      results.push({ id: entry.id, action: 'disabled' });
+      continue;
+    }
+    if (!entry.due) {
+      results.push({ id: entry.id, action: 'not_due', next_due_at: entry.next_due_at });
+      continue;
+    }
+
+    const eligibility = evaluateScheduleLaunchEligibility(context.root, context.config);
+    if (!eligibility.ok) {
+      updateScheduleState(context.root, context.config, entry.id, (record) => ({
+        ...record,
+        last_skip_at: nowIso,
+        last_skip_reason: eligibility.reason,
+      }));
+      results.push({
+        id: entry.id,
+        action: 'skipped',
+        reason: eligibility.reason,
+        project_status: eligibility.status,
+      });
+      continue;
+    }
+
+    if (!opts.json) {
+      console.log(chalk.cyan(`Schedule due: ${entry.id}`));
+    }
+    const execution = await executeGovernedRun(context, {
+      provenance: buildScheduleProvenance(entry),
+      maxTurns: entry.max_turns,
+      autoApprove: entry.auto_approve,
+      role: entry.initial_role || undefined,
+      report: true,
+      allowBlockedRestart: false,
+      requireFreshStart: true,
+      allowedFreshStatuses: ['idle', 'completed'],
+      log: opts.json ? () => {} : console.log,
+    });
+
+    if (execution.skipped) {
+      updateScheduleState(context.root, context.config, entry.id, (record) => ({
+        ...record,
+        last_skip_at: nowIso,
+        last_skip_reason: execution.skipReason,
+      }));
+      results.push({
+        id: entry.id,
+        action: 'skipped',
+        reason: execution.skipReason,
+      });
+      continue;
+    }
+
+    const runId = execution.result?.state?.run_id || null;
+    const startedAt = execution.result?.state?.created_at || nowIso;
+    updateScheduleState(context.root, context.config, entry.id, (record) => ({
+      ...record,
+      last_started_at: startedAt,
+      last_finished_at: new Date().toISOString(),
+      last_run_id: runId,
+      last_status: execution.result?.stop_reason || (execution.exitCode === 0 ? 'completed' : 'launch_failed'),
+      last_skip_at: null,
+      last_skip_reason: null,
+    }));
+    results.push({
+      id: entry.id,
+      action: 'ran',
+      run_id: runId,
+      stop_reason: execution.result?.stop_reason || null,
+      exit_code: execution.exitCode,
+    });
+
+    if (execution.exitCode !== 0) {
+      return { ok: false, exitCode: execution.exitCode, results };
+    }
+  }
+
+  return { ok: true, exitCode: 0, results };
+}
+
+export async function scheduleListCommand(opts) {
+  const context = loadScheduleContext();
+  if (!context) return;
+
+  const resolved = resolveScheduleEntries(context, opts.schedule, opts.at);
+  if (!resolved.ok) {
+    console.error(chalk.red(resolved.error));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      schedules: resolved.entries,
+      state_file: SCHEDULE_STATE_PATH,
+    }, null, 2));
+    return;
+  }
+
+  printScheduleTable(resolved.entries);
+}
+
+export async function scheduleRunDueCommand(opts) {
+  const context = loadScheduleContext();
+  if (!context) return;
+
+  const result = await runDueSchedules(context, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!result.ok) {
+    console.error(chalk.red(result.error || 'Scheduled run failed'));
+  } else if (result.results.length === 0) {
+    console.log(chalk.dim('No schedules configured.'));
+  } else {
+    for (const entry of result.results) {
+      if (entry.action === 'ran') {
+        console.log(chalk.green(`Schedule ran: ${entry.id} (${entry.run_id || 'no run id'})`));
+      } else if (entry.action === 'skipped') {
+        console.log(chalk.yellow(`Schedule skipped: ${entry.id} (${entry.reason})`));
+      } else if (entry.action === 'not_due') {
+        console.log(chalk.dim(`Schedule not due: ${entry.id}`));
+      } else if (entry.action === 'disabled') {
+        console.log(chalk.dim(`Schedule disabled: ${entry.id}`));
+      }
+    }
+  }
+
+  process.exitCode = result.exitCode;
+}
+
+export async function scheduleDaemonCommand(opts) {
+  const context = loadScheduleContext();
+  if (!context) return;
+
+  const pollSeconds = Number.parseInt(opts.pollSeconds ?? '60', 10);
+  const maxCycles = opts.maxCycles != null ? Number.parseInt(opts.maxCycles, 10) : null;
+  if (!Number.isInteger(pollSeconds) || pollSeconds < 1) {
+    console.error(chalk.red('--poll-seconds must be an integer >= 1'));
+    process.exitCode = 1;
+    return;
+  }
+  if (maxCycles !== null && (!Number.isInteger(maxCycles) || maxCycles < 1)) {
+    console.error(chalk.red('--max-cycles must be an integer >= 1'));
+    process.exitCode = 1;
+    return;
+  }
+
+  let cycle = 0;
+  if (!opts.json) {
+    console.log(chalk.bold('AgentXchain Schedule Daemon'));
+    console.log(chalk.dim(`  Poll: ${pollSeconds}s`));
+    console.log(chalk.dim(`  State: ${SCHEDULE_STATE_PATH}`));
+    console.log('');
+  }
+
+  while (true) {
+    cycle += 1;
+    const result = await runDueSchedules(context, opts);
+    if (opts.json) {
+      console.log(JSON.stringify({ cycle, ...result }));
+    }
+    if (!result.ok) {
+      process.exitCode = result.exitCode;
+      return;
+    }
+    if (maxCycles !== null && cycle >= maxCycles) {
+      process.exitCode = 0;
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollSeconds * 1000));
+  }
+}

package/src/lib/export.js

@@ -31,6 +31,8 @@ export const RUN_EXPORT_INCLUDED_ROOTS = [
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/notification-audit.jsonl',
   '.agentxchain/run-history.jsonl',
+  '.agentxchain/events.jsonl',
+  '.agentxchain/schedule-state.json',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',
@@ -53,6 +55,8 @@ export const RUN_RESTORE_ROOTS = [
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/notification-audit.jsonl',
   '.agentxchain/run-history.jsonl',
+  '.agentxchain/events.jsonl',
+  '.agentxchain/schedule-state.json',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',

package/src/lib/governed-state.js

@@ -40,6 +40,7 @@ import { getMaxConcurrentTurns } from './normalized-config.js';
 import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir, getReviewArtifactPath } from './turn-paths.js';
 import { runHooks } from './hook-runner.js';
 import { emitNotifications } from './notification-runner.js';
+import { emitRunEvent } from './run-events.js';
 import { writeSessionCheckpoint } from './session-checkpoint.js';
 import { recordRunHistory } from './run-history.js';
 import { buildDefaultRunProvenance } from './run-provenance.js';
@@ -1751,6 +1752,12 @@ export function raiseOperatorEscalation(root, config, details) {
     detail,
     recovery_action: recoveryAction,
   }, targetTurn);
+  emitRunEvent(root, 'escalation_raised', {
+    run_id: blocked.state.run_id,
+    phase: blocked.state.phase,
+    status: 'blocked',
+    payload: { source: 'operator', reason },
+  });
 
   return {
     ok: true,
@@ -1794,6 +1801,12 @@ export function reactivateGovernedRun(root, state, details = {}) {
       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));
+    emitRunEvent(details.root || root, 'escalation_resolved', {
+      run_id: nextState.run_id,
+      phase: nextState.phase,
+      status: nextState.status,
+      payload: { resolved_via: details.via || 'unknown' },
+    });
   }
 
   return { ok: true, state: attachLegacyCurrentTurnAlias(nextState) };
@@ -1846,6 +1859,12 @@ export function initializeGovernedRun(root, config, options = {}) {
   };
 
   writeState(root, updatedState);
+  emitRunEvent(root, 'run_started', {
+    run_id: runId,
+    phase: updatedState.phase,
+    status: 'active',
+    payload: { provenance: provenance || {} },
+  });
   return { ok: true, state: attachLegacyCurrentTurnAlias(updatedState) };
 }
 
@@ -2051,6 +2070,13 @@ export function assignGovernedTurn(root, config, roleId) {
 
   writeState(root, updatedState);
 
+  emitRunEvent(root, 'turn_dispatched', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: updatedState.status,
+    turn: { turn_id: turnId, role_id: roleId },
+  });
+
   // Session checkpoint — non-fatal, written after every successful turn assignment
   writeSessionCheckpoint(root, updatedState, 'turn_assigned', {
     role: roleId,
@@ -3027,6 +3053,14 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     }
   }
 
+  // Emit turn_accepted event to local log.
+  emitRunEvent(root, 'turn_accepted', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: updatedState.status,
+    turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+  });
+
   if (updatedState.status === 'blocked') {
     // DEC-RHTR-SPEC: Record blocked outcome in cross-run history (non-fatal)
     // Covers needs_human, budget:exhausted, and any other non-hook blocked states
@@ -3037,6 +3071,13 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       blockedOn: updatedState.blocked_on,
       recovery: updatedState.blocked_reason?.recovery || null,
     }, currentTurn);
+    emitRunEvent(root, 'run_blocked', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: 'blocked',
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      payload: { category: updatedState.blocked_reason?.category || 'needs_human' },
+    });
   }
 
   if (updatedState.pending_phase_transition) {
@@ -3046,6 +3087,16 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       gate: updatedState.pending_phase_transition.gate,
       requested_by_turn: updatedState.pending_phase_transition.requested_by_turn,
     }, currentTurn);
+    emitRunEvent(root, 'gate_pending', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      payload: {
+        gate_type: 'phase_transition',
+        from: updatedState.pending_phase_transition.from,
+        to: updatedState.pending_phase_transition.to,
+      },
+    });
   }
 
   if (updatedState.pending_run_completion) {
@@ -3054,6 +3105,12 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       requested_by_turn: updatedState.pending_run_completion.requested_by_turn,
       requested_at: updatedState.pending_run_completion.requested_at,
     }, currentTurn);
+    emitRunEvent(root, 'gate_pending', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      payload: { gate_type: 'run_completion' },
+    });
   }
 
   if (updatedState.status === 'completed') {
@@ -3062,6 +3119,12 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       completed_via: completionResult?.action === 'complete' ? 'accept_turn' : 'accept_turn_direct',
       requested_by_turn: completionResult?.requested_by_turn || turnResult.turn_id,
     }, currentTurn);
+    emitRunEvent(root, 'run_completed', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: 'completed',
+      payload: { completed_at: updatedState.completed_at || now },
+    });
   }
 
   // Session checkpoint — non-fatal, written after every successful acceptance
@@ -3211,6 +3274,13 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
     };
 
     writeState(root, updatedState);
+    emitRunEvent(root, 'turn_rejected', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      payload: { attempt: currentAttempt, retrying: true },
+    });
     return {
       ok: true,
       state: attachLegacyCurrentTurnAlias(updatedState),
@@ -3271,6 +3341,19 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
     blockedOn: updatedState.blocked_on,
     recovery: updatedState.blocked_reason?.recovery || null,
   }, updatedState.active_turns[currentTurn.turn_id]);
+  emitRunEvent(root, 'turn_rejected', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'blocked',
+    turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+    payload: { attempt: currentAttempt, retrying: false, escalated: true },
+  });
+  emitRunEvent(root, 'run_blocked', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'blocked',
+    payload: { category: 'retries_exhausted' },
+  });
 
   // Fire on_escalation hooks (advisory-only) after blocked state is persisted.
   const hooksConfig = config?.hooks || {};
@@ -3382,6 +3465,18 @@ export function approvePhaseTransition(root, config) {
   };
 
   writeState(root, updatedState);
+  emitRunEvent(root, 'gate_approved', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'active',
+    payload: { gate_type: 'phase_transition', from: transition.from, to: transition.to },
+  });
+  emitRunEvent(root, 'phase_entered', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'active',
+    payload: { from: transition.from },
+  });
 
   // Session checkpoint — non-fatal
   writeSessionCheckpoint(root, updatedState, 'phase_approved');
@@ -3484,6 +3579,18 @@ export function approveRunCompletion(root, config) {
     gate: completion.gate,
     requested_by_turn: completion.requested_by_turn || null,
   }, completion.requested_by_turn ? getActiveTurns(state)[completion.requested_by_turn] || null : null);
+  emitRunEvent(root, 'gate_approved', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'completed',
+    payload: { gate_type: 'run_completion' },
+  });
+  emitRunEvent(root, 'run_completed', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'completed',
+    payload: { completed_at: updatedState.completed_at },
+  });
 
   // Session checkpoint — non-fatal
   writeSessionCheckpoint(root, updatedState, 'run_completed');

package/src/lib/normalized-config.js

@@ -34,6 +34,7 @@ const DEFAULT_PHASES = ['planning', 'implementation', 'qa'];
 export { DEFAULT_PHASES };
 const VALID_PHASE_NAME = /^[a-z][a-z0-9_-]*$/;
 const VALID_SEMANTIC_IDS = ['pm_signoff', 'system_spec', 'implementation_notes', 'acceptance_matrix', 'ship_verdict', 'release_notes', 'section_check'];
+const VALID_SCHEDULE_ID = /^[a-z0-9_-]+$/;
 
 const VALID_API_PROXY_RETRY_JITTER = ['none', 'full'];
 const VALID_API_PROXY_RETRY_CLASSES = [
@@ -508,6 +509,12 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...notificationValidation.errors);
   }
 
+  // Schedules (optional but validated if present)
+  if (data.schedules !== undefined) {
+    const scheduleValidation = validateSchedulesConfig(data.schedules, data.roles);
+    errors.push(...scheduleValidation.errors);
+  }
+
   // Workflow Kit (optional but validated if present)
   if (data.workflow_kit !== undefined) {
     const wkValidation = validateWorkflowKitConfig(data.workflow_kit, data.routing, data.roles);
@@ -534,6 +541,57 @@ export function validateV4Config(data, projectRoot) {
   return { ok: errors.length === 0, errors };
 }
 
+export function validateSchedulesConfig(schedules, roles) {
+  const errors = [];
+
+  if (!schedules || typeof schedules !== 'object' || Array.isArray(schedules)) {
+    errors.push('schedules must be an object');
+    return { ok: false, errors };
+  }
+
+  for (const [scheduleId, schedule] of Object.entries(schedules)) {
+    if (!VALID_SCHEDULE_ID.test(scheduleId)) {
+      errors.push(`Schedule "${scheduleId}" must use lowercase alphanumeric, underscore, or hyphen characters only`);
+      continue;
+    }
+
+    if (!schedule || typeof schedule !== 'object' || Array.isArray(schedule)) {
+      errors.push(`Schedule "${scheduleId}" must be an object`);
+      continue;
+    }
+
+    if (!Number.isInteger(schedule.every_minutes) || schedule.every_minutes < 1) {
+      errors.push(`Schedule "${scheduleId}": every_minutes must be an integer >= 1`);
+    }
+
+    if ('enabled' in schedule && typeof schedule.enabled !== 'boolean') {
+      errors.push(`Schedule "${scheduleId}": enabled must be a boolean`);
+    }
+
+    if ('auto_approve' in schedule && typeof schedule.auto_approve !== 'boolean') {
+      errors.push(`Schedule "${scheduleId}": auto_approve must be a boolean`);
+    }
+
+    if ('max_turns' in schedule && (!Number.isInteger(schedule.max_turns) || schedule.max_turns < 1)) {
+      errors.push(`Schedule "${scheduleId}": max_turns must be an integer >= 1`);
+    }
+
+    if ('trigger_reason' in schedule && (typeof schedule.trigger_reason !== 'string' || !schedule.trigger_reason.trim())) {
+      errors.push(`Schedule "${scheduleId}": trigger_reason must be a non-empty string when provided`);
+    }
+
+    if ('initial_role' in schedule) {
+      if (typeof schedule.initial_role !== 'string' || !schedule.initial_role.trim()) {
+        errors.push(`Schedule "${scheduleId}": initial_role must be a non-empty string when provided`);
+      } else if (roles && !roles[schedule.initial_role]) {
+        errors.push(`Schedule "${scheduleId}": initial_role "${schedule.initial_role}" is not a defined role`);
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
 /**
  * Validate the workflow_kit config section.
  * Returns { ok, errors, warnings }.
@@ -850,6 +908,7 @@ export function normalizeV3(raw) {
     gates: {},
     hooks: {},
     notifications: {},
+    schedules: {},
     budget: null,
     policies: [],
     approval_policy: null,
@@ -917,6 +976,7 @@ export function normalizeV4(raw) {
     gates: raw.gates || {},
     hooks: raw.hooks || {},
     notifications: raw.notifications || {},
+    schedules: normalizeSchedules(raw.schedules),
     budget: raw.budget || null,
     policies: normalizePolicies(raw.policies),
     approval_policy: raw.approval_policy || null,
@@ -949,6 +1009,26 @@ export function normalizeV4(raw) {
   };
 }
 
+function normalizeSchedules(rawSchedules) {
+  if (!rawSchedules || typeof rawSchedules !== 'object' || Array.isArray(rawSchedules)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(rawSchedules).map(([scheduleId, schedule]) => [
+      scheduleId,
+      {
+        enabled: schedule?.enabled !== false,
+        every_minutes: schedule?.every_minutes,
+        auto_approve: schedule?.auto_approve !== false,
+        max_turns: schedule?.max_turns ?? 50,
+        initial_role: schedule?.initial_role || null,
+        trigger_reason: schedule?.trigger_reason?.trim() || `schedule:${scheduleId}`,
+      },
+    ]),
+  );
+}
+
 /**
  * Load and normalize a config from raw JSON.
  * Returns { ok, normalized, errors, version }.

package/src/lib/repo-observer.js

@@ -41,6 +41,9 @@ const ORCHESTRATOR_STATE_FILES = [
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/run-history.jsonl',
+  '.agentxchain/events.jsonl',
+  '.agentxchain/notification-audit.jsonl',
+  '.agentxchain/schedule-state.json',
   'TALK.md',
 ];