agentxchain 2.45.0 → 2.46.2

package/src/lib/governed-templates.js

@@ -80,6 +80,7 @@ const VALID_SCAFFOLD_BLUEPRINT_KEYS = new Set([
   'runtimes',
   'routing',
   'gates',
+  'policies',
   'workflow_kit',
 ]);
 
@@ -106,6 +107,7 @@ function validateScaffoldBlueprint(scaffoldBlueprint, errors) {
     runtimes: scaffoldBlueprint.runtimes,
     routing: scaffoldBlueprint.routing,
     gates: scaffoldBlueprint.gates,
+    policies: scaffoldBlueprint.policies,
     workflow_kit: scaffoldBlueprint.workflow_kit,
   });
 

package/src/lib/normalized-config.js

@@ -14,6 +14,8 @@
 
 import { validateHooksConfig } from './hook-runner.js';
 import { validateNotificationsConfig } from './notification-runner.js';
+import { validatePolicies, normalizePolicies } from './policy-evaluator.js';
+import { validateTimeoutsConfig } from './timeout-evaluator.js';
 import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
 import {
   buildDefaultWorkflowKitArtifactsForPhase,
@@ -512,6 +514,23 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...wkValidation.errors);
   }
 
+  // Policies (optional but validated if present)
+  if (data.policies !== undefined) {
+    const policyValidation = validatePolicies(data.policies);
+    errors.push(...policyValidation.errors);
+  }
+
+  // Approval Policy (optional but validated if present)
+  if (data.approval_policy !== undefined) {
+    errors.push(...validateApprovalPolicy(data.approval_policy, data.routing));
+  }
+
+  // Timeouts (optional but validated if present)
+  if (data.timeouts !== undefined) {
+    const timeoutValidation = validateTimeoutsConfig(data.timeouts, data.routing);
+    errors.push(...timeoutValidation.errors);
+  }
+
   return { ok: errors.length === 0, errors };
 }
 
@@ -684,6 +703,113 @@ export function validateWorkflowKitConfig(wk, routing, roles) {
   return { ok: errors.length === 0, errors, warnings };
 }
 
+const VALID_APPROVAL_ACTIONS = ['auto_approve', 'require_human'];
+
+/**
+ * Validate the approval_policy config section.
+ * Returns an array of error strings.
+ */
+export function validateApprovalPolicy(ap, routing) {
+  const errors = [];
+  if (ap === null || ap === undefined) return errors;
+  if (typeof ap !== 'object' || Array.isArray(ap)) {
+    errors.push('approval_policy must be an object');
+    return errors;
+  }
+
+  const routingPhases = routing ? Object.keys(routing) : [];
+
+  // phase_transitions
+  if (ap.phase_transitions !== undefined) {
+    const pt = ap.phase_transitions;
+    if (typeof pt !== 'object' || Array.isArray(pt)) {
+      errors.push('approval_policy.phase_transitions must be an object');
+    } else {
+      if (pt.default !== undefined && !VALID_APPROVAL_ACTIONS.includes(pt.default)) {
+        errors.push(`approval_policy.phase_transitions.default must be one of: ${VALID_APPROVAL_ACTIONS.join(', ')}`);
+      }
+      if (pt.rules !== undefined) {
+        if (!Array.isArray(pt.rules)) {
+          errors.push('approval_policy.phase_transitions.rules must be an array');
+        } else {
+          for (let i = 0; i < pt.rules.length; i++) {
+            const rule = pt.rules[i];
+            const prefix = `approval_policy.phase_transitions.rules[${i}]`;
+            if (!rule || typeof rule !== 'object') {
+              errors.push(`${prefix} must be an object`);
+              continue;
+            }
+            if (!VALID_APPROVAL_ACTIONS.includes(rule.action)) {
+              errors.push(`${prefix}.action must be one of: ${VALID_APPROVAL_ACTIONS.join(', ')}`);
+            }
+            if (rule.from_phase !== undefined) {
+              if (typeof rule.from_phase !== 'string') {
+                errors.push(`${prefix}.from_phase must be a string`);
+              } else if (routingPhases.length > 0 && !routingPhases.includes(rule.from_phase)) {
+                errors.push(`${prefix}.from_phase "${rule.from_phase}" does not exist in routing`);
+              }
+            }
+            if (rule.to_phase !== undefined) {
+              if (typeof rule.to_phase !== 'string') {
+                errors.push(`${prefix}.to_phase must be a string`);
+              } else if (routingPhases.length > 0 && !routingPhases.includes(rule.to_phase)) {
+                errors.push(`${prefix}.to_phase "${rule.to_phase}" does not exist in routing`);
+              }
+            }
+            if (rule.when !== undefined) {
+              errors.push(...validateApprovalWhen(rule.when, prefix));
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // run_completion
+  if (ap.run_completion !== undefined) {
+    const rc = ap.run_completion;
+    if (typeof rc !== 'object' || Array.isArray(rc)) {
+      errors.push('approval_policy.run_completion must be an object');
+    } else {
+      if (rc.action !== undefined && !VALID_APPROVAL_ACTIONS.includes(rc.action)) {
+        errors.push(`approval_policy.run_completion.action must be one of: ${VALID_APPROVAL_ACTIONS.join(', ')}`);
+      }
+      if (rc.when !== undefined) {
+        errors.push(...validateApprovalWhen(rc.when, 'approval_policy.run_completion'));
+      }
+    }
+  }
+
+  return errors;
+}
+
+function validateApprovalWhen(when, prefix) {
+  const errors = [];
+  if (typeof when !== 'object' || Array.isArray(when) || when === null) {
+    errors.push(`${prefix}.when must be an object`);
+    return errors;
+  }
+  if (when.gate_passed !== undefined && typeof when.gate_passed !== 'boolean') {
+    errors.push(`${prefix}.when.gate_passed must be a boolean`);
+  }
+  if (when.roles_participated !== undefined) {
+    if (!Array.isArray(when.roles_participated)) {
+      errors.push(`${prefix}.when.roles_participated must be an array of role IDs`);
+    } else {
+      for (const r of when.roles_participated) {
+        if (typeof r !== 'string' || !r.trim()) {
+          errors.push(`${prefix}.when.roles_participated entries must be non-empty strings`);
+          break;
+        }
+      }
+    }
+  }
+  if (when.all_phases_visited !== undefined && typeof when.all_phases_visited !== 'boolean') {
+    errors.push(`${prefix}.when.all_phases_visited must be a boolean`);
+  }
+  return errors;
+}
+
 /**
  * Normalize a legacy v3 config into the internal shape.
  * Does NOT modify the original file — this is a read-time transformation.
@@ -725,6 +851,9 @@ export function normalizeV3(raw) {
     hooks: {},
     notifications: {},
     budget: null,
+    policies: [],
+    approval_policy: null,
+    timeouts: null,
     workflow_kit: normalizeWorkflowKit(undefined, DEFAULT_PHASES),
     retention: {
       talk_strategy: 'append_only',
@@ -789,6 +918,9 @@ export function normalizeV4(raw) {
     hooks: raw.hooks || {},
     notifications: raw.notifications || {},
     budget: raw.budget || null,
+    policies: normalizePolicies(raw.policies),
+    approval_policy: raw.approval_policy || null,
+    timeouts: raw.timeouts || null,
     workflow_kit: normalizeWorkflowKit(raw.workflow_kit, routingPhases),
     retention: raw.retention || {
       talk_strategy: 'append_only',

package/src/lib/policy-evaluator.js

@@ -0,0 +1,330 @@
+/**
+ * Policy evaluator — declarative governance rules for turn acceptance.
+ *
+ * Policies are config-driven rules that evaluate on every turn acceptance.
+ * Gates evaluate at phase boundaries. Hooks run external commands.
+ * Policies evaluate built-in governance rules on every accepted turn.
+ *
+ * Pure functions only — no I/O, no side effects.
+ */
+
+/**
+ * Registry of built-in rule evaluators.
+ * Each evaluator: (params, context) → { triggered: boolean, message: string }
+ */
+const RULE_EVALUATORS = {
+  max_turns_per_phase: (params, ctx) => {
+    const count = ctx.history.filter(
+      (entry) => entry.phase === ctx.currentPhase,
+    ).length;
+    if (count >= params.limit) {
+      return {
+        triggered: true,
+        message: `phase "${ctx.currentPhase}" has reached ${count}/${params.limit} accepted turns`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+
+  max_total_turns: (params, ctx) => {
+    const count = ctx.history.length;
+    if (count >= params.limit) {
+      return {
+        triggered: true,
+        message: `run has reached ${count}/${params.limit} total accepted turns`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+
+  max_consecutive_same_role: (params, ctx) => {
+    const role = ctx.turnRole;
+    let consecutive = 0;
+    for (let i = ctx.history.length - 1; i >= 0; i--) {
+      if (ctx.history[i].role === role) {
+        consecutive++;
+      } else {
+        break;
+      }
+    }
+    // The current turn (not yet in history) adds one more
+    consecutive += 1;
+    if (consecutive > params.limit) {
+      return {
+        triggered: true,
+        message: `role "${role}" has ${consecutive} consecutive turns (limit: ${params.limit})`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+
+  max_cost_per_turn: (params, ctx) => {
+    const cost = ctx.turnCostUsd;
+    if (cost != null && cost > params.limit_usd) {
+      return {
+        triggered: true,
+        message: `turn cost $${cost.toFixed(2)} exceeds limit $${params.limit_usd.toFixed(2)}`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+
+  require_status: (params, ctx) => {
+    if (!params.allowed.includes(ctx.turnStatus)) {
+      return {
+        triggered: true,
+        message: `status "${ctx.turnStatus}" is not in allowed set [${params.allowed.join(', ')}]`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+};
+
+export const VALID_POLICY_RULES = Object.keys(RULE_EVALUATORS);
+export const VALID_POLICY_ACTIONS = ['block', 'warn', 'escalate'];
+export const VALID_POLICY_TURN_STATUSES = [
+  'completed',
+  'blocked',
+  'needs_human',
+  'failed',
+];
+const VALID_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+
+/**
+ * Validate a single policy definition at config load time.
+ * Returns an array of error strings (empty if valid).
+ */
+export function validatePolicy(policy, index) {
+  const errors = [];
+  const prefix = `policies[${index}]`;
+
+  if (!policy || typeof policy !== 'object') {
+    return [`${prefix}: must be an object`];
+  }
+
+  if (typeof policy.id !== 'string' || !VALID_ID_PATTERN.test(policy.id)) {
+    errors.push(`${prefix}: id must be a lowercase kebab-case string`);
+  }
+
+  if (!VALID_POLICY_RULES.includes(policy.rule)) {
+    errors.push(
+      `${prefix}: unknown rule "${policy.rule}"; valid rules: ${VALID_POLICY_RULES.join(', ')}`,
+    );
+  }
+
+  if (!VALID_POLICY_ACTIONS.includes(policy.action)) {
+    errors.push(
+      `${prefix}: action must be one of ${VALID_POLICY_ACTIONS.join(', ')}`,
+    );
+  }
+
+  // Rule-specific param validation
+  if (VALID_POLICY_RULES.includes(policy.rule)) {
+    const paramErrors = validatePolicyParams(policy.rule, policy.params, prefix);
+    errors.push(...paramErrors);
+  }
+
+  // Scope validation (optional)
+  if (policy.scope != null) {
+    if (typeof policy.scope !== 'object') {
+      errors.push(`${prefix}: scope must be an object`);
+    } else {
+      if (policy.scope.phases != null && !Array.isArray(policy.scope.phases)) {
+        errors.push(`${prefix}: scope.phases must be an array`);
+      }
+      if (policy.scope.roles != null && !Array.isArray(policy.scope.roles)) {
+        errors.push(`${prefix}: scope.roles must be an array`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+function validatePolicyParams(rule, params, prefix) {
+  const errors = [];
+
+  switch (rule) {
+    case 'max_turns_per_phase':
+    case 'max_total_turns':
+      if (!params || typeof params.limit !== 'number' || params.limit < 1) {
+        errors.push(`${prefix}: params.limit must be a number >= 1`);
+      }
+      break;
+
+    case 'max_consecutive_same_role':
+      if (!params || typeof params.limit !== 'number' || params.limit < 1) {
+        errors.push(`${prefix}: params.limit must be a number >= 1`);
+      }
+      break;
+
+    case 'max_cost_per_turn':
+      if (
+        !params ||
+        typeof params.limit_usd !== 'number' ||
+        params.limit_usd <= 0
+      ) {
+        errors.push(`${prefix}: params.limit_usd must be a number > 0`);
+      }
+      break;
+
+    case 'require_status':
+      if (
+        !params ||
+        !Array.isArray(params.allowed) ||
+        params.allowed.length === 0
+      ) {
+        errors.push(`${prefix}: params.allowed must be a non-empty array`);
+      } else {
+        for (const status of params.allowed) {
+          if (!VALID_POLICY_TURN_STATUSES.includes(status)) {
+            errors.push(
+              `${prefix}: params.allowed contains invalid status "${status}"; valid statuses: ${VALID_POLICY_TURN_STATUSES.join(', ')}`,
+            );
+          }
+        }
+      }
+      break;
+  }
+
+  return errors;
+}
+
+/**
+ * Validate the full policies array at config load time.
+ * Returns { ok: boolean, errors: string[] }.
+ */
+export function validatePolicies(policies) {
+  if (policies == null) {
+    return { ok: true, errors: [] };
+  }
+
+  if (!Array.isArray(policies)) {
+    return { ok: false, errors: ['policies must be an array'] };
+  }
+
+  const errors = [];
+  const ids = new Set();
+
+  for (let i = 0; i < policies.length; i++) {
+    const policyErrors = validatePolicy(policies[i], i);
+    errors.push(...policyErrors);
+
+    if (policies[i]?.id) {
+      if (ids.has(policies[i].id)) {
+        errors.push(`policies[${i}]: duplicate id "${policies[i].id}"`);
+      }
+      ids.add(policies[i].id);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Evaluate all policies against the current turn context.
+ *
+ * @param {Array} policies - normalized policies from config
+ * @param {object} context
+ * @param {string} context.currentPhase
+ * @param {string} context.turnRole - role of the turn being accepted
+ * @param {string} context.turnStatus - status from turn result
+ * @param {number|null} context.turnCostUsd - cost from turn result
+ * @param {Array} context.history - accepted history entries
+ * @returns {PolicyEvaluationResult}
+ *
+ * @typedef {object} PolicyEvaluationResult
+ * @property {boolean} ok - true if no block/escalate violations
+ * @property {PolicyViolation[]} violations - all triggered policies
+ * @property {PolicyViolation[]} blocks - violations with action "block"
+ * @property {PolicyViolation[]} escalations - violations with action "escalate"
+ * @property {PolicyViolation[]} warnings - violations with action "warn"
+ *
+ * @typedef {object} PolicyViolation
+ * @property {string} policy_id
+ * @property {string} rule
+ * @property {string} action
+ * @property {string} message
+ */
+export function evaluatePolicies(policies, context) {
+  const result = {
+    ok: true,
+    violations: [],
+    blocks: [],
+    escalations: [],
+    warnings: [],
+  };
+
+  if (!Array.isArray(policies) || policies.length === 0) {
+    return result;
+  }
+
+  for (const policy of policies) {
+    // Scope check: skip if out of scope
+    if (policy.scope) {
+      if (
+        Array.isArray(policy.scope.phases) &&
+        policy.scope.phases.length > 0 &&
+        !policy.scope.phases.includes(context.currentPhase)
+      ) {
+        continue;
+      }
+      if (
+        Array.isArray(policy.scope.roles) &&
+        policy.scope.roles.length > 0 &&
+        !policy.scope.roles.includes(context.turnRole)
+      ) {
+        continue;
+      }
+    }
+
+    const evaluator = RULE_EVALUATORS[policy.rule];
+    if (!evaluator) {
+      continue; // Unknown rules caught at config validation
+    }
+
+    const evaluation = evaluator(policy.params || {}, context);
+    if (!evaluation.triggered) {
+      continue;
+    }
+
+    const violation = {
+      policy_id: policy.id,
+      rule: policy.rule,
+      action: policy.action,
+      message:
+        policy.message ||
+        `Policy "${policy.id}": ${evaluation.message}`,
+    };
+
+    result.violations.push(violation);
+
+    switch (policy.action) {
+      case 'block':
+        result.blocks.push(violation);
+        break;
+      case 'escalate':
+        result.escalations.push(violation);
+        break;
+      case 'warn':
+        result.warnings.push(violation);
+        break;
+    }
+  }
+
+  result.ok = result.blocks.length === 0 && result.escalations.length === 0;
+  return result;
+}
+
+/**
+ * Normalize policies config: null/undefined → [], validate, return.
+ */
+export function normalizePolicies(raw) {
+  if (raw == null) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw;
+}

package/src/lib/reference-conformance-adapter.js

@@ -139,6 +139,7 @@ function inflateState(rawState = {}, config) {
     blocked_on: rawState.blocked_on ?? null,
     blocked_reason: rawState.blocked_reason ?? null,
     escalation: rawState.escalation ?? null,
+    last_gate_failure: rawState.last_gate_failure ?? null,
     accepted_sequence: rawState.accepted_sequence ?? 0,
     turn_sequence: rawState.turn_sequence ?? 0,
     budget_reservations: rawState.budget_reservations ?? {},

package/src/lib/repo-observer.js

@@ -121,6 +121,7 @@ export function observeChanges(root, baseline) {
     // Non-git project — no observation possible
     return {
       files_changed: [],
+      file_markers: {},
       head_ref: null,
       diff_summary: null,
       observation_available: false,
@@ -162,6 +163,7 @@ export function observeChanges(root, baseline) {
 
   return {
     files_changed: actorFiles.sort(),
+    file_markers: buildFileMarkers(root, actorFiles),
     head_ref: currentHead,
     diff_summary: diffSummary,
     observation_available: true,
@@ -169,6 +171,119 @@ export function observeChanges(root, baseline) {
   };
 }
 
+export function attributeObservedChangesToTurn(observation, currentTurn, historyEntries = []) {
+  const observedFiles = Array.isArray(observation?.files_changed) ? observation.files_changed : [];
+  if (observedFiles.length === 0) {
+    return observation;
+  }
+
+  const concurrentIds = new Set(
+    Array.isArray(currentTurn?.concurrent_with) ? currentTurn.concurrent_with : [],
+  );
+  if (concurrentIds.size === 0) {
+    return observation;
+  }
+
+  const assignedSequence = Number.isInteger(currentTurn?.assigned_sequence)
+    ? currentTurn.assigned_sequence
+    : 0;
+  const acceptedConcurrentSiblings = (Array.isArray(historyEntries) ? historyEntries : [])
+    .filter((entry) => (
+      Number.isInteger(entry?.accepted_sequence)
+      && entry.accepted_sequence > assignedSequence
+      && concurrentIds.has(entry.turn_id)
+    ))
+    .sort((left, right) => left.accepted_sequence - right.accepted_sequence);
+
+  if (acceptedConcurrentSiblings.length === 0) {
+    return observation;
+  }
+
+  const siblingMarkersByFile = new Map();
+  for (const entry of acceptedConcurrentSiblings) {
+    const siblingFiles = Array.isArray(entry?.observed_artifact?.files_changed)
+      ? entry.observed_artifact.files_changed
+      : Array.isArray(entry?.files_changed)
+        ? entry.files_changed
+        : [];
+    const siblingMarkers = entry?.observed_artifact?.file_markers;
+    if (!siblingMarkers || typeof siblingMarkers !== 'object' || Array.isArray(siblingMarkers)) {
+      continue;
+    }
+    for (const filePath of siblingFiles) {
+      if (typeof siblingMarkers[filePath] === 'string' && siblingMarkers[filePath].length > 0) {
+        siblingMarkersByFile.set(filePath, siblingMarkers[filePath]);
+      }
+    }
+  }
+
+  if (siblingMarkersByFile.size === 0) {
+    return observation;
+  }
+
+  const nextFiles = [];
+  const nextMarkers = {};
+  const attributedToConcurrentSiblings = [];
+  const observationMarkers = observation?.file_markers && typeof observation.file_markers === 'object'
+    ? observation.file_markers
+    : {};
+
+  for (const filePath of observedFiles) {
+    const currentMarker = observationMarkers[filePath];
+    const siblingMarker = siblingMarkersByFile.get(filePath);
+    if (typeof siblingMarker === 'string' && siblingMarker === currentMarker) {
+      attributedToConcurrentSiblings.push(filePath);
+      continue;
+    }
+    nextFiles.push(filePath);
+    if (typeof currentMarker === 'string') {
+      nextMarkers[filePath] = currentMarker;
+    }
+  }
+
+  if (attributedToConcurrentSiblings.length === 0) {
+    return observation;
+  }
+
+  return {
+    ...observation,
+    files_changed: nextFiles,
+    file_markers: nextMarkers,
+    attributed_to_concurrent_siblings: attributedToConcurrentSiblings,
+  };
+}
+
+/**
+ * Build the file set used for acceptance-time conflict detection.
+ *
+ * Parallel attribution removes unchanged sibling files from the current turn's
+ * observed set so declared-vs-observed checks stay truthful. Conflict detection
+ * is stricter: if the agent declared a file that still appears in the raw
+ * baseline-to-now workspace union, that overlap must remain conflict-eligible
+ * even if the current file contents match a sibling's accepted marker.
+ *
+ * @param {object} rawObservation — unfiltered observeChanges() result
+ * @param {object} attributedObservation — result after attributeObservedChangesToTurn()
+ * @param {string[]} declaredFiles — turnResult.files_changed
+ * @returns {string[]}
+ */
+export function buildConflictCandidateFiles(rawObservation, attributedObservation, declaredFiles = []) {
+  const conflictFiles = new Set(
+    Array.isArray(attributedObservation?.files_changed) ? attributedObservation.files_changed : [],
+  );
+  const rawObserved = new Set(
+    Array.isArray(rawObservation?.files_changed) ? rawObservation.files_changed : [],
+  );
+
+  for (const filePath of declaredFiles || []) {
+    if (rawObserved.has(filePath)) {
+      conflictFiles.add(filePath);
+    }
+  }
+
+  return [...conflictFiles].sort();
+}
+
 /**
  * Classify observed file changes into added, modified, and deleted.
  *
@@ -284,13 +399,21 @@ function getFilteredChanges(root, baseRef, filter) {
  * @returns {object}
  */
 export function buildObservedArtifact(observation, baseline) {
-  return {
+  const artifact = {
     derived_by: 'orchestrator',
     baseline_ref: baseline?.head_ref ? `git:${baseline.head_ref}` : null,
     accepted_ref: observation.head_ref ? `git:${observation.head_ref}` : 'workspace:dirty',
     files_changed: observation.files_changed,
+    file_markers: observation.file_markers || {},
     diff_summary: observation.diff_summary,
   };
+  // Preserve parallel attribution so operators can see which files were
+  // attributed to concurrent siblings and excluded from this turn.
+  const attributed = observation.attributed_to_concurrent_siblings;
+  if (Array.isArray(attributed) && attributed.length > 0) {
+    artifact.attributed_to_concurrent_siblings = attributed;
+  }
+  return artifact;
 }
 
 // ── Verification Normalization ──────────────────────────────────────────────
@@ -572,6 +695,14 @@ function getWorkspaceFileMarker(root, filePath) {
   }
 }
 
+function buildFileMarkers(root, filePaths) {
+  const markers = {};
+  for (const filePath of filePaths || []) {
+    markers[filePath] = getWorkspaceFileMarker(root, filePath);
+  }
+  return markers;
+}
+
 function getUntrackedFiles(root) {
   try {
     const result = execSync('git ls-files --others --exclude-standard', {