agentxchain 2.77.0 → 2.78.0

package/bin/agentxchain.js

@@ -111,6 +111,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 { diffCommand } from '../src/commands/diff.js';
 import { eventsCommand } from '../src/commands/events.js';
 import { connectorCheckCommand } from '../src/commands/connector.js';
 import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand, scheduleStatusCommand } from '../src/commands/schedule.js';
@@ -330,6 +331,13 @@ program
   .option('-d, --dir <path>', 'Project directory')
   .action(historyCommand);
 
+program
+  .command('diff <left_run_id> <right_run_id>')
+  .description('Compare two recorded governed runs from run-history')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(diffCommand);
+
 program
   .command('events')
   .description('Show repo-local run lifecycle events')

package/package.json

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

package/src/commands/diff.js

@@ -0,0 +1,121 @@
+import chalk from 'chalk';
+
+import { findProjectRoot } from '../lib/config.js';
+import { buildRunDiff, resolveRunHistoryReference } from '../lib/run-diff.js';
+
+export async function diffCommand(leftRef, rightRef, 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 leftResult = resolveRunHistoryReference(root, leftRef);
+  if (!leftResult.ok) {
+    console.error(chalk.red(leftResult.error));
+    process.exit(1);
+  }
+
+  const rightResult = resolveRunHistoryReference(root, rightRef);
+  if (!rightResult.ok) {
+    console.error(chalk.red(rightResult.error));
+    process.exit(1);
+  }
+
+  const diff = buildRunDiff(leftResult.entry, rightResult.entry);
+  if (opts.json) {
+    console.log(JSON.stringify(diff, null, 2));
+    return;
+  }
+
+  console.log(formatRunDiffText(diff));
+}
+
+function formatRunDiffText(diff) {
+  const lines = [];
+  lines.push(chalk.bold('Run Diff'));
+  lines.push(`${chalk.dim('Left:')}  ${formatRunHeader(diff.left)}`);
+  lines.push(`${chalk.dim('Right:')} ${formatRunHeader(diff.right)}`);
+
+  if (!diff.changed) {
+    lines.push('');
+    lines.push(chalk.green('No differences.'));
+    return lines.join('\n');
+  }
+
+  appendChangedSection(lines, 'Changed fields', Object.values(diff.scalar_changes)
+    .filter((entry) => entry.changed)
+    .map((entry) => `${entry.label}: ${formatValue(entry.left, entry.label)} -> ${formatValue(entry.right, entry.label)}`));
+
+  appendChangedSection(lines, 'Numeric deltas', Object.values(diff.numeric_changes)
+    .filter((entry) => entry.changed)
+    .map((entry) => `${entry.label}: ${formatValue(entry.left, entry.label)} -> ${formatValue(entry.right, entry.label)}${formatDelta(entry.delta, entry.label)}`));
+
+  appendChangedSection(lines, 'List changes', Object.values(diff.list_changes)
+    .filter((entry) => entry.changed)
+    .flatMap((entry) => {
+      const items = [];
+      if (entry.added.length > 0) {
+        items.push(`${entry.label} added: ${entry.added.join(', ')}`);
+      }
+      if (entry.removed.length > 0) {
+        items.push(`${entry.label} removed: ${entry.removed.join(', ')}`);
+      }
+      return items;
+    }));
+
+  appendChangedSection(lines, 'Gate changes', diff.gate_changes
+    .filter((entry) => entry.changed)
+    .map((entry) => `${entry.gate_id}: ${formatValue(entry.left)} -> ${formatValue(entry.right)}`));
+
+  return lines.join('\n');
+}
+
+function appendChangedSection(lines, heading, items) {
+  if (items.length === 0) return;
+  lines.push('');
+  lines.push(chalk.bold(heading));
+  for (const item of items) {
+    lines.push(`- ${item}`);
+  }
+}
+
+function formatRunHeader(entry) {
+  const status = entry.status || '—';
+  const trigger = entry.trigger || 'legacy';
+  const recordedAt = entry.recorded_at
+    ? new Date(entry.recorded_at).toLocaleString()
+    : 'unknown date';
+  return `${entry.run_id} (${status}, ${trigger}, ${recordedAt})`;
+}
+
+function formatValue(value, label = '') {
+  if (value == null) return '—';
+  if (typeof value === 'boolean') return value ? 'yes' : 'no';
+  if (label === 'Cost' || label === 'Budget') return `$${value.toFixed(4)}`;
+  if (label === 'Duration') return formatDuration(value);
+  return String(value);
+}
+
+function formatDelta(delta, label) {
+  if (delta == null || delta === 0) return '';
+  if (label === 'Cost' || label === 'Budget') {
+    return ` (${delta > 0 ? '+' : ''}$${delta.toFixed(4)})`;
+  }
+  if (label === 'Duration') {
+    return ` (${delta > 0 ? '+' : ''}${formatDuration(delta)})`;
+  }
+  return ` (${delta > 0 ? '+' : ''}${delta})`;
+}
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const secs = Math.floor(ms / 1000);
+  if (secs < 60) return `${secs}s`;
+  const mins = Math.floor(secs / 60);
+  const remainSecs = secs % 60;
+  if (mins < 60) return `${mins}m ${remainSecs}s`;
+  const hrs = Math.floor(mins / 60);
+  const remainMins = mins % 60;
+  return `${hrs}h ${remainMins}m`;
+}

package/src/lib/run-diff.js

@@ -0,0 +1,194 @@
+import { isInheritable, queryRunHistory } from './run-history.js';
+import { getRunTriggerLabel } from './run-provenance.js';
+
+const SCALAR_FIELDS = [
+  ['status', 'Status'],
+  ['trigger', 'Trigger'],
+  ['template', 'Template'],
+  ['connector_used', 'Connector'],
+  ['model_used', 'Model'],
+  ['blocked_reason', 'Blocked reason'],
+  ['headline', 'Headline'],
+  ['inheritable', 'Inheritance snapshot'],
+];
+
+const NUMERIC_FIELDS = [
+  ['total_turns', 'Turns'],
+  ['decisions_count', 'Decisions'],
+  ['total_cost_usd', 'Cost'],
+  ['budget_limit_usd', 'Budget'],
+  ['duration_ms', 'Duration'],
+];
+
+export function resolveRunHistoryReference(root, ref) {
+  const entries = queryRunHistory(root, {});
+
+  if (entries.length === 0) {
+    return {
+      ok: false,
+      error: 'No run history found. Run at least one governed run first.',
+    };
+  }
+
+  const exact = entries.find((entry) => entry.run_id === ref);
+  if (exact) {
+    return { ok: true, entry: exact, resolved_ref: exact.run_id, match_kind: 'exact' };
+  }
+
+  const prefixMatches = entries.filter((entry) => typeof entry.run_id === 'string' && entry.run_id.startsWith(ref));
+  if (prefixMatches.length === 1) {
+    return {
+      ok: true,
+      entry: prefixMatches[0],
+      resolved_ref: prefixMatches[0].run_id,
+      match_kind: 'prefix',
+    };
+  }
+
+  if (prefixMatches.length > 1) {
+    return {
+      ok: false,
+      error: `Run reference "${ref}" is ambiguous. Matches: ${prefixMatches.map((entry) => entry.run_id).join(', ')}`,
+    };
+  }
+
+  return {
+    ok: false,
+    error: `Run ${ref} not found in run history.`,
+  };
+}
+
+export function buildRunDiff(leftEntry, rightEntry) {
+  const left = normalizeRunEntry(leftEntry);
+  const right = normalizeRunEntry(rightEntry);
+
+  const scalar_changes = Object.fromEntries(
+    SCALAR_FIELDS.map(([field, label]) => {
+      const leftValue = left[field];
+      const rightValue = right[field];
+      return [field, {
+        label,
+        left: leftValue,
+        right: rightValue,
+        changed: !isEqual(leftValue, rightValue),
+      }];
+    }),
+  );
+
+  const numeric_changes = Object.fromEntries(
+    NUMERIC_FIELDS.map(([field, label]) => {
+      const leftValue = left[field];
+      const rightValue = right[field];
+      return [field, {
+        label,
+        left: leftValue,
+        right: rightValue,
+        changed: !isEqual(leftValue, rightValue),
+        delta: typeof leftValue === 'number' && typeof rightValue === 'number'
+          ? rightValue - leftValue
+          : null,
+      }];
+    }),
+  );
+
+  const list_changes = {
+    phases_completed: buildListChange('Phases', left.phases_completed, right.phases_completed),
+    roles_used: buildListChange('Roles', left.roles_used, right.roles_used),
+  };
+
+  const gate_changes = buildGateChanges(left.gate_results, right.gate_results);
+
+  const changed = [
+    ...Object.values(scalar_changes),
+    ...Object.values(numeric_changes),
+  ].some((entry) => entry.changed)
+    || Object.values(list_changes).some((entry) => entry.changed)
+    || gate_changes.some((entry) => entry.changed);
+
+  return {
+    changed,
+    left,
+    right,
+    scalar_changes,
+    numeric_changes,
+    list_changes,
+    gate_changes,
+  };
+}
+
+function normalizeRunEntry(entry) {
+  return {
+    run_id: entry.run_id || null,
+    status: entry.status || null,
+    trigger: getRunTriggerLabel(entry.provenance),
+    template: entry.template || null,
+    connector_used: entry.connector_used || null,
+    model_used: entry.model_used || null,
+    blocked_reason: entry.blocked_reason || null,
+    headline: entry.retrospective?.headline || null,
+    inheritable: isInheritable(entry),
+    total_turns: typeof entry.total_turns === 'number' ? entry.total_turns : null,
+    decisions_count: typeof entry.decisions_count === 'number' ? entry.decisions_count : null,
+    total_cost_usd: typeof entry.total_cost_usd === 'number' ? entry.total_cost_usd : null,
+    budget_limit_usd: typeof entry.budget_limit_usd === 'number' ? entry.budget_limit_usd : null,
+    duration_ms: typeof entry.duration_ms === 'number' ? entry.duration_ms : null,
+    phases_completed: normalizeStringArray(entry.phases_completed),
+    roles_used: normalizeStringArray(entry.roles_used),
+    gate_results: normalizeGateResults(entry.gate_results),
+    recorded_at: entry.recorded_at || null,
+  };
+}
+
+function buildListChange(label, left, right) {
+  const leftSet = new Set(left);
+  const rightSet = new Set(right);
+  const added = right.filter((value) => !leftSet.has(value));
+  const removed = left.filter((value) => !rightSet.has(value));
+  return {
+    label,
+    left,
+    right,
+    added,
+    removed,
+    changed: added.length > 0 || removed.length > 0,
+  };
+}
+
+function buildGateChanges(leftGateResults, rightGateResults) {
+  const gateIds = [...new Set([
+    ...Object.keys(leftGateResults),
+    ...Object.keys(rightGateResults),
+  ])].sort((a, b) => a.localeCompare(b, 'en'));
+
+  return gateIds.map((gateId) => {
+    const left = gateId in leftGateResults ? leftGateResults[gateId] : null;
+    const right = gateId in rightGateResults ? rightGateResults[gateId] : null;
+    return {
+      gate_id: gateId,
+      left,
+      right,
+      changed: !isEqual(left, right),
+    };
+  });
+}
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value
+    .filter((item) => typeof item === 'string' && item.trim().length > 0)
+    .map((item) => item.trim()))]
+    .sort((a, b) => a.localeCompare(b, 'en'));
+}
+
+function normalizeGateResults(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([gateId]) => typeof gateId === 'string' && gateId.trim().length > 0)
+      .map(([gateId, result]) => [gateId.trim(), result ?? null]),
+  );
+}
+
+function isEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}