agentxchain 2.111.0 → 2.112.0

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

package/src/commands/run.js

@@ -56,7 +56,9 @@ export async function runCommand(opts) {
   const chainOpts = resolveChainOptions(opts, context.config);
   if (chainOpts.enabled) {
     console.log(chalk.cyan.bold('agentxchain run --chain'));
-    console.log(chalk.dim(`  Chain mode: enabled (max ${chainOpts.maxChains} continuations, on: ${chainOpts.chainOn.join(',')}, cooldown: ${chainOpts.cooldownSeconds}s)`));
+    const chainParts = [`max ${chainOpts.maxChains} continuations`, `on: ${chainOpts.chainOn.join(',')}`, `cooldown: ${chainOpts.cooldownSeconds}s`];
+    if (chainOpts.mission) chainParts.push(`mission: ${chainOpts.mission}`);
+    console.log(chalk.dim(`  Chain mode: enabled (${chainParts.join(', ')})`));
     const { exitCode } = await executeChainedRun(context, opts, chainOpts, executeGovernedRun);
     process.exit(exitCode);
   }

package/src/lib/dashboard/bridge-server.js

@@ -30,6 +30,7 @@ import { loadProjectContext, loadProjectState } from '../config.js';
 import { evaluateApprovalSlaReminders } from '../notification-runner.js';
 import { readGateActionSnapshot } from './gate-action-reader.js';
 import { readChainReportSnapshot } from './chain-report-reader.js';
+import { readMissionSnapshot } from './mission-reader.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -470,6 +471,13 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847,
       return;
     }
 
+    if (pathname === '/api/missions') {
+      const limit = url.searchParams.get('limit') ? parseInt(url.searchParams.get('limit'), 10) : undefined;
+      const result = readMissionSnapshot(workspacePath, { limit });
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     if (pathname === '/api/gate-actions') {
       const result = readGateActionSnapshot(workspacePath);
       writeJson(res, result.status, result.body);

package/src/lib/dashboard/file-watcher.js

@@ -8,7 +8,7 @@
 import { watch, existsSync } from 'fs';
 import { basename, join } from 'path';
 import { EventEmitter } from 'events';
-import { WATCH_DIRECTORIES, resourceForRelativePath } from './state-reader.js';
+import { WATCH_DIRECTORIES, resourcesForRelativePath } from './state-reader.js';
 
 const DEBOUNCE_MS = 100;
 
@@ -40,24 +40,26 @@ export class FileWatcher extends EventEmitter {
         if (!filename || this.#closed) return;
         const base = basename(filename);
         const relativePath = relativeDir ? `${relativeDir}/${base}` : base;
-        const resource = resourceForRelativePath(relativePath);
+        const resources = resourcesForRelativePath(relativePath);
 
-        if (!resource) {
+        if (resources.length === 0) {
           if (!relativeDir && base === 'multirepo') {
             this.#watchPath('multirepo');
           }
           return;
         }
 
-        if (this.#debounceTimers.has(resource)) {
-          clearTimeout(this.#debounceTimers.get(resource));
-        }
-        this.#debounceTimers.set(resource, setTimeout(() => {
-          this.#debounceTimers.delete(resource);
-          if (!this.#closed) {
-            this.emit('invalidate', { resource });
+        for (const resource of resources) {
+          if (this.#debounceTimers.has(resource)) {
+            clearTimeout(this.#debounceTimers.get(resource));
           }
-        }, DEBOUNCE_MS));
+          this.#debounceTimers.set(resource, setTimeout(() => {
+            this.#debounceTimers.delete(resource);
+            if (!this.#closed) {
+              this.emit('invalidate', { resource });
+            }
+          }, DEBOUNCE_MS));
+        }
       });
 
       watcher.on('error', (err) => {

package/src/lib/dashboard/mission-reader.js

@@ -0,0 +1,14 @@
+import { buildMissionListSummary, loadLatestMissionSnapshot } from '../missions.js';
+
+export function readMissionSnapshot(workspacePath, { limit } = {}) {
+  const missions = buildMissionListSummary(workspacePath, limit);
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      latest: loadLatestMissionSnapshot(workspacePath),
+      missions,
+    },
+  };
+}

package/src/lib/dashboard/state-reader.js

@@ -62,6 +62,7 @@ FILE_TO_RESOURCE[normalizeRelativePath(REPO_DECISIONS_FILE)] = '/api/repo-decisi
 export const WATCH_DIRECTORIES = [
   '',
   MULTIREPO_DIR,
+  'missions',
   'reports',
 ];
 
@@ -69,12 +70,20 @@ export function normalizeRelativePath(filePath) {
   return normalize(filePath).replace(/\\/g, '/').replace(/^\.\/+/, '');
 }
 
-export function resourceForRelativePath(filePath) {
+export function resourcesForRelativePath(filePath) {
   const normalized = normalizeRelativePath(filePath);
+  if (normalized.startsWith('missions/') && normalized.endsWith('.json')) {
+    return ['/api/missions'];
+  }
   if (normalized.startsWith('reports/chain-') && normalized.endsWith('.json')) {
-    return '/api/chain-reports';
+    return ['/api/chain-reports', '/api/missions'];
   }
-  return FILE_TO_RESOURCE[normalized] || null;
+  return FILE_TO_RESOURCE[normalized] ? [FILE_TO_RESOURCE[normalized]] : [];
+}
+
+export function resourceForRelativePath(filePath) {
+  const resources = resourcesForRelativePath(filePath);
+  return resources[0] || null;
 }
 
 /**

package/src/lib/missions.js

@@ -0,0 +1,195 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { loadAllChainReports, loadChainReport, loadLatestChainReport } from './chain-reports.js';
+import { getActiveRepoDecisions } from './repo-decisions.js';
+
+const MISSION_ATTENTION_TERMINALS = new Set(['operator_abort', 'parent_validation_failed']);
+const MISSION_ATTENTION_RUN_STATUSES = new Set(['blocked', 'failed']);
+
+export function getMissionsDir(root) {
+  return join(root, '.agentxchain', 'missions');
+}
+
+export function buildMissionId(input) {
+  const slug = String(input || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64);
+  const base = slug || 'untitled';
+  return base.startsWith('mission-') ? base : `mission-${base}`;
+}
+
+export function createMission(root, { missionId, title, goal }) {
+  const normalizedId = buildMissionId(missionId || title);
+  const filePath = join(getMissionsDir(root), `${normalizedId}.json`);
+  if (existsSync(filePath)) {
+    return { ok: false, error: `Mission already exists: ${normalizedId}` };
+  }
+
+  const now = new Date().toISOString();
+  const artifact = {
+    mission_id: normalizedId,
+    title,
+    goal,
+    status: 'active',
+    created_at: now,
+    updated_at: now,
+    chain_ids: [],
+  };
+
+  mkdirSync(getMissionsDir(root), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(artifact, null, 2));
+  return { ok: true, mission: artifact };
+}
+
+export function loadAllMissionArtifacts(root) {
+  const missionsDir = getMissionsDir(root);
+  if (!existsSync(missionsDir)) return [];
+
+  const missions = [];
+  for (const file of readdirSync(missionsDir).filter((entry) => entry.endsWith('.json')).sort()) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(missionsDir, file), 'utf8'));
+      if (parsed && parsed.mission_id) {
+        missions.push(parsed);
+      }
+    } catch {
+      // Advisory surface only. Skip malformed mission files.
+    }
+  }
+
+  missions.sort((left, right) => {
+    const leftTime = new Date(left.updated_at || left.created_at || 0).getTime();
+    const rightTime = new Date(right.updated_at || right.created_at || 0).getTime();
+    return rightTime - leftTime;
+  });
+
+  return missions;
+}
+
+export function loadMissionArtifact(root, missionId) {
+  const filePath = join(getMissionsDir(root), `${missionId}.json`);
+  if (existsSync(filePath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+      if (parsed?.mission_id) return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  return loadAllMissionArtifacts(root).find((mission) => mission.mission_id === missionId) || null;
+}
+
+export function loadLatestMissionArtifact(root) {
+  const missions = loadAllMissionArtifacts(root);
+  return missions.length > 0 ? missions[0] : null;
+}
+
+export function attachChainToMission(root, missionId, chainRef = 'latest') {
+  const mission = loadMissionArtifact(root, missionId);
+  if (!mission) {
+    return { ok: false, error: `Mission not found: ${missionId}` };
+  }
+
+  const chain = chainRef === 'latest'
+    ? loadLatestChainReport(root)
+    : loadChainReport(root, chainRef);
+  if (!chain) {
+    return { ok: false, error: chainRef === 'latest' ? 'No chain reports found.' : `Chain report not found: ${chainRef}` };
+  }
+
+  const nextChainIds = Array.isArray(mission.chain_ids) ? [...mission.chain_ids] : [];
+  if (!nextChainIds.includes(chain.chain_id)) {
+    nextChainIds.push(chain.chain_id);
+  }
+
+  const updated = {
+    ...mission,
+    chain_ids: nextChainIds,
+    updated_at: new Date().toISOString(),
+  };
+
+  mkdirSync(getMissionsDir(root), { recursive: true });
+  writeFileSync(join(getMissionsDir(root), `${updated.mission_id}.json`), JSON.stringify(updated, null, 2));
+  return { ok: true, mission: updated, chain };
+}
+
+export function buildMissionSnapshot(root, missionArtifact) {
+  const chainIds = Array.isArray(missionArtifact.chain_ids) ? missionArtifact.chain_ids : [];
+  const chains = [];
+  const missingChainIds = [];
+
+  for (const chainId of chainIds) {
+    const report = loadChainReport(root, chainId);
+    if (report) {
+      chains.push(report);
+    } else {
+      missingChainIds.push(chainId);
+    }
+  }
+
+  chains.sort((left, right) => {
+    const leftTime = new Date(left.started_at || 0).getTime();
+    const rightTime = new Date(right.started_at || 0).getTime();
+    return rightTime - leftTime;
+  });
+
+  const totalRuns = chains.reduce((sum, chain) => sum + (chain.runs?.length || 0), 0);
+  const totalTurns = chains.reduce((sum, chain) => sum + (chain.total_turns || 0), 0);
+  const latestChain = chains[0] || null;
+  const activeRepoDecisions = getActiveRepoDecisions(root);
+
+  return {
+    ...missionArtifact,
+    derived_status: deriveMissionStatus(missionArtifact, chains, missingChainIds),
+    chain_count: chainIds.length,
+    attached_chain_count: chains.length,
+    missing_chain_ids: missingChainIds,
+    total_runs: totalRuns,
+    total_turns: totalTurns,
+    latest_chain_id: latestChain?.chain_id || null,
+    latest_terminal_reason: latestChain?.terminal_reason || null,
+    active_repo_decisions_count: activeRepoDecisions.length,
+    chains,
+  };
+}
+
+export function loadAllMissionSnapshots(root) {
+  return loadAllMissionArtifacts(root).map((mission) => buildMissionSnapshot(root, mission));
+}
+
+function deriveMissionStatus(missionArtifact, chains, missingChainIds) {
+  if (missionArtifact.status && missionArtifact.status !== 'active') {
+    return missionArtifact.status;
+  }
+  if (missingChainIds.length > 0) return 'degraded';
+  if (chains.length === 0) return 'planned';
+  if (chains.some((chain) => (
+    MISSION_ATTENTION_TERMINALS.has(chain.terminal_reason)
+    || (chain.runs || []).some((run) => MISSION_ATTENTION_RUN_STATUSES.has(run.status))
+  ))) {
+    return 'needs_attention';
+  }
+  return 'progressing';
+}
+
+export function loadLatestMissionSnapshot(root) {
+  const artifact = loadLatestMissionArtifact(root);
+  return artifact ? buildMissionSnapshot(root, artifact) : null;
+}
+
+export function loadMissionSnapshot(root, missionId) {
+  const artifact = loadMissionArtifact(root, missionId);
+  return artifact ? buildMissionSnapshot(root, artifact) : null;
+}
+
+export function buildMissionListSummary(root, limit = 20) {
+  return loadAllMissionSnapshots(root).slice(0, limit);
+}
+
+export function loadMissionAttachmentTarget(root, missionId) {
+  if (missionId) return loadMissionArtifact(root, missionId);
+  return loadLatestMissionArtifact(root);
+}