agentxchain 2.47.0 → 2.48.0

package/bin/agentxchain.js

@@ -106,6 +106,7 @@ import { intakeResolveCommand } from '../src/commands/intake-resolve.js';
 import { intakeStatusCommand } from '../src/commands/intake-status.js';
 import { demoCommand } from '../src/commands/demo.js';
 import { historyCommand } from '../src/commands/history.js';
+import { eventsCommand } from '../src/commands/events.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -267,6 +268,17 @@ program
   .option('-d, --dir <path>', 'Project directory')
   .action(historyCommand);
 
+program
+  .command('events')
+  .description('Show repo-local run lifecycle events')
+  .option('-f, --follow', 'Stream events as they occur')
+  .option('-t, --type <type>', 'Filter by event type (comma-separated)')
+  .option('--since <timestamp>', 'Show events after ISO-8601 timestamp')
+  .option('-j, --json', 'Output raw JSONL')
+  .option('-l, --limit <n>', 'Max events to show (default: 50, 0 = all)')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(eventsCommand);
+
 program
   .command('validate')
   .description('Validate project protocol artifacts')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.47.0",
+  "version": "2.48.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/events.js

@@ -0,0 +1,150 @@
+/**
+ * agentxchain events — repo-local run event stream reader.
+ *
+ * Reads and optionally follows the `.agentxchain/events.jsonl` log,
+ * giving operators structured visibility into governed run lifecycle
+ * without requiring webhooks or a dashboard.
+ */
+
+import { resolve } from 'path';
+import { existsSync, watchFile, unwatchFile } from 'fs';
+import { readFileSync } from 'fs';
+import chalk from 'chalk';
+import { readRunEvents, RUN_EVENTS_PATH, VALID_RUN_EVENTS } from '../lib/run-events.js';
+
+/**
+ * @param {object} opts
+ * @param {boolean} [opts.follow]  - Stream events as they arrive
+ * @param {string}  [opts.type]    - Comma-separated event types
+ * @param {string}  [opts.since]   - ISO-8601 timestamp filter
+ * @param {boolean} [opts.json]    - Raw JSONL output
+ * @param {number}  [opts.limit]   - Max events to show (default 50)
+ * @param {string}  [opts.dir]     - Project directory
+ */
+export async function eventsCommand(opts) {
+  const root = findProjectRoot(opts.dir || process.cwd());
+  if (!root) {
+    console.error(chalk.red('No AgentXchain project found. Run this inside a governed project.'));
+    process.exit(1);
+  }
+
+  const limit = opts.limit != null ? parseInt(opts.limit, 10) : 50;
+  const events = readRunEvents(root, {
+    type: opts.type,
+    since: opts.since,
+    limit: limit === 0 ? undefined : limit,
+  });
+
+  if (opts.json) {
+    for (const evt of events) {
+      console.log(JSON.stringify(evt));
+    }
+  } else {
+    if (events.length === 0 && !opts.follow) {
+      console.log(chalk.dim('No events found.'));
+      if (opts.type) console.log(chalk.dim(`  (filtered by type: ${opts.type})`));
+      return;
+    }
+    for (const evt of events) {
+      printEvent(evt);
+    }
+  }
+
+  if (opts.follow) {
+    return followEvents(root, opts);
+  }
+}
+
+function printEvent(evt) {
+  const ts = evt.timestamp ? new Date(evt.timestamp).toLocaleTimeString() : '—';
+  const type = colorEventType(evt.event_type);
+  const runId = evt.run_id ? evt.run_id.slice(0, 12) : '—';
+  const phase = evt.phase || '—';
+  const turnInfo = evt.turn?.role_id ? ` [${evt.turn.role_id}]` : '';
+  console.log(`${chalk.dim(ts)}  ${type}  ${chalk.cyan(runId)}  ${phase}${turnInfo}`);
+}
+
+function colorEventType(type) {
+  const colors = {
+    run_started: chalk.green,
+    run_completed: chalk.green.bold,
+    run_blocked: chalk.red,
+    turn_dispatched: chalk.blue,
+    turn_accepted: chalk.green,
+    turn_rejected: chalk.yellow,
+    phase_entered: chalk.magenta,
+    escalation_raised: chalk.red.bold,
+    escalation_resolved: chalk.green,
+    gate_pending: chalk.yellow,
+    gate_approved: chalk.green,
+  };
+  const colorFn = colors[type] || chalk.white;
+  return colorFn(pad(type, 22));
+}
+
+function pad(str, len) {
+  return (str || '').padEnd(len);
+}
+
+function followEvents(root, opts) {
+  const filePath = resolve(root, RUN_EVENTS_PATH);
+  let lastSize = 0;
+
+  try {
+    if (existsSync(filePath)) {
+      lastSize = readFileSync(filePath).length;
+    }
+  } catch {}
+
+  console.log(chalk.dim('Watching for events... (Ctrl+C to stop)'));
+
+  return new Promise(() => {
+    const checkForNewEvents = () => {
+      try {
+        if (!existsSync(filePath)) return;
+        const content = readFileSync(filePath, 'utf8');
+        if (content.length <= lastSize) return;
+
+        const newContent = content.slice(lastSize);
+        lastSize = content.length;
+
+        const lines = newContent.split('\n').filter(Boolean);
+        for (const line of lines) {
+          try {
+            const evt = JSON.parse(line);
+            if (opts.type) {
+              const types = new Set(opts.type.split(',').map(t => t.trim()));
+              if (!types.has(evt.event_type)) continue;
+            }
+            if (opts.json) {
+              console.log(JSON.stringify(evt));
+            } else {
+              printEvent(evt);
+            }
+          } catch {}
+        }
+      } catch {}
+    };
+
+    watchFile(filePath, { interval: 200 }, checkForNewEvents);
+
+    process.on('SIGINT', () => {
+      unwatchFile(filePath, checkForNewEvents);
+      process.exit(0);
+    });
+  });
+}
+
+/**
+ * Walk up to find the nearest directory containing agentxchain.json.
+ */
+function findProjectRoot(start) {
+  let dir = resolve(start);
+  while (true) {
+    if (existsSync(resolve(dir, 'agentxchain.json'))) return dir;
+    if (existsSync(resolve(dir, '.agentxchain', 'state.json'))) return dir;
+    const parent = resolve(dir, '..');
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}

package/src/lib/export.js

@@ -31,6 +31,7 @@ export const RUN_EXPORT_INCLUDED_ROOTS = [
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/notification-audit.jsonl',
   '.agentxchain/run-history.jsonl',
+  '.agentxchain/events.jsonl',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',
@@ -53,6 +54,7 @@ export const RUN_RESTORE_ROOTS = [
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/notification-audit.jsonl',
   '.agentxchain/run-history.jsonl',
+  '.agentxchain/events.jsonl',
   '.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/repo-observer.js

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

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;
+}