agentxchain 2.110.0 → 2.112.0

package/scripts/release-preflight.sh

@@ -85,7 +85,7 @@ fi
 echo ""
 
 # 1. Clean working tree
-echo "[1/6] Git status"
+echo "[1/7] Git status"
 if git diff --quiet HEAD 2>/dev/null && [ -z "$(git ls-files --others --exclude-standard 2>/dev/null)" ]; then
   pass "Working tree is clean"
 else
@@ -97,7 +97,7 @@ else
 fi
 
 # 2. Dependencies
-echo "[2/6] Dependencies"
+echo "[2/7] Dependencies"
 if run_and_capture NPM_CI_OUTPUT npm ci --ignore-scripts; then
   pass "npm ci succeeded"
 else
@@ -107,7 +107,7 @@ fi
 
 # 3. Tests
 if [[ "$PUBLISH_GATE" -eq 1 ]]; then
-  echo "[3/6] Release-gate tests (targeted subset)"
+  echo "[3/7] Release-gate tests (targeted subset)"
   # In publish-gate mode, run only release-critical tests to avoid CI hangs.
   # The full test suite is a pre-tag responsibility, not a publish-time gate.
   GATE_TESTS=(
@@ -142,7 +142,7 @@ if [[ "$PUBLISH_GATE" -eq 1 ]]; then
     fi
   fi
 else
-  echo "[3/6] Test suite"
+  echo "[3/7] Test suite"
   # Install MCP example deps — tests start example servers as subprocesses
   for example_dir in "${CLI_DIR}/../examples/mcp-echo-agent" "${CLI_DIR}/../examples/mcp-http-echo-agent"; do
     if [[ -f "${example_dir}/package.json" && ! -d "${example_dir}/node_modules" ]]; then
@@ -189,7 +189,7 @@ else
 fi
 
 # 4. CHANGELOG has target version
-echo "[4/6] CHANGELOG"
+echo "[4/7] CHANGELOG"
 if grep -Fxq "## ${TARGET_VERSION}" CHANGELOG.md 2>/dev/null; then
   pass "CHANGELOG.md contains ${TARGET_VERSION} entry"
 else
@@ -197,7 +197,7 @@ else
 fi
 
 # 5. Package version
-echo "[5/6] Package version"
+echo "[5/7] Package version"
 PKG_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).version)")
 echo "  Current version: ${PKG_VERSION}"
 if [ "$PKG_VERSION" = "${TARGET_VERSION}" ]; then
@@ -210,8 +210,23 @@ else
   fi
 fi
 
-# 6. Pack dry-run
-echo "[6/6] npm pack --dry-run"
+# 6. Release-alignment surfaces (shared manifest)
+echo "[6/7] Release alignment (shared manifest)"
+ALIGNMENT_SCRIPT="${SCRIPT_DIR}/check-release-alignment.mjs"
+if [[ -f "$ALIGNMENT_SCRIPT" ]]; then
+  if run_and_capture ALIGNMENT_OUTPUT node "$ALIGNMENT_SCRIPT" --scope current --target-version "$TARGET_VERSION"; then
+    ALIGNED_COUNT="$(printf '%s\n' "$ALIGNMENT_OUTPUT" | awk -F'[,)]' '/surfaces/ { for (i=1;i<=NF;i++) if ($i ~ /[0-9]+ surfaces/) { gsub(/[^0-9]/,"",$i); print $i; exit } }')"
+    pass "Release alignment OK (${ALIGNED_COUNT:-all} surfaces)"
+  else
+    fail "Release alignment failed"
+    printf '%s\n' "$ALIGNMENT_OUTPUT" | head -20
+  fi
+else
+  warn "check-release-alignment.mjs not found — skipping manifest validation"
+fi
+
+# 7. Pack dry-run
+echo "[7/7] npm pack --dry-run"
 if run_and_capture PACK_OUTPUT npm pack --dry-run; then
   pass "npm pack --dry-run succeeded"
   PACK_SIZE_LINE="$(printf '%s\n' "$PACK_OUTPUT" | awk '/total files:/ { print; found=1 } END { if (!found) exit 1 }')"

package/src/commands/chain.js

@@ -0,0 +1,252 @@
+/**
+ * agentxchain chain — operator-facing read surface for chain reports.
+ *
+ * Surfaces chain report metadata so operators can inspect lights-out
+ * run-chaining history without opening raw JSON files.
+ */
+
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import {
+  loadAllChainReports,
+  loadChainReport,
+  loadLatestChainReport,
+} from '../lib/chain-reports.js';
+
+/**
+ * agentxchain chain latest — show the most recent chain report.
+ *
+ * @param {object} opts - { json?: boolean, dir?: string }
+ */
+export async function chainLatestCommand(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 report = loadLatestChainReport(root);
+  if (!report) {
+    console.log(chalk.dim('No chain reports found.'));
+    console.log(chalk.dim('  Run `agentxchain run --chain` to enable auto-chaining.'));
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  renderChainReport(report);
+}
+
+/**
+ * agentxchain chain list — list all chain reports.
+ *
+ * @param {object} opts - { json?: boolean, limit?: number, dir?: string }
+ */
+export async function chainListCommand(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 reports = loadAllChainReports(root);
+  const limit = opts.limit ? parseInt(opts.limit, 10) : 20;
+  const limited = reports.slice(0, limit);
+
+  if (opts.json) {
+    console.log(JSON.stringify(limited, null, 2));
+    return;
+  }
+
+  if (limited.length === 0) {
+    console.log(chalk.dim('No chain reports found.'));
+    console.log(chalk.dim('  Run `agentxchain run --chain` to enable auto-chaining.'));
+    return;
+  }
+
+  // Table header
+  const header = [
+    pad('#', 4),
+    pad('Chain ID', 16),
+    pad('Runs', 6),
+    pad('Turns', 7),
+    pad('Terminal Reason', 28),
+    pad('Duration', 12),
+    pad('Started', 22),
+  ].join(' ');
+
+  console.log(chalk.bold(header));
+  console.log(chalk.dim('─'.repeat(header.length)));
+
+  limited.forEach((report, i) => {
+    const idx = String(i + 1);
+    const chainId = report.chain_id || '—';
+    const runs = String(report.runs?.length || 0);
+    const turns = String(report.total_turns || 0);
+    const terminal = formatTerminalReason(report.terminal_reason);
+    const duration = report.total_duration_ms != null
+      ? formatDuration(report.total_duration_ms)
+      : '—';
+    const started = report.started_at
+      ? new Date(report.started_at).toLocaleString()
+      : '—';
+
+    console.log([
+      pad(idx, 4),
+      pad(chainId, 16),
+      pad(runs, 6),
+      pad(turns, 7),
+      pad(terminal, 28),
+      pad(duration, 12),
+      pad(started, 22),
+    ].join(' '));
+  });
+
+  console.log(chalk.dim(`\n${limited.length} chain(s) shown${reports.length > limit ? ` (${reports.length} total)` : ''}`));
+}
+
+/**
+ * agentxchain chain show <chain_id> — show a specific chain report.
+ *
+ * @param {string} chainId
+ * @param {object} opts - { json?: boolean, dir?: string }
+ */
+export async function chainShowCommand(chainId, 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 report = loadChainReport(root, chainId);
+  if (!report) {
+    console.error(chalk.red(`Chain report not found: ${chainId}`));
+    console.log(chalk.dim('  Use `agentxchain chain list` to see available chain reports.'));
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  renderChainReport(report);
+}
+
+// ── Rendering ─────────────────────────────────────────────────────────────────
+
+function renderChainReport(report) {
+  console.log(chalk.bold(`Chain Report: ${report.chain_id}`));
+  console.log('');
+  console.log(`  Total runs:     ${report.runs?.length || 0}`);
+  console.log(`  Total turns:    ${report.total_turns || 0}`);
+  console.log(`  Duration:       ${formatDuration(report.total_duration_ms || 0)}`);
+  console.log(`  Terminal:       ${formatTerminalReason(report.terminal_reason)}`);
+  console.log(`  Started:        ${report.started_at || '—'}`);
+  console.log(`  Completed:      ${report.completed_at || '—'}`);
+  console.log('');
+
+  if (!report.runs || report.runs.length === 0) {
+    console.log(chalk.dim('  No runs recorded.'));
+    return;
+  }
+
+  // Run table header
+  const runHeader = [
+    pad('#', 4),
+    pad('Run ID', 14),
+    pad('Status', 12),
+    pad('Trigger', 14),
+    pad('Turns', 7),
+    pad('Duration', 12),
+    pad('Parent', 14),
+    pad('Ctx', 40),
+  ].join(' ');
+
+  console.log(chalk.bold('  Runs:'));
+  console.log(`  ${chalk.dim(runHeader)}`);
+  console.log(`  ${chalk.dim('─'.repeat(runHeader.length))}`);
+
+  report.runs.forEach((run, i) => {
+    const idx = String(i + 1);
+    const runId = (run.run_id || '—').slice(0, 12);
+    const status = formatStatus(run.status);
+    const trigger = run.provenance_trigger || '—';
+    const turns = String(run.turns || 0);
+    const duration = run.duration_ms != null ? formatDuration(run.duration_ms) : '—';
+    const parent = run.parent_run_id ? run.parent_run_id.slice(0, 12) : '—';
+    const ctx = formatInheritedContextSummary(run.inherited_context_summary);
+
+    console.log(`  ${[
+      pad(idx, 4),
+      pad(runId, 14),
+      pad(status, 12),
+      pad(trigger, 14),
+      pad(turns, 7),
+      pad(duration, 12),
+      pad(parent, 14),
+      pad(ctx, 40),
+    ].join(' ')}`);
+  });
+}
+
+function formatInheritedContextSummary(summary) {
+  if (!summary) return '—';
+
+  const parts = [];
+  if (summary.parent_roles_used?.length) {
+    parts.push(`${summary.parent_roles_used.length} roles`);
+  }
+  if (summary.parent_phases_completed_count > 0) {
+    parts.push(`${summary.parent_phases_completed_count} phases`);
+  }
+  if (summary.recent_decisions_count > 0) {
+    parts.push(`${summary.recent_decisions_count} decisions`);
+  }
+  if (summary.recent_accepted_turns_count > 0) {
+    parts.push(`${summary.recent_accepted_turns_count} turns`);
+  }
+
+  return parts.length > 0 ? parts.join(', ') : '—';
+}
+
+function formatTerminalReason(reason) {
+  if (!reason) return '—';
+  switch (reason) {
+    case 'chain_limit_reached': return chalk.cyan('chain limit reached');
+    case 'non_chainable_status': return chalk.yellow('non-chainable status');
+    case 'operator_abort': return chalk.red('operator abort');
+    case 'parent_validation_failed': return chalk.red('parent validation failed');
+    case 'completed': return chalk.green('completed');
+    case 'blocked': return chalk.yellow('blocked');
+    default: return reason;
+  }
+}
+
+function formatStatus(status) {
+  if (status === 'completed') return chalk.green('completed');
+  if (status === 'blocked') return chalk.yellow('blocked');
+  if (status === 'failed') return chalk.red('failed');
+  return status || '—';
+}
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) return `${minutes}m ${remainingSeconds}s`;
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours}h ${remainingMinutes}m`;
+}
+
+function pad(str, width) {
+  return String(str).padEnd(width);
+}
+
+// ── Data Loading ──────────────────────────────────────────────────────────────

package/src/commands/diff.js

@@ -215,9 +215,28 @@ function formatValue(value, label = '') {
   if (typeof value === 'boolean') return value ? 'yes' : 'no';
   if (label === 'Cost' || label === 'Budget') return `$${value.toFixed(4)}`;
   if (label === 'Duration') return formatDuration(value);
+  if (label === 'Blocked reason' && value && typeof value === 'object') {
+    return formatBlockedReason(value);
+  }
+  if (typeof value === 'object') return JSON.stringify(value);
   return String(value);
 }
 
+function formatBlockedReason(reason) {
+  const category = reason.category || 'unknown';
+  const gateAction = reason.gate_action;
+  if (category === 'gate_action_failed' && gateAction) {
+    const actionLabel = gateAction.action_label || gateAction.command || 'unknown action';
+    if (gateAction.timed_out) {
+      return `gate_action_failed: ${actionLabel} timed out after ${gateAction.timeout_ms}ms`;
+    }
+    const exit = gateAction.exit_code != null ? ` (exit ${gateAction.exit_code})` : '';
+    return `gate_action_failed: ${actionLabel} failed${exit}`;
+  }
+  const detail = reason.detail || reason.recovery?.detail || '';
+  return detail ? `${category}: ${detail}` : category;
+}
+
 function formatDelta(delta, label) {
   if (delta == null || delta === 0) return '';
   if (label === 'Cost' || label === 'Budget') {

package/src/commands/mission.js

@@ -0,0 +1,252 @@
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import {
+  attachChainToMission,
+  buildMissionListSummary,
+  buildMissionSnapshot,
+  createMission,
+  loadLatestMissionArtifact,
+  loadLatestMissionSnapshot,
+  loadMissionArtifact,
+  loadMissionSnapshot,
+} from '../lib/missions.js';
+
+export async function missionStartCommand(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 title = String(opts.title || '').trim();
+  const goal = String(opts.goal || '').trim();
+  if (!title) {
+    console.error(chalk.red('Mission title is required. Use --title <text>.'));
+    process.exit(1);
+  }
+  if (!goal) {
+    console.error(chalk.red('Mission goal is required. Use --goal <text>.'));
+    process.exit(1);
+  }
+
+  const result = createMission(root, {
+    missionId: opts.id,
+    title,
+    goal,
+  });
+  if (!result.ok) {
+    console.error(chalk.red(result.error));
+    process.exit(1);
+  }
+
+  const snapshot = buildMissionSnapshot(root, result.mission);
+  if (opts.json) {
+    console.log(JSON.stringify(snapshot, null, 2));
+    return;
+  }
+
+  console.log(chalk.green(`Created mission ${snapshot.mission_id}`));
+  console.log(chalk.dim(`  Goal: ${snapshot.goal}`));
+  renderMissionSnapshot(snapshot);
+}
+
+export async function missionListCommand(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 ? parseInt(opts.limit, 10) : 20;
+  const missions = buildMissionListSummary(root, limit);
+
+  if (opts.json) {
+    console.log(JSON.stringify(missions, null, 2));
+    return;
+  }
+
+  if (missions.length === 0) {
+    console.log(chalk.dim('No missions found.'));
+    console.log(chalk.dim('  Run `agentxchain mission start --title "..." --goal "..."` to create one.'));
+    return;
+  }
+
+  const header = [
+    pad('#', 4),
+    pad('Mission ID', 28),
+    pad('Status', 18),
+    pad('Chains', 8),
+    pad('Runs', 7),
+    pad('Turns', 7),
+    pad('Decisions', 10),
+    pad('Updated', 22),
+    'Title',
+  ].join(' ');
+
+  console.log(chalk.bold(header));
+  console.log(chalk.dim('─'.repeat(header.length)));
+
+  missions.forEach((mission, index) => {
+    console.log([
+      pad(String(index + 1), 4),
+      pad(mission.mission_id || '—', 28),
+      pad(formatMissionStatus(mission.derived_status), 18),
+      pad(String(mission.chain_count || 0), 8),
+      pad(String(mission.total_runs || 0), 7),
+      pad(String(mission.total_turns || 0), 7),
+      pad(String(mission.active_repo_decisions_count || 0), 10),
+      pad(formatTimestamp(mission.updated_at), 22),
+      mission.title || '—',
+    ].join(' '));
+  });
+
+  console.log(chalk.dim(`\n${missions.length} mission(s) shown`));
+}
+
+export async function missionShowCommand(missionId, 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 snapshot = missionId
+    ? loadMissionSnapshot(root, missionId)
+    : loadLatestMissionSnapshot(root);
+  if (!snapshot) {
+    if (missionId) {
+      console.error(chalk.red(`Mission not found: ${missionId}`));
+      process.exit(1);
+    }
+    console.log(chalk.dim('No missions found.'));
+    console.log(chalk.dim('  Run `agentxchain mission start --title "..." --goal "..."` to create one.'));
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(snapshot, null, 2));
+    return;
+  }
+
+  renderMissionSnapshot(snapshot);
+}
+
+export async function missionAttachChainCommand(chainId, 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 mission = opts.mission
+    ? loadMissionArtifact(root, opts.mission)
+    : loadLatestMissionArtifact(root);
+  if (!mission) {
+    console.error(chalk.red('No mission found to attach to.'));
+    console.error(chalk.dim('  Use `agentxchain mission start --title "..." --goal "..."` first.'));
+    process.exit(1);
+  }
+
+  const result = attachChainToMission(root, mission.mission_id, chainId || 'latest');
+  if (!result.ok) {
+    console.error(chalk.red(result.error));
+    process.exit(1);
+  }
+
+  const snapshot = buildMissionSnapshot(root, result.mission);
+  if (opts.json) {
+    console.log(JSON.stringify(snapshot, null, 2));
+    return;
+  }
+
+  console.log(chalk.green(`Attached ${result.chain.chain_id} to ${snapshot.mission_id}`));
+  renderMissionSnapshot(snapshot);
+}
+
+function renderMissionSnapshot(snapshot) {
+  console.log(chalk.bold(`Mission: ${snapshot.mission_id}`));
+  console.log('');
+  console.log(`  Title:                 ${snapshot.title || '—'}`);
+  console.log(`  Goal:                  ${snapshot.goal || '—'}`);
+  console.log(`  Status:                ${formatMissionStatus(snapshot.derived_status)}`);
+  console.log(`  Chains:                ${snapshot.chain_count || 0}`);
+  console.log(`  Total runs:            ${snapshot.total_runs || 0}`);
+  console.log(`  Total turns:           ${snapshot.total_turns || 0}`);
+  console.log(`  Active repo decisions: ${snapshot.active_repo_decisions_count || 0}`);
+  console.log(`  Latest chain:          ${snapshot.latest_chain_id || '—'}`);
+  console.log(`  Latest terminal:       ${snapshot.latest_terminal_reason || '—'}`);
+  console.log(`  Created:               ${snapshot.created_at || '—'}`);
+  console.log(`  Updated:               ${snapshot.updated_at || '—'}`);
+
+  if (snapshot.missing_chain_ids?.length) {
+    console.log(`  Missing chains:        ${snapshot.missing_chain_ids.join(', ')}`);
+  }
+
+  if (!snapshot.chains || snapshot.chains.length === 0) {
+    console.log('');
+    console.log(chalk.dim('  No chains attached.'));
+    console.log(chalk.dim('  Use `agentxchain mission attach-chain latest` after a chained run.'));
+    return;
+  }
+
+  const header = [
+    pad('#', 4),
+    pad('Chain ID', 16),
+    pad('Runs', 6),
+    pad('Turns', 7),
+    pad('Terminal', 26),
+    pad('Started', 22),
+  ].join(' ');
+
+  console.log('');
+  console.log(chalk.bold('  Chains:'));
+  console.log(`  ${chalk.dim(header)}`);
+  console.log(`  ${chalk.dim('─'.repeat(header.length))}`);
+
+  snapshot.chains.forEach((chain, index) => {
+    console.log(`  ${[
+      pad(String(index + 1), 4),
+      pad(chain.chain_id || '—', 16),
+      pad(String(chain.runs?.length || 0), 6),
+      pad(String(chain.total_turns || 0), 7),
+      pad(formatTerminal(chain.terminal_reason), 26),
+      pad(formatTimestamp(chain.started_at), 22),
+    ].join(' ')}`);
+  });
+}
+
+function formatTerminal(reason) {
+  if (!reason) return '—';
+  if (reason === 'chain_limit_reached') return 'chain limit reached';
+  if (reason === 'non_chainable_status') return 'non-chainable status';
+  return reason.replace(/_/g, ' ');
+}
+
+function formatMissionStatus(status) {
+  if (!status) return '—';
+  switch (status) {
+    case 'planned':
+      return chalk.blue('planned');
+    case 'progressing':
+      return chalk.green('progressing');
+    case 'needs_attention':
+      return chalk.yellow('needs_attention');
+    case 'degraded':
+      return chalk.red('degraded');
+    default:
+      return status;
+  }
+}
+
+function formatTimestamp(value) {
+  if (!value) return '—';
+  try {
+    return new Date(value).toLocaleString();
+  } catch {
+    return value;
+  }
+}
+
+function pad(value, width) {
+  return String(value).padEnd(width);
+}