agentxchain 2.21.0 → 2.23.0

package/src/lib/blocked-state.js

@@ -1,6 +1,66 @@
-import { getActiveTurnCount } from './governed-state.js';
+import {
+  deriveConflictLoopRecoveryAction,
+  deriveDispatchRecoveryAction,
+  deriveEscalationRecoveryAction,
+  deriveHookTamperRecoveryAction,
+  deriveNeedsHumanRecoveryAction,
+  getActiveTurnCount,
+} from './governed-state.js';
 
-export function deriveRecoveryDescriptor(state) {
+function isLegacyEscalationRecoveryAction(action) {
+  return action === 'Resolve the escalation, then run agentxchain step --resume'
+    || action === 'Resolve the escalation, then run agentxchain step';
+}
+
+function isLegacyNeedsHumanRecoveryAction(action) {
+  return action === 'Resolve the stated issue, then run agentxchain step --resume';
+}
+
+function isLegacyHookTamperRecoveryAction(action) {
+  return action === 'Disable or fix the hook, verify protected files, then run agentxchain step --resume';
+}
+
+function isLegacyConflictLoopRecoveryAction(action) {
+  return typeof action === 'string' && action.startsWith('Serialize the conflicting work, then run agentxchain step --resume');
+}
+
+function maybeRefreshRecoveryAction(state, config, persistedRecovery, turnRetained) {
+  if (!config || !persistedRecovery || typeof persistedRecovery !== 'object') {
+    return null;
+  }
+
+  const typedReason = persistedRecovery.typed_reason;
+  const currentAction = persistedRecovery.recovery_action || null;
+  const turnId = state?.blocked_reason?.turn_id ?? state?.escalation?.from_turn_id ?? null;
+  if (typedReason === 'retries_exhausted' || ((typedReason === 'operator_escalation') && isLegacyEscalationRecoveryAction(currentAction))) {
+    return deriveEscalationRecoveryAction(state, config, {
+      turnRetained,
+      turnId,
+    });
+  }
+
+  if (typedReason === 'needs_human' && isLegacyNeedsHumanRecoveryAction(currentAction)) {
+    return deriveNeedsHumanRecoveryAction(state, config, {
+      turnRetained,
+      turnId,
+    });
+  }
+
+  if (typedReason === 'hook_tamper' && isLegacyHookTamperRecoveryAction(currentAction)) {
+    return deriveHookTamperRecoveryAction(state, config, {
+      turnRetained,
+      turnId,
+    });
+  }
+
+  if (typedReason === 'conflict_loop' && isLegacyConflictLoopRecoveryAction(currentAction)) {
+    return deriveConflictLoopRecoveryAction(turnId);
+  }
+
+  return null;
+}
+
+export function deriveRecoveryDescriptor(state, config = null) {
   if (!state || typeof state !== 'object') {
     return null;
   }
@@ -29,10 +89,13 @@ export function deriveRecoveryDescriptor(state) {
 
   const persistedRecovery = state.blocked_reason?.recovery;
   if (persistedRecovery && typeof persistedRecovery === 'object') {
+    const refreshedRecoveryAction = maybeRefreshRecoveryAction(state, config, persistedRecovery, turnRetained);
     return {
       typed_reason: persistedRecovery.typed_reason || 'unknown_block',
       owner: persistedRecovery.owner || 'human',
-      recovery_action: persistedRecovery.recovery_action || 'Inspect state.json and resolve manually before rerunning agentxchain step',
+      recovery_action: refreshedRecoveryAction
+        || persistedRecovery.recovery_action
+        || 'Inspect state.json and resolve manually before rerunning agentxchain step',
       turn_retained: typeof persistedRecovery.turn_retained === 'boolean'
         ? persistedRecovery.turn_retained
         : turnRetained,
@@ -48,7 +111,10 @@ export function deriveRecoveryDescriptor(state) {
     return {
       typed_reason: 'needs_human',
       owner: 'human',
-      recovery_action: 'Resolve the stated issue, then run agentxchain step --resume',
+      recovery_action: deriveNeedsHumanRecoveryAction(state, config, {
+        turnRetained,
+        turnId: state.blocked_reason?.turn_id ?? null,
+      }),
       turn_retained: turnRetained,
       detail: state.blocked_on.slice('human:'.length) || null,
     };
@@ -66,9 +132,10 @@ export function deriveRecoveryDescriptor(state) {
 
   if (state.blocked_on.startsWith('escalation:')) {
     const isOperatorEscalation = state.blocked_on.startsWith('escalation:operator:') || state.escalation?.source === 'operator';
-    const recoveryAction = turnRetained
-      ? 'Resolve the escalation, then run agentxchain step --resume'
-      : 'Resolve the escalation, then run agentxchain step';
+    const recoveryAction = deriveEscalationRecoveryAction(state, config, {
+      turnRetained,
+      turnId: state.blocked_reason?.turn_id ?? state.escalation?.from_turn_id ?? null,
+    });
     return {
       typed_reason: isOperatorEscalation ? 'operator_escalation' : 'retries_exhausted',
       owner: 'human',
@@ -82,7 +149,10 @@ export function deriveRecoveryDescriptor(state) {
     return {
       typed_reason: 'dispatch_error',
       owner: 'human',
-      recovery_action: 'Resolve the dispatch issue, then run agentxchain step --resume',
+      recovery_action: deriveDispatchRecoveryAction(state, config, {
+        turnRetained,
+        turnId: state.blocked_reason?.turn_id ?? null,
+      }),
       turn_retained: turnRetained,
       detail: state.blocked_on.slice('dispatch:'.length) || state.blocked_on,
     };

package/src/lib/config.js

@@ -3,7 +3,12 @@ import { join, parse as pathParse, resolve } from 'path';
 import { safeParseJson, validateConfigSchema, validateLockSchema, validateProjectStateSchema, validateStateSchema } from './schema.js';
 import { loadNormalizedConfig } from './normalized-config.js';
 import { safeWriteJson } from './safe-write.js';
-import { normalizeGovernedStateShape, getActiveTurn } from './governed-state.js';
+import {
+  normalizeGovernedStateShape,
+  getActiveTurn,
+  reconcileBudgetStatusWithConfig,
+  reconcileRecoveryActionsWithConfig,
+} from './governed-state.js';
 
 function attachLegacyCurrentTurnAlias(state) {
   if (!state || typeof state !== 'object') {
@@ -148,7 +153,11 @@ export function loadProjectState(root, config) {
   if (config?.protocol_mode === 'governed') {
     const normalized = normalizeGovernedStateShape(stateData);
     stateData = normalized.state;
-    if (normalized.changed) {
+    const reconciledBudget = reconcileBudgetStatusWithConfig(stateData, config);
+    stateData = reconciledBudget.state;
+    const reconciledRecovery = reconcileRecoveryActionsWithConfig(stateData, config);
+    stateData = reconciledRecovery.state;
+    if (normalized.changed || reconciledBudget.changed || reconciledRecovery.changed) {
       safeWriteJson(filePath, stateData);
     }
   }

package/src/lib/dispatch-bundle.js

@@ -14,7 +14,7 @@
  * orchestrator turn loop call it after assignGovernedTurn().
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { getActiveTurn, getActiveTurns } from './governed-state.js';
 import {
@@ -31,6 +31,7 @@ import {
 const HISTORY_PATH = '.agentxchain/history.jsonl';
 const FILE_PREVIEW_MAX_FILES = 5;
 const FILE_PREVIEW_MAX_LINES = 120;
+const PROPOSAL_SUMMARY_MAX_LINES = 80;
 const GATE_FILE_PREVIEW_MAX_LINES = 60;
 const DISPATCH_LOG_MAX_LINES = 50;
 const DISPATCH_LOG_MAX_LINE_BYTES = 8192;
@@ -229,6 +230,21 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('');
     lines.push('- You may propose changes as patches but cannot directly commit.');
     lines.push('- Your artifact type should be `patch`.');
+    if (runtimeType === 'api_proxy') {
+      lines.push('- **This runtime cannot write repo files directly.** When doing work, you MUST return proposed changes as structured JSON.');
+      lines.push('- Include a `proposed_changes` array in your turn result with each file change (omit or set to `[]` on completion-only turns):');
+      lines.push('  ```json');
+      lines.push('  "proposed_changes": [');
+      lines.push('    { "path": "src/lib/foo.js", "action": "create", "content": "// full file..." },');
+      lines.push('    { "path": "src/lib/bar.js", "action": "modify", "content": "// full new content..." },');
+      lines.push('    { "path": "src/old.js", "action": "delete" }');
+      lines.push('  ]');
+      lines.push('  ```');
+      lines.push('- Valid actions: `create` (new file), `modify` (replace content), `delete` (remove file).');
+      lines.push('- `content` is required for `create` and `modify` actions.');
+      lines.push('- The orchestrator will materialize your proposal to `.agentxchain/proposed/<turn_id>/` for review.');
+      lines.push('- List all proposed file paths in `files_changed`.');
+    }
     lines.push('');
   }
 
@@ -366,6 +382,22 @@ function renderPrompt(role, roleId, turn, state, config, root) {
       lines.push(`- **You are in the \`${currentPhase}\` phase (final phase).** When ready to ship, set \`run_completion_request: true\` and \`phase_transition_request: null\`.`);
     }
   }
+  // Phase-specific guidance for proposed roles
+  if (role.write_authority === 'proposed' && phaseNames.length > 0) {
+    const currentPhase = state?.phase;
+    const phaseIdx = currentPhase ? phaseNames.indexOf(currentPhase) : -1;
+    if (phaseIdx >= 0 && phaseIdx < phaseNames.length - 1) {
+      const nextPhase = phaseNames[phaseIdx + 1];
+      const currentGate = config.routing?.[currentPhase]?.exit_gate;
+      const gateClause = currentGate ? ` and the exit gate (\`${currentGate}\`) is satisfied` : '';
+      lines.push(`- **You are in the \`${currentPhase}\` phase (not final phase).** When your work is complete${gateClause}, set \`phase_transition_request: "${nextPhase}"\`.`);
+    } else if (phaseIdx >= 0 && phaseIdx === phaseNames.length - 1) {
+      lines.push(`- **You are in the \`${currentPhase}\` phase (final phase).** When ready to ship, set \`run_completion_request: true\` and \`phase_transition_request: null\`.`);
+      if (runtimeType === 'api_proxy') {
+        lines.push('- **Completion turns must be no-op:** set `proposed_changes` to `[]` or omit it, set `files_changed` to `[]`, and set `artifact.type` to `"review"`. Do NOT propose file changes on a completion turn.');
+      }
+    }
+  }
   // Phase-specific guidance for review_only roles (terminal phase ship readiness)
   if (role.write_authority === 'review_only' && phaseNames.length > 0) {
     const currentPhase = state?.phase;
@@ -467,6 +499,42 @@ function renderContext(state, config, root, turn, role) {
         }
       }
 
+      const proposalPreview = role?.write_authority === 'review_only'
+        ? buildProposalArtifactPreview(root, lastTurn)
+        : null;
+      if (proposalPreview) {
+        lines.push('### Proposed Artifact');
+        lines.push('');
+        lines.push(`- **Artifact ref:** \`${proposalPreview.artifactRef}\``);
+        lines.push(`- **Proposed files:** ${proposalPreview.changeCount}`);
+        lines.push('');
+        lines.push('```');
+        lines.push(proposalPreview.summary);
+        lines.push('```');
+        if (proposalPreview.summaryTruncated) {
+          lines.push('');
+          lines.push(`_Preview truncated after ${PROPOSAL_SUMMARY_MAX_LINES} lines._`);
+        }
+        lines.push('');
+
+        if (proposalPreview.filePreviews.length > 0) {
+          lines.push('### Proposed File Previews');
+          lines.push('');
+          for (const preview of proposalPreview.filePreviews) {
+            lines.push(`#### \`${preview.path}\` (${preview.action})`);
+            lines.push('');
+            lines.push('```');
+            lines.push(preview.content);
+            lines.push('```');
+            if (preview.truncated) {
+              lines.push('');
+              lines.push(`_Preview truncated after ${FILE_PREVIEW_MAX_LINES} lines._`);
+            }
+            lines.push('');
+          }
+        }
+      }
+
       // Verification evidence from the previous turn
       // Use raw verification (has commands, machine_evidence, evidence_summary)
       // and supplement with normalized_verification status when available
@@ -683,6 +751,113 @@ function buildChangedFilePreviews(root, filesChanged) {
   return previews;
 }
 
+function buildProposalArtifactPreview(root, lastTurn) {
+  const artifactRef = lastTurn?.artifact?.ref;
+  if (typeof artifactRef !== 'string' || !artifactRef.startsWith('.agentxchain/proposed/')) {
+    return null;
+  }
+
+  const absProposalDir = join(root, artifactRef);
+  const summaryPath = join(absProposalDir, 'PROPOSAL.md');
+
+  let summary = '';
+  let summaryTruncated = false;
+
+  if (existsSync(summaryPath)) {
+    try {
+      const raw = readFileSync(summaryPath, 'utf8');
+      const lines = raw.replace(/\r\n/g, '\n').split('\n');
+      summaryTruncated = lines.length > PROPOSAL_SUMMARY_MAX_LINES;
+      summary = (summaryTruncated ? lines.slice(0, PROPOSAL_SUMMARY_MAX_LINES) : lines)
+        .join('\n')
+        .trimEnd();
+    } catch {
+      summary = '';
+    }
+  }
+
+  const changeActions = extractProposalActions(summary);
+  const materializedFiles = collectProposalFiles(absProposalDir);
+
+  if (!summary) {
+    const fallbackLines = [
+      `# Proposed Changes — ${lastTurn.turn_id || '(unknown)'}`,
+      '',
+      lastTurn.summary || '(no summary)',
+      '',
+    ];
+    for (const filePath of materializedFiles) {
+      fallbackLines.push(`- \`${filePath}\` — ${changeActions.get(filePath) || 'create'}`);
+    }
+    summary = fallbackLines.join('\n');
+  }
+
+  const filePreviews = [];
+  for (const relPath of materializedFiles.slice(0, FILE_PREVIEW_MAX_FILES)) {
+    const absPath = join(absProposalDir, relPath);
+
+    let raw;
+    try {
+      raw = readFileSync(absPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lines = raw.replace(/\r\n/g, '\n').split('\n');
+    const truncated = lines.length > FILE_PREVIEW_MAX_LINES;
+    const previewLines = truncated ? lines.slice(0, FILE_PREVIEW_MAX_LINES) : lines;
+    filePreviews.push({
+      path: relPath,
+      action: changeActions.get(relPath) || 'create',
+      content: previewLines.join('\n').trimEnd(),
+      truncated,
+    });
+  }
+
+  return {
+    artifactRef,
+    summary,
+    summaryTruncated,
+    filePreviews,
+    changeCount: changeActions.size || materializedFiles.length,
+  };
+}
+
+function extractProposalActions(summary) {
+  const actions = new Map();
+  if (!summary) {
+    return actions;
+  }
+
+  const matches = summary.matchAll(/^- `([^`]+)` — ([a-z]+)/gm);
+  for (const match of matches) {
+    actions.set(match[1], match[2]);
+  }
+  return actions;
+}
+
+function collectProposalFiles(absProposalDir, relPrefix = '') {
+  if (!existsSync(absProposalDir)) {
+    return [];
+  }
+
+  const files = [];
+  for (const entry of readdirSync(absProposalDir, { withFileTypes: true })) {
+    if (entry.name === 'PROPOSAL.md') {
+      continue;
+    }
+
+    const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+    const absPath = join(absProposalDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectProposalFiles(absPath, relPath));
+    } else if (entry.isFile()) {
+      files.push(relPath);
+    }
+  }
+  return files.sort();
+}
+
 function buildDispatchLogExcerpt(root, turnId) {
   const logPath = join(root, getDispatchLogPath(turnId));
   if (!existsSync(logPath)) {