agentxchain 2.47.0 → 2.49.0

package/src/lib/run-events.js

@@ -0,0 +1,117 @@
+/**
+ * run-events.js — Repo-local structured event log for governed runs.
+ *
+ * Appends lifecycle events to `.agentxchain/events.jsonl` so operators
+ * can observe run progress without webhooks or dashboard.
+ */
+
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export const RUN_EVENTS_PATH = '.agentxchain/events.jsonl';
+
+export const VALID_RUN_EVENTS = [
+  'run_started',
+  'phase_entered',
+  'turn_dispatched',
+  'turn_accepted',
+  'turn_rejected',
+  'run_blocked',
+  'run_completed',
+  'escalation_raised',
+  'escalation_resolved',
+  'gate_pending',
+  'gate_approved',
+];
+
+/**
+ * Emit a structured lifecycle event to the local event log.
+ *
+ * @param {string} root        - Project root directory
+ * @param {string} eventType   - One of VALID_RUN_EVENTS
+ * @param {object} details     - Event details
+ * @param {string} [details.run_id]  - Current run ID
+ * @param {string} [details.phase]   - Current phase
+ * @param {string} [details.status]  - Current run status
+ * @param {object} [details.turn]    - Turn context (turn_id, role_id, etc.)
+ * @param {object} [details.payload] - Additional event-specific data
+ * @returns {{ ok: boolean, event_id: string }}
+ */
+export function emitRunEvent(root, eventType, details = {}) {
+  const event_id = `evt_${randomBytes(8).toString('hex')}`;
+  const entry = {
+    event_id,
+    event_type: eventType,
+    timestamp: new Date().toISOString(),
+    run_id: details.run_id || null,
+    phase: details.phase || null,
+    status: details.status || null,
+    turn: details.turn || null,
+    payload: details.payload || {},
+  };
+
+  try {
+    const filePath = join(root, RUN_EVENTS_PATH);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    appendFileSync(filePath, `${JSON.stringify(entry)}\n`);
+    return { ok: true, event_id };
+  } catch (err) {
+    // Best-effort — never interrupt governed operations for event logging.
+    if (process.env.AGENTXCHAIN_DEBUG) {
+      process.stderr.write(`[run-events] write failed: ${err.message}\n`);
+    }
+    return { ok: false, event_id };
+  }
+}
+
+/**
+ * Read events from the local event log.
+ *
+ * @param {string} root      - Project root directory
+ * @param {object} [opts]    - Filter options
+ * @param {string} [opts.type]   - Comma-separated event types to include
+ * @param {string} [opts.since]  - ISO-8601 timestamp; only events after this
+ * @param {number} [opts.limit]  - Max events to return (from end of file)
+ * @returns {object[]}
+ */
+export function readRunEvents(root, opts = {}) {
+  const filePath = join(root, RUN_EVENTS_PATH);
+  if (!existsSync(filePath)) return [];
+
+  const raw = readFileSync(filePath, 'utf8');
+  const lines = raw.split('\n').filter(Boolean);
+
+  let events = [];
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      // Skip malformed lines.
+    }
+  }
+
+  // Apply type filter.
+  if (opts.type) {
+    const types = new Set(opts.type.split(',').map(t => t.trim()));
+    events = events.filter(e => types.has(e.event_type));
+  }
+
+  // Apply since filter.
+  if (opts.since) {
+    const sinceMs = new Date(opts.since).getTime();
+    if (!Number.isNaN(sinceMs)) {
+      events = events.filter(e => new Date(e.timestamp).getTime() > sinceMs);
+    }
+  }
+
+  // Apply limit (from end).
+  if (opts.limit && opts.limit > 0 && events.length > opts.limit) {
+    events = events.slice(-opts.limit);
+  }
+
+  return events;
+}

package/src/lib/run-schedule.js

@@ -0,0 +1,160 @@
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { safeWriteJson } from './safe-write.js';
+import { loadProjectState } from './config.js';
+
+export const SCHEDULE_STATE_PATH = '.agentxchain/schedule-state.json';
+const SCHEDULE_STATE_SCHEMA_VERSION = '0.1';
+
+function parseIsoTime(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const ts = Date.parse(value);
+  return Number.isFinite(ts) ? ts : null;
+}
+
+function toIso(value) {
+  return new Date(value).toISOString();
+}
+
+function normalizeScheduleStateRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {
+      last_started_at: null,
+      last_finished_at: null,
+      last_run_id: null,
+      last_status: null,
+      last_skip_at: null,
+      last_skip_reason: null,
+    };
+  }
+
+  return {
+    last_started_at: typeof value.last_started_at === 'string' ? value.last_started_at : null,
+    last_finished_at: typeof value.last_finished_at === 'string' ? value.last_finished_at : null,
+    last_run_id: typeof value.last_run_id === 'string' ? value.last_run_id : null,
+    last_status: typeof value.last_status === 'string' ? value.last_status : null,
+    last_skip_at: typeof value.last_skip_at === 'string' ? value.last_skip_at : null,
+    last_skip_reason: typeof value.last_skip_reason === 'string' ? value.last_skip_reason : null,
+  };
+}
+
+function normalizeScheduleState(value, config) {
+  const schedules = {};
+  const configuredIds = Object.keys(config?.schedules || {});
+  for (const scheduleId of configuredIds) {
+    schedules[scheduleId] = normalizeScheduleStateRecord(value?.schedules?.[scheduleId]);
+  }
+
+  return {
+    schema_version: SCHEDULE_STATE_SCHEMA_VERSION,
+    schedules,
+  };
+}
+
+export function readScheduleState(root, config) {
+  const absPath = join(root, SCHEDULE_STATE_PATH);
+  if (!existsSync(absPath)) {
+    return normalizeScheduleState(null, config);
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(absPath, 'utf8'));
+    return normalizeScheduleState(parsed, config);
+  } catch {
+    return normalizeScheduleState(null, config);
+  }
+}
+
+export function writeScheduleState(root, state) {
+  const absPath = join(root, SCHEDULE_STATE_PATH);
+  mkdirSync(dirname(absPath), { recursive: true });
+  safeWriteJson(absPath, state);
+}
+
+export function updateScheduleState(root, config, scheduleId, updater) {
+  const state = readScheduleState(root, config);
+  const current = normalizeScheduleStateRecord(state.schedules[scheduleId]);
+  state.schedules[scheduleId] = normalizeScheduleStateRecord(updater(current));
+  writeScheduleState(root, state);
+  return state.schedules[scheduleId];
+}
+
+export function computeScheduleStatus(schedule, record, now = Date.now()) {
+  if (schedule.enabled === false) {
+    return {
+      due: false,
+      next_due_at: null,
+      due_reason: 'disabled',
+    };
+  }
+
+  const lastStartedAt = parseIsoTime(record.last_started_at);
+  if (lastStartedAt === null) {
+    return {
+      due: true,
+      next_due_at: toIso(now),
+      due_reason: 'never_started',
+    };
+  }
+
+  const nextDueTs = lastStartedAt + (schedule.every_minutes * 60 * 1000);
+  return {
+    due: now >= nextDueTs,
+    next_due_at: toIso(nextDueTs),
+    due_reason: now >= nextDueTs ? 'interval_elapsed' : 'waiting_interval',
+  };
+}
+
+export function listSchedules(root, config, { at } = {}) {
+  const now = at ? Date.parse(at) : Date.now();
+  const scheduleState = readScheduleState(root, config);
+  const projectState = loadProjectState(root, config);
+  const projectStatus = projectState?.status || 'missing';
+
+  return Object.entries(config?.schedules || {}).map(([scheduleId, schedule]) => {
+    const record = scheduleState.schedules[scheduleId] || normalizeScheduleStateRecord(null);
+    const status = computeScheduleStatus(schedule, record, now);
+    return {
+      id: 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 || `schedule:${scheduleId}`,
+      due: status.due,
+      due_reason: status.due_reason,
+      next_due_at: status.next_due_at,
+      project_status: projectStatus,
+      last_started_at: record.last_started_at,
+      last_finished_at: record.last_finished_at,
+      last_run_id: record.last_run_id,
+      last_status: record.last_status,
+      last_skip_at: record.last_skip_at,
+      last_skip_reason: record.last_skip_reason,
+    };
+  });
+}
+
+export function evaluateScheduleLaunchEligibility(root, config) {
+  const projectState = loadProjectState(root, config);
+  const status = projectState?.status || 'missing';
+
+  if (status === 'missing' || status === 'idle' || status === 'completed') {
+    return { ok: true, status };
+  }
+
+  if (status === 'blocked') {
+    return { ok: false, status, reason: 'run_blocked' };
+  }
+
+  if (status === 'active') {
+    return { ok: false, status, reason: 'run_active' };
+  }
+
+  if (status === 'paused') {
+    return { ok: false, status, reason: 'run_paused' };
+  }
+
+  return { ok: false, status, reason: `run_${status}` };
+}