agentxchain 0.8.8 → 2.1.1

package/src/lib/coordinator-state.js

@@ -0,0 +1,365 @@
+/**
+ * Coordinator state machine — multi-repo run lifecycle.
+ *
+ * Manages: super_run initialization, repo-local run linkage,
+ * coordinator state persistence, barrier bootstrapping, and status queries.
+ *
+ * Design rules:
+ *   - Coordinator state lives under <workspace>/.agentxchain/multirepo/
+ *   - Repo-local .agentxchain/ directories are NEVER mutated by coordinator code
+ *   - Init is atomic: if any required repo fails, no coordinator state is written
+ *   - Uses loadCoordinatorConfig() as the sole config entry point (DEC-MR-IMPL-006)
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { safeWriteJson } from './safe-write.js';
+import { loadCoordinatorConfig } from './coordinator-config.js';
+import { initializeGovernedRun } from './governed-state.js';
+
+// ── Paths ───────────────────────────────────────────────────────────────────
+
+const MULTIREPO_DIR = '.agentxchain/multirepo';
+const STATE_FILE = 'state.json';
+const HISTORY_FILE = 'history.jsonl';
+const LEDGER_FILE = 'decision-ledger.jsonl';
+const BARRIERS_FILE = 'barriers.json';
+const BARRIER_LEDGER_FILE = 'barrier-ledger.jsonl';
+
+function multiDir(workspacePath) {
+  return join(workspacePath, MULTIREPO_DIR);
+}
+
+function statePath(workspacePath) {
+  return join(multiDir(workspacePath), STATE_FILE);
+}
+
+function historyPath(workspacePath) {
+  return join(multiDir(workspacePath), HISTORY_FILE);
+}
+
+function ledgerPath(workspacePath) {
+  return join(multiDir(workspacePath), LEDGER_FILE);
+}
+
+function barriersPath(workspacePath) {
+  return join(multiDir(workspacePath), BARRIERS_FILE);
+}
+
+function barrierLedgerPath(workspacePath) {
+  return join(multiDir(workspacePath), BARRIER_LEDGER_FILE);
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function generateSuperRunId() {
+  const ts = Date.now();
+  const rand = randomBytes(4).toString('hex');
+  return `srun_${ts}_${rand}`;
+}
+
+function appendJsonl(filePath, entry) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(entry) + '\n', { flag: 'a' });
+}
+
+function readRepoLocalState(repoPath) {
+  const stateFile = join(repoPath, '.agentxchain/state.json');
+  if (!existsSync(stateFile)) return null;
+  try {
+    return JSON.parse(readFileSync(stateFile, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readRepoLocalConfig(repoPath) {
+  const configFile = join(repoPath, 'agentxchain.json');
+  if (!existsSync(configFile)) return null;
+  try {
+    return JSON.parse(readFileSync(configFile, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ── Barrier bootstrapping ───────────────────────────────────────────────────
+
+function bootstrapBarriers(config) {
+  const barriers = {};
+
+  for (const [workstreamId, workstream] of Object.entries(config.workstreams)) {
+    const barrierId = `${workstreamId}_completion`;
+    barriers[barrierId] = {
+      workstream_id: workstreamId,
+      type: workstream.completion_barrier,
+      status: 'pending',
+      required_repos: [...workstream.repos],
+      satisfied_repos: [],
+      created_at: new Date().toISOString(),
+    };
+  }
+
+  return barriers;
+}
+
+// ── Core API ────────────────────────────────────────────────────────────────
+
+/**
+ * Initialize a multi-repo coordinator run.
+ *
+ * 1. Validates config via loadCoordinatorConfig().
+ * 2. For each repo: links existing active run or initializes a new one.
+ * 3. Writes all coordinator state files atomically.
+ * 4. If any required repo fails, no coordinator state is written.
+ *
+ * @param {string} workspacePath - path to the coordinator workspace
+ * @param {object} [preloadedConfig] - optional pre-loaded config (skips loadCoordinatorConfig)
+ * @returns {{ ok: boolean, super_run_id?: string, repo_runs?: object, errors?: string[] }}
+ */
+export function initializeCoordinatorRun(workspacePath, preloadedConfig) {
+  // Step 1: Load and validate config
+  let config;
+  if (preloadedConfig) {
+    config = preloadedConfig;
+  } else {
+    const configResult = loadCoordinatorConfig(workspacePath);
+    if (!configResult.ok) {
+      return { ok: false, errors: configResult.errors };
+    }
+    config = configResult.config;
+  }
+
+  // Step 2: Link or initialize repo-local runs
+  const repoRuns = {};
+  const errors = [];
+
+  for (const repoId of config.repo_order) {
+    const repo = config.repos[repoId];
+    const repoPath = repo.resolved_path;
+
+    const repoState = readRepoLocalState(repoPath);
+
+    if (repoState && repoState.run_id && repoState.status === 'active') {
+      // Link existing active run
+      repoRuns[repoId] = {
+        run_id: repoState.run_id,
+        status: 'linked',
+        phase: repoState.phase ?? 'implementation',
+        initialized_by_coordinator: false,
+      };
+    } else if (repoState && (repoState.status === 'idle' || repoState.status === 'paused' ||
+      (repoState.status === 'blocked' && !repoState.run_id))) {
+      // Initialize a new run
+      const repoConfig = readRepoLocalConfig(repoPath);
+      if (!repoConfig) {
+        errors.push(`repo_init_failed: repo "${repoId}" config could not be read`);
+        continue;
+      }
+
+      const initResult = initializeGovernedRun(repoPath, repoConfig);
+      if (!initResult.ok) {
+        errors.push(`repo_init_failed: repo "${repoId}" initialization failed: ${initResult.error}`);
+        continue;
+      }
+
+      repoRuns[repoId] = {
+        run_id: initResult.state.run_id,
+        status: 'initialized',
+        phase: initResult.state.phase ?? 'implementation',
+        initialized_by_coordinator: true,
+      };
+    } else if (repoState && repoState.status === 'completed') {
+      errors.push(`repo_completed: repo "${repoId}" has a completed run. Reset or start a new project before coordinator init.`);
+      continue;
+    } else if (repoState && repoState.status === 'blocked' && repoState.run_id) {
+      errors.push(`repo_blocked: repo "${repoId}" is blocked with an active run. Resolve the blocked state before coordinator init.`);
+      continue;
+    } else {
+      errors.push(`repo_no_state: repo "${repoId}" has no governed state`);
+      continue;
+    }
+  }
+
+  // Check if all required repos succeeded
+  const requiredRepos = config.repo_order.filter(id => config.repos[id].required);
+  const failedRequired = requiredRepos.filter(id => !repoRuns[id]);
+  if (failedRequired.length > 0) {
+    return {
+      ok: false,
+      errors: [
+        ...errors,
+        `atomic_failure: required repos failed: ${failedRequired.join(', ')}. No coordinator state written.`,
+      ],
+    };
+  }
+
+  // Step 3: Generate coordinator state
+  const superRunId = generateSuperRunId();
+  const now = new Date().toISOString();
+  const barriers = bootstrapBarriers(config);
+
+  const state = {
+    schema_version: '0.1',
+    super_run_id: superRunId,
+    project_id: config.project.id,
+    status: 'active',
+    phase: config.workstream_order.length > 0
+      ? config.workstreams[config.workstream_order[0]].phase
+      : 'implementation',
+    repo_runs: repoRuns,
+    pending_gate: null,
+    phase_gate_status: {},
+    created_at: now,
+    updated_at: now,
+  };
+
+  // Step 4: Atomic write — create directory and all files
+  const dir = multiDir(workspacePath);
+  try {
+    mkdirSync(dir, { recursive: true });
+
+    // Write state
+    safeWriteJson(statePath(workspacePath), state);
+
+    // Write barriers
+    safeWriteJson(barriersPath(workspacePath), barriers);
+
+    // Create empty JSONL files
+    const emptyFiles = [
+      historyPath(workspacePath),
+      ledgerPath(workspacePath),
+      barrierLedgerPath(workspacePath),
+    ];
+    for (const filePath of emptyFiles) {
+      if (!existsSync(filePath)) {
+        writeFileSync(filePath, '', { flag: 'w' });
+      }
+    }
+
+    // Append run_initialized to history
+    appendJsonl(historyPath(workspacePath), {
+      type: 'run_initialized',
+      super_run_id: superRunId,
+      project_id: config.project.id,
+      repo_runs: Object.fromEntries(
+        Object.entries(repoRuns).map(([id, run]) => [id, {
+          run_id: run.run_id,
+          initialized_by_coordinator: run.initialized_by_coordinator,
+        }]),
+      ),
+      timestamp: now,
+    });
+  } catch (err) {
+    // Atomic failure: clean up partial state
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch { /* best effort cleanup */ }
+    return {
+      ok: false,
+      errors: [...errors, `write_failed: ${err.message}`],
+    };
+  }
+
+  return {
+    ok: true,
+    super_run_id: superRunId,
+    repo_runs: repoRuns,
+    errors: errors.length > 0 ? errors : undefined,
+  };
+}
+
+/**
+ * Load coordinator state from disk.
+ *
+ * @param {string} workspacePath
+ * @returns {object|null} - parsed state or null if not found
+ */
+export function loadCoordinatorState(workspacePath) {
+  const file = statePath(workspacePath);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save coordinator state to disk.
+ *
+ * @param {string} workspacePath
+ * @param {object} state
+ */
+export function saveCoordinatorState(workspacePath, state) {
+  const updated = { ...state, updated_at: new Date().toISOString() };
+  safeWriteJson(statePath(workspacePath), updated);
+}
+
+/**
+ * Get a full coordinator status snapshot.
+ *
+ * @param {string} workspacePath
+ * @returns {{ super_run_id, status, phase, repo_runs, pending_barriers, pending_gate }|null}
+ */
+export function getCoordinatorStatus(workspacePath) {
+  const state = loadCoordinatorState(workspacePath);
+  if (!state) return null;
+
+  // Read barriers
+  let barriers = {};
+  const barriersFile = barriersPath(workspacePath);
+  if (existsSync(barriersFile)) {
+    try {
+      barriers = JSON.parse(readFileSync(barriersFile, 'utf8'));
+    } catch { /* empty or corrupt — treat as empty */ }
+  }
+
+  const pendingBarriers = Object.entries(barriers)
+    .filter(([, b]) => b.status === 'pending' || b.status === 'partially_satisfied')
+    .map(([id, b]) => ({ id, ...b }));
+
+  return {
+    super_run_id: state.super_run_id,
+    status: state.status,
+    phase: state.phase,
+    repo_runs: state.repo_runs,
+    pending_barriers: pendingBarriers,
+    pending_gate: state.pending_gate ?? null,
+  };
+}
+
+/**
+ * Read coordinator history entries.
+ *
+ * @param {string} workspacePath
+ * @returns {object[]}
+ */
+export function readCoordinatorHistory(workspacePath) {
+  const file = historyPath(workspacePath);
+  if (!existsSync(file)) return [];
+  try {
+    const content = readFileSync(file, 'utf8').trim();
+    if (!content) return [];
+    return content.split('\n').map(line => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read coordinator barriers snapshot.
+ *
+ * @param {string} workspacePath
+ * @returns {object}
+ */
+export function readBarriers(workspacePath) {
+  const file = barriersPath(workspacePath);
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+}

package/src/lib/cross-repo-context.js

@@ -0,0 +1,247 @@
+import { mkdirSync, writeFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { readCoordinatorHistory, readBarriers } from './coordinator-state.js';
+
+const CONTEXT_ROOT = '.agentxchain/multirepo/context';
+
+function buildContextRef(workstreamId, targetRepoId) {
+  return `ctx_${workstreamId}_${targetRepoId}_${randomBytes(4).toString('hex')}`;
+}
+
+function getContextDir(workspacePath, contextRef) {
+  return join(workspacePath, CONTEXT_ROOT, contextRef);
+}
+
+function isProjectionEntry(entry) {
+  return entry && typeof entry === 'object' && entry.type === 'acceptance_projection';
+}
+
+function collectUpstreamAcceptances(history, targetRepoId, relevantWorkstreamIds) {
+  const relevantIds = new Set(relevantWorkstreamIds);
+  return history
+    .filter(isProjectionEntry)
+    .filter((entry) => relevantIds.has(entry.workstream_id))
+    .filter((entry) => entry.repo_id !== targetRepoId)
+    .map((entry) => ({
+      projection_ref: entry.projection_ref || null,
+      workstream_id: entry.workstream_id,
+      repo_id: entry.repo_id,
+      repo_turn_id: entry.repo_turn_id || null,
+      summary: entry.summary || '',
+      decisions: Array.isArray(entry.decisions) ? entry.decisions : [],
+      files_changed: Array.isArray(entry.files_changed) ? entry.files_changed : [],
+      verification: entry.verification || null,
+    }));
+}
+
+function collectActiveBarriers(barriers, workstreamIds, targetRepoId) {
+  const relevantIds = new Set(workstreamIds);
+  return Object.entries(barriers)
+    .filter(([, barrier]) => barrier && typeof barrier === 'object')
+    .filter(([, barrier]) => barrier.type !== 'all_repos_accepted')
+    .filter(([, barrier]) => relevantIds.has(barrier.workstream_id))
+    .filter(([, barrier]) => barrier.status && barrier.status !== 'satisfied')
+    .filter(([, barrier]) => {
+      if (Array.isArray(barrier.downstream_repos) && barrier.downstream_repos.includes(targetRepoId)) {
+        return true;
+      }
+      if (Array.isArray(barrier.required_repos) && barrier.required_repos.includes(targetRepoId)) {
+        return true;
+      }
+      if (Array.isArray(barrier.blocked_assignments)) {
+        return barrier.blocked_assignments.some((assignment) => assignment === targetRepoId || assignment.startsWith(`${targetRepoId}:`));
+      }
+      return barrier.workstream_id === workstreamIds[0];
+    })
+    .map(([barrierId, barrier]) => ({
+      barrier_id: barrier.barrier_id || barrierId,
+      workstream_id: barrier.workstream_id,
+      type: barrier.type || 'unknown',
+      status: barrier.status,
+      notes: barrier.notes || null,
+    }));
+}
+
+function buildRequiredFollowups(workstreamId, dependencyIds, upstreamAcceptances, activeBarriers, targetRepoId) {
+  const followups = [];
+
+  for (const dependencyId of dependencyIds) {
+    followups.push(`Incorporate accepted output from dependency "${dependencyId}" before changing ${targetRepoId}.`);
+  }
+
+  for (const acceptance of upstreamAcceptances) {
+    followups.push(`Review ${acceptance.repo_id} acceptance${acceptance.summary ? `: ${acceptance.summary}` : ''}`.trim());
+  }
+
+  for (const barrier of activeBarriers) {
+    if (barrier.notes) {
+      followups.push(barrier.notes);
+    } else {
+      followups.push(`Respect barrier "${barrier.barrier_id}" (${barrier.type}) before proceeding.`);
+    }
+  }
+
+  return [...new Set(followups)];
+}
+
+function renderContextMarkdown(snapshot) {
+  const lines = [
+    '# Coordinator Context',
+    '',
+    `- Super Run: ${snapshot.super_run_id}`,
+    `- Workstream: ${snapshot.workstream_id}`,
+    `- Target Repo: ${snapshot.target_repo_id}`,
+    `- Context Ref: ${snapshot.context_ref}`,
+    `- Generated At: ${snapshot.generated_at}`,
+    '',
+    '## Upstream Acceptances',
+    '',
+  ];
+
+  if (snapshot.upstream_acceptances.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const acceptance of snapshot.upstream_acceptances) {
+      const decisionText = acceptance.decisions.length > 0 ? ` Decisions: ${acceptance.decisions.join(', ')}.` : '';
+      lines.push(`- ${acceptance.repo_id} (${acceptance.workstream_id}): ${acceptance.summary || 'No summary recorded.'}${decisionText}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('## Active Barriers');
+  lines.push('');
+
+  if (snapshot.active_barriers.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const barrier of snapshot.active_barriers) {
+      lines.push(`- ${barrier.barrier_id}: ${barrier.type} (${barrier.status})`);
+    }
+  }
+
+  lines.push('');
+  lines.push('## Required Follow-ups');
+  lines.push('');
+
+  if (snapshot.required_followups.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const followup of snapshot.required_followups) {
+      lines.push(`- ${followup}`);
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Compute which repos have stale cross-repo context after a turn is accepted in sourceRepoId.
+ *
+ * Returns an array of invalidation signals:
+ *   { target_repo_id, context_ref, workstream_id, reason }
+ *
+ * A context is invalidated when:
+ *   1. It was generated for a target repo (not the source)
+ *   2. It included upstream acceptances from the source repo
+ *   3. The source repo has since accepted a new turn (the files_changed may affect
+ *      decisions/context the target repo relied on)
+ *
+ * This is informational — the coordinator regenerates context on next dispatch anyway.
+ * The signal is for external consumers (notification pipelines, compliance validators).
+ */
+export function computeContextInvalidations(workspacePath, sourceRepoId, workstreamId, filesChanged) {
+  const history = readCoordinatorHistory(workspacePath);
+
+  // Find all context-generation events that included upstream acceptances from sourceRepoId
+  const contextEvents = history.filter(
+    (e) => e?.type === 'context_generated' && e.target_repo_id !== sourceRepoId
+  );
+
+  const invalidations = [];
+
+  for (const ctx of contextEvents) {
+    // Check if this context included projections from the source repo
+    const includedSourceProjections = (ctx.upstream_repo_ids || []).includes(sourceRepoId);
+    const sameWorkstream = ctx.workstream_id === workstreamId ||
+      (Array.isArray(ctx.relevant_workstream_ids) && ctx.relevant_workstream_ids.includes(workstreamId));
+
+    if (includedSourceProjections || sameWorkstream) {
+      invalidations.push({
+        target_repo_id: ctx.target_repo_id,
+        context_ref: ctx.context_ref,
+        workstream_id: ctx.workstream_id,
+        source_repo_id: sourceRepoId,
+        files_changed: Array.isArray(filesChanged) ? filesChanged : [],
+        reason: includedSourceProjections
+          ? `Context ${ctx.context_ref} included projections from ${sourceRepoId} which has a new accepted turn`
+          : `Context ${ctx.context_ref} shares workstream "${workstreamId}" with newly accepted turn in ${sourceRepoId}`,
+      });
+    }
+  }
+
+  return invalidations;
+}
+
+export function generateCrossRepoContext(workspacePath, state, config, targetRepoId, workstreamId) {
+  const workstream = config.workstreams?.[workstreamId];
+  if (!workstream) {
+    return { ok: false, error: `Unknown workstream "${workstreamId}"` };
+  }
+
+  const contextRef = buildContextRef(workstreamId, targetRepoId);
+  const generatedAt = new Date().toISOString();
+  const history = readCoordinatorHistory(workspacePath);
+  const barriers = readBarriers(workspacePath);
+  const relevantWorkstreamIds = [workstreamId, ...(Array.isArray(workstream.depends_on) ? workstream.depends_on : [])];
+  const upstreamAcceptances = collectUpstreamAcceptances(history, targetRepoId, relevantWorkstreamIds);
+  const activeBarriers = collectActiveBarriers(barriers, relevantWorkstreamIds, targetRepoId);
+  const snapshot = {
+    schema_version: '0.1',
+    super_run_id: state.super_run_id,
+    workstream_id: workstreamId,
+    target_repo_id: targetRepoId,
+    context_ref: contextRef,
+    generated_at: generatedAt,
+    upstream_acceptances: upstreamAcceptances,
+    active_barriers: activeBarriers,
+    required_followups: buildRequiredFollowups(
+      workstreamId,
+      Array.isArray(workstream.depends_on) ? workstream.depends_on : [],
+      upstreamAcceptances,
+      activeBarriers,
+      targetRepoId,
+    ),
+  };
+
+  const contextDir = getContextDir(workspacePath, contextRef);
+  const jsonPath = join(contextDir, 'COORDINATOR_CONTEXT.json');
+  const mdPath = join(contextDir, 'COORDINATOR_CONTEXT.md');
+
+  mkdirSync(contextDir, { recursive: true });
+  writeFileSync(jsonPath, JSON.stringify(snapshot, null, 2) + '\n');
+  writeFileSync(mdPath, renderContextMarkdown(snapshot));
+
+  // Record context-generation event in coordinator history for invalidation tracking
+  const historyFile = join(workspacePath, '.agentxchain/multirepo/history.jsonl');
+  const contextEvent = {
+    type: 'context_generated',
+    timestamp: generatedAt,
+    super_run_id: state.super_run_id,
+    context_ref: contextRef,
+    workstream_id: workstreamId,
+    target_repo_id: targetRepoId,
+    relevant_workstream_ids: relevantWorkstreamIds,
+    upstream_repo_ids: [...new Set(upstreamAcceptances.map((a) => a.repo_id))],
+  };
+  appendFileSync(historyFile, JSON.stringify(contextEvent) + '\n');
+
+  return {
+    ok: true,
+    contextRef,
+    jsonPath,
+    mdPath,
+    snapshot,
+  };
+}