agentxchain 0.8.8 → 2.1.1

package/src/lib/dispatch-manifest.js

@@ -0,0 +1,252 @@
+/**
+ * Dispatch manifest integrity — content-addressed bundle verification.
+ *
+ * Implements V2.1-F1: each finalized dispatch bundle gets a MANIFEST.json
+ * containing SHA-256 digests and byte sizes for every file in the bundle.
+ * Adapters verify the manifest before consuming bundle files.
+ *
+ * Timing:
+ *   writeDispatchBundle()  → core files written
+ *   after_dispatch hooks   → supplements added
+ *   finalizeDispatchManifest() → MANIFEST.json sealed
+ *   verifyDispatchManifest()   → adapter checks before execution
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, readdirSync, readFileSync, writeFileSync, statSync } from 'fs';
+import { join, relative } from 'path';
+import { getDispatchTurnDir, getDispatchManifestPath } from './turn-paths.js';
+
+const MANIFEST_VERSION = '1.0';
+const MANIFEST_FILENAME = 'MANIFEST.json';
+
+/**
+ * Finalize a dispatch bundle by writing MANIFEST.json with content-addressed entries.
+ *
+ * Must be called AFTER writeDispatchBundle() and after_dispatch hooks have completed.
+ *
+ * @param {string} root - project root directory
+ * @param {string} turnId - turn identifier
+ * @param {{ run_id: string, role: string }} identity - turn identity for manifest metadata
+ * @returns {{ ok: boolean, manifestPath?: string, fileCount?: number, error?: string }}
+ */
+export function finalizeDispatchManifest(root, turnId, identity) {
+  const bundleDir = join(root, getDispatchTurnDir(turnId));
+
+  if (!existsSync(bundleDir)) {
+    return { ok: false, error: 'Bundle directory does not exist' };
+  }
+
+  const entries = scanBundleFiles(bundleDir);
+  if (entries.length === 0) {
+    return { ok: false, error: 'Bundle directory is empty — no files to manifest' };
+  }
+
+  const manifest = {
+    manifest_version: MANIFEST_VERSION,
+    run_id: identity.run_id,
+    turn_id: turnId,
+    role: identity.role,
+    finalized_at: new Date().toISOString(),
+    files: entries,
+  };
+
+  const manifestPath = join(root, getDispatchManifestPath(turnId));
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+
+  return { ok: true, manifestPath, fileCount: entries.length };
+}
+
+/**
+ * Return whether a finalized manifest exists for the dispatch bundle.
+ *
+ * @param {string} root
+ * @param {string} turnId
+ * @returns {boolean}
+ */
+export function hasDispatchManifest(root, turnId) {
+  return existsSync(join(root, getDispatchManifestPath(turnId)));
+}
+
+/**
+ * Verify a dispatch bundle against its MANIFEST.json.
+ *
+ * @param {string} root - project root directory
+ * @param {string} turnId - turn identifier
+ * @returns {{ ok: boolean, errors?: Array<{ type: string, path?: string, detail: string }>, manifest?: object }}
+ */
+export function verifyDispatchManifest(root, turnId) {
+  const bundleDir = join(root, getDispatchTurnDir(turnId));
+  const manifestPath = join(root, getDispatchManifestPath(turnId));
+
+  // Check manifest exists
+  if (!existsSync(manifestPath)) {
+    return {
+      ok: false,
+      errors: [{ type: 'missing_manifest', detail: 'MANIFEST.json does not exist in bundle directory' }],
+    };
+  }
+
+  // Parse manifest
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [{ type: 'invalid_manifest', detail: `MANIFEST.json is malformed: ${err.message}` }],
+    };
+  }
+
+  // Validate schema
+  if (!manifest.manifest_version || !Array.isArray(manifest.files)) {
+    return {
+      ok: false,
+      errors: [{ type: 'invalid_manifest', detail: 'MANIFEST.json missing required fields (manifest_version, files)' }],
+    };
+  }
+
+  const errors = [];
+
+  // Check each declared file
+  for (const entry of manifest.files) {
+    const filePath = join(bundleDir, entry.path);
+
+    if (!existsSync(filePath)) {
+      errors.push({ type: 'missing_file', path: entry.path, detail: `Declared file "${entry.path}" is missing from bundle` });
+      continue;
+    }
+
+    const content = readFileSync(filePath);
+    const actualSize = content.length;
+    const actualDigest = createHash('sha256').update(content).digest('hex');
+
+    if (actualSize !== entry.size) {
+      errors.push({
+        type: 'size_mismatch',
+        path: entry.path,
+        detail: `"${entry.path}" size mismatch: manifest=${entry.size}, actual=${actualSize}`,
+      });
+    }
+
+    if (actualDigest !== entry.sha256) {
+      errors.push({
+        type: 'digest_mismatch',
+        path: entry.path,
+        detail: `"${entry.path}" SHA-256 mismatch: manifest=${entry.sha256}, actual=${actualDigest}`,
+      });
+    }
+  }
+
+  // Check for unexpected files
+  const declaredPaths = new Set(manifest.files.map((f) => f.path));
+  const actualFiles = scanFilenames(bundleDir);
+  for (const actual of actualFiles) {
+    if (!declaredPaths.has(actual)) {
+      errors.push({
+        type: 'unexpected_file',
+        path: actual,
+        detail: `Unexpected file "${actual}" not declared in manifest`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors, manifest };
+  }
+
+  return { ok: true, manifest };
+}
+
+/**
+ * Verify dispatch bundle integrity according to adapter consumption policy.
+ *
+ * Policy:
+ * - default: verify automatically when MANIFEST.json exists
+ * - verifyManifest: true → manifest is required and verified
+ * - skipManifestVerification: true → explicit escape hatch; skip entirely
+ *
+ * @param {string} root
+ * @param {string} turnId
+ * @param {{ verifyManifest?: boolean, skipManifestVerification?: boolean }} [options]
+ * @returns {{ ok: boolean, skipped?: boolean, manifestPresent?: boolean, error?: string, manifest?: object, errors?: Array<{ type: string, path?: string, detail: string }> }}
+ */
+export function verifyDispatchManifestForAdapter(root, turnId, options = {}) {
+  const requireManifest = options.verifyManifest === true;
+  const skipManifestVerification = options.skipManifestVerification === true;
+
+  if (skipManifestVerification) {
+    return { ok: true, skipped: true, manifestPresent: hasDispatchManifest(root, turnId) };
+  }
+
+  const manifestPresent = hasDispatchManifest(root, turnId);
+  if (!manifestPresent && !requireManifest) {
+    return { ok: true, skipped: true, manifestPresent: false };
+  }
+
+  const manifestCheck = verifyDispatchManifest(root, turnId);
+  if (!manifestCheck.ok) {
+    return {
+      ok: false,
+      manifestPresent,
+      errors: manifestCheck.errors,
+      error: formatDispatchManifestErrors(manifestCheck.errors),
+    };
+  }
+
+  return {
+    ok: true,
+    manifestPresent,
+    manifest: manifestCheck.manifest,
+  };
+}
+
+/**
+ * Format structured manifest errors for CLI/operator display.
+ *
+ * @param {Array<{ type: string, detail: string }>} errors
+ * @returns {string}
+ */
+export function formatDispatchManifestErrors(errors = []) {
+  return errors.map((entry) => `${entry.type}: ${entry.detail}`).join('; ');
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Scan a bundle directory and return manifest file entries.
+ * Excludes MANIFEST.json itself.
+ */
+function scanBundleFiles(bundleDir) {
+  const entries = [];
+  const files = readdirSync(bundleDir);
+
+  for (const filename of files) {
+    if (filename === MANIFEST_FILENAME) continue;
+
+    const filePath = join(bundleDir, filename);
+    const stat = statSync(filePath);
+    if (!stat.isFile()) continue;
+
+    const content = readFileSync(filePath);
+    const digest = createHash('sha256').update(content).digest('hex');
+
+    entries.push({
+      path: filename,
+      sha256: digest,
+      size: content.length,
+    });
+  }
+
+  // Sort for deterministic manifest output
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+  return entries;
+}
+
+/**
+ * Get all filenames in a bundle directory, excluding MANIFEST.json.
+ */
+function scanFilenames(bundleDir) {
+  return readdirSync(bundleDir)
+    .filter((f) => f !== MANIFEST_FILENAME && statSync(join(bundleDir, f)).isFile());
+}

package/src/lib/gate-evaluator.js

@@ -0,0 +1,285 @@
+/**
+ * Gate evaluator — pure library for phase exit gate evaluation.
+ *
+ * Implements the frozen spec (§40-§43):
+ *
+ *   - evaluatePhaseExit() is a pure function: (state, config, acceptedTurn, root) → GateResult
+ *   - Phase advancement happens only on accepted turns
+ *   - phase_transition_request must be explicitly present in the turn result
+ *   - Human-approval gates pause the run instead of auto-advancing
+ *
+ * Rules from §43:
+ *   Rule 1: No phase_transition_request → stay in current phase
+ *   Rule 2: Unknown target phase → gate_error
+ *   Rule 3: Request present but gate fails → accept turn, stay in phase
+ *   Rule 4: Request present + gate passes (no human approval) → advance immediately
+ *   Rule 5: Request present + gate passes + requires_human_approval → pause with pending_phase_transition
+ *   Rule 6: Acceptance never auto-assigns the next turn
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Evaluate whether the current phase exit gate is satisfied.
+ *
+ * @param {object} params
+ * @param {object} params.state - current run state (post-acceptance)
+ * @param {object} params.config - normalized config
+ * @param {object} params.acceptedTurn - the accepted turn result
+ * @param {string} params.root - project root directory
+ * @returns {GateResult}
+ *
+ * @typedef {object} GateResult
+ * @property {string|null} gate_id - the gate that was evaluated, or null if no gate
+ * @property {boolean} passed - whether all predicates passed
+ * @property {boolean} blocked_by_human_approval - gate passed structurally but needs human sign-off
+ * @property {string[]} reasons - human-readable failure reasons
+ * @property {string[]} missing_files - files required by gate but not found
+ * @property {boolean} missing_verification - verification required but not passed
+ * @property {string|null} next_phase - the target phase if transition was requested and gate passed
+ * @property {string|null} transition_request - the raw phase_transition_request value
+ * @property {'no_request'|'unknown_phase'|'gate_failed'|'advance'|'awaiting_human_approval'|'no_gate'} action
+ */
+export function evaluatePhaseExit({ state, config, acceptedTurn, root }) {
+  const currentPhase = state.phase;
+  const transitionRequest = acceptedTurn.phase_transition_request || null;
+
+  const baseResult = {
+    gate_id: null,
+    passed: false,
+    blocked_by_human_approval: false,
+    reasons: [],
+    missing_files: [],
+    missing_verification: false,
+    next_phase: null,
+    transition_request: transitionRequest,
+    action: 'no_request',
+  };
+
+  // Rule 1: No phase_transition_request → stay in current phase
+  if (!transitionRequest) {
+    return { ...baseResult, action: 'no_request' };
+  }
+
+  // Rule 2: Unknown target phase → error
+  const routing = config.routing || {};
+  if (!routing[transitionRequest]) {
+    return {
+      ...baseResult,
+      action: 'unknown_phase',
+      reasons: [`Requested phase "${transitionRequest}" does not exist in routing config`],
+    };
+  }
+
+  // Find the exit gate for the current phase
+  const currentRouting = routing[currentPhase];
+  if (!currentRouting || !currentRouting.exit_gate) {
+    // No gate defined for current phase → auto-advance
+    return {
+      ...baseResult,
+      passed: true,
+      next_phase: transitionRequest,
+      action: 'advance',
+    };
+  }
+
+  const gateId = currentRouting.exit_gate;
+  const gateDef = (config.gates || {})[gateId];
+
+  if (!gateDef) {
+    // Gate referenced but not defined → treat as no gate (advance)
+    return {
+      ...baseResult,
+      gate_id: gateId,
+      passed: true,
+      next_phase: transitionRequest,
+      action: 'advance',
+      reasons: [`Gate "${gateId}" referenced by routing but not defined in gates config — treated as open`],
+    };
+  }
+
+  // Evaluate gate predicates
+  const result = {
+    ...baseResult,
+    gate_id: gateId,
+  };
+
+  const failures = [];
+
+  // Predicate: requires_files
+  if (gateDef.requires_files && Array.isArray(gateDef.requires_files)) {
+    for (const filePath of gateDef.requires_files) {
+      if (!existsSync(join(root, filePath))) {
+        result.missing_files.push(filePath);
+        failures.push(`Required file missing: ${filePath}`);
+      }
+    }
+  }
+
+  // Predicate: requires_verification_pass
+  if (gateDef.requires_verification_pass) {
+    const verificationStatus = acceptedTurn.verification?.status;
+    if (verificationStatus !== 'pass' && verificationStatus !== 'attested_pass') {
+      result.missing_verification = true;
+      failures.push(`Verification status is "${verificationStatus || 'missing'}", requires "pass" or "attested_pass"`);
+    }
+  }
+
+  if (failures.length > 0) {
+    // Rule 3: Gate fails → accept turn but stay in phase
+    result.passed = false;
+    result.reasons = failures;
+    result.action = 'gate_failed';
+    return result;
+  }
+
+  // All structural predicates passed
+  result.passed = true;
+  result.next_phase = transitionRequest;
+
+  // Rule 5: requires_human_approval → pause instead of advancing
+  if (gateDef.requires_human_approval) {
+    result.blocked_by_human_approval = true;
+    result.action = 'awaiting_human_approval';
+    return result;
+  }
+
+  // Rule 4: Gate passes, no human approval needed → advance
+  result.action = 'advance';
+  return result;
+}
+
+/**
+ * Evaluate whether a run should complete (terminal state).
+ *
+ * Called when a turn result contains `run_completion_request: true` in the
+ * final phase. Uses the same gate predicate system as phase transitions.
+ *
+ * @param {object} params
+ * @param {object} params.state - current run state (post-acceptance)
+ * @param {object} params.config - normalized config
+ * @param {object} params.acceptedTurn - the accepted turn result
+ * @param {string} params.root - project root directory
+ * @returns {RunCompletionResult}
+ *
+ * @typedef {object} RunCompletionResult
+ * @property {string|null} gate_id - the gate evaluated, or null
+ * @property {boolean} passed - whether all predicates passed
+ * @property {boolean} blocked_by_human_approval - gate passed structurally but needs human sign-off
+ * @property {string[]} reasons - human-readable failure reasons
+ * @property {string[]} missing_files - files required by gate but not found
+ * @property {boolean} missing_verification - verification required but not passed
+ * @property {'no_request'|'not_final_phase'|'gate_failed'|'complete'|'awaiting_human_approval'} action
+ */
+export function evaluateRunCompletion({ state, config, acceptedTurn, root }) {
+  const baseResult = {
+    gate_id: null,
+    passed: false,
+    blocked_by_human_approval: false,
+    reasons: [],
+    missing_files: [],
+    missing_verification: false,
+    action: 'no_request',
+  };
+
+  // Must have explicit run_completion_request
+  if (!acceptedTurn.run_completion_request) {
+    return { ...baseResult, action: 'no_request' };
+  }
+
+  // Must be in the final phase
+  const phases = getPhaseOrder(config.routing || {});
+  const currentPhase = state.phase;
+  if (phases.length > 0 && phases[phases.length - 1] !== currentPhase) {
+    return {
+      ...baseResult,
+      action: 'not_final_phase',
+      reasons: [`Run completion requested but current phase "${currentPhase}" is not the final phase "${phases[phases.length - 1]}"`],
+    };
+  }
+
+  // Find the exit gate for the current (final) phase
+  const currentRouting = (config.routing || {})[currentPhase];
+  if (!currentRouting || !currentRouting.exit_gate) {
+    // No gate → auto-complete
+    return { ...baseResult, passed: true, action: 'complete' };
+  }
+
+  const gateId = currentRouting.exit_gate;
+  const gateDef = (config.gates || {})[gateId];
+
+  if (!gateDef) {
+    // Gate referenced but not defined → complete
+    return {
+      ...baseResult,
+      gate_id: gateId,
+      passed: true,
+      action: 'complete',
+      reasons: [`Gate "${gateId}" referenced but not defined — treated as open`],
+    };
+  }
+
+  // Evaluate gate predicates (same logic as phase exit)
+  const result = { ...baseResult, gate_id: gateId };
+  const failures = [];
+
+  if (gateDef.requires_files && Array.isArray(gateDef.requires_files)) {
+    for (const filePath of gateDef.requires_files) {
+      if (!existsSync(join(root, filePath))) {
+        result.missing_files.push(filePath);
+        failures.push(`Required file missing: ${filePath}`);
+      }
+    }
+  }
+
+  if (gateDef.requires_verification_pass) {
+    const verificationStatus = acceptedTurn.verification?.status;
+    if (verificationStatus !== 'pass' && verificationStatus !== 'attested_pass') {
+      result.missing_verification = true;
+      failures.push(`Verification status is "${verificationStatus || 'missing'}", requires "pass" or "attested_pass"`);
+    }
+  }
+
+  if (failures.length > 0) {
+    result.passed = false;
+    result.reasons = failures;
+    result.action = 'gate_failed';
+    return result;
+  }
+
+  // All structural predicates passed
+  result.passed = true;
+
+  if (gateDef.requires_human_approval) {
+    result.blocked_by_human_approval = true;
+    result.action = 'awaiting_human_approval';
+    return result;
+  }
+
+  result.action = 'complete';
+  return result;
+}
+
+/**
+ * Determine the phase ordering from routing config.
+ * Returns the list of phase names in declaration order.
+ *
+ * @param {object} routing - routing config object
+ * @returns {string[]}
+ */
+export function getPhaseOrder(routing) {
+  return Object.keys(routing || {});
+}
+
+/**
+ * Check if a phase is the final phase in the routing config.
+ *
+ * @param {string} phase - the phase to check
+ * @param {object} routing - routing config object
+ * @returns {boolean}
+ */
+export function isFinalPhase(phase, routing) {
+  const phases = getPhaseOrder(routing || {});
+  return phases.length > 0 && phases[phases.length - 1] === phase;
+}