agentxchain 2.60.0 → 2.62.0

package/bin/agentxchain.js

@@ -192,6 +192,7 @@ program
   .description('View or edit project configuration')
   .option('--add-agent', 'Add a new agent interactively')
   .option('--remove-agent <id>', 'Remove an agent by ID')
+  .option('--get <path>', 'Read a config value (e.g. --get project.goal)')
   .option('--set <path_and_value...>', 'Set a config value (e.g. --set project.goal "Build a governed CLI")')
   .option('-j, --json', 'Output config as JSON')
   .action(configCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.60.0",
+  "version": "2.62.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/accept-turn.js

@@ -166,6 +166,9 @@ export async function acceptTurnCommand(opts = {}) {
   if (accepted?.cost?.usd != null) {
     console.log(`  ${chalk.dim('Cost:')}     $${formatUsd(accepted.cost.usd)}`);
   }
+  if (result.budget_warning) {
+    console.log(`  ${chalk.yellow('Budget warning:')} ${result.budget_warning}`);
+  }
   console.log('');
 
   const recovery = deriveRecoveryDescriptor(result.state);

package/src/commands/config.js

@@ -17,6 +17,12 @@ export async function configCommand(opts) {
   const config = rawConfig;
   const configPath = join(root, CONFIG_FILE);
 
+  if (opts.get && opts.set) {
+    console.log(chalk.red('  --get and --set are mutually exclusive.'));
+    console.log(chalk.dim('  Inspect a value with `agentxchain config --get <path>` or change it with `agentxchain config --set <path> <value>`.'));
+    process.exit(1);
+  }
+
   if (version === 4 && opts.addAgent) {
     printLegacyOnlyMutationError('--add-agent');
     return;
@@ -37,6 +43,11 @@ export async function configCommand(opts) {
     return;
   }
 
+  if (opts.get) {
+    getSetting(config, opts.get, { json: opts.json });
+    return;
+  }
+
   if (opts.set) {
     setSetting(config, configPath, opts.set, { version, root });
     return;
@@ -81,6 +92,7 @@ function printLegacyConfig(config) {
   console.log(chalk.dim('  Commands:'));
   console.log(`    ${chalk.bold('agentxchain config --add-agent')}        Add a new agent`);
   console.log(`    ${chalk.bold('agentxchain config --remove-agent <id>')} Remove an agent`);
+  console.log(`    ${chalk.bold('agentxchain config --get <key>')}         Read one config value`);
   console.log(`    ${chalk.bold('agentxchain config --set <key> <val>')}   Update a setting`);
   console.log(`    ${chalk.bold('agentxchain config --json')}              Output as JSON`);
   console.log('');
@@ -99,6 +111,7 @@ function printGovernedConfig(config) {
   console.log(`  ${chalk.dim('Runtimes:')}  ${Object.keys(config.runtimes || {}).length}`);
   console.log('');
   console.log(chalk.dim('  Commands:'));
+  console.log(`    ${chalk.bold('agentxchain config --get project.goal')}              Read one config value without opening JSON`);
   console.log(`    ${chalk.bold('agentxchain config --set project.goal "Build a ..."')}  Set mission context without hand-editing JSON`);
   console.log(`    ${chalk.bold('agentxchain config --set roles.qa.runtime manual-qa')}  Switch a governed role runtime`);
   console.log(`    ${chalk.bold('agentxchain config --json')}                             Output raw config`);
@@ -169,10 +182,8 @@ function setSetting(config, configPath, keyValPair, context) {
   }
 
   const { key, rawVal } = parsed;
-  const segments = key.split('.');
-  const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
-
-  if (segments.some(segment => forbiddenKeys.has(segment))) {
+  const segments = parseKeyPath(key);
+  if (!segments) {
     console.log(chalk.red('  Refusing to write reserved object path.'));
     process.exit(1);
   }
@@ -211,6 +222,35 @@ function setSetting(config, configPath, keyValPair, context) {
   console.log('');
 }
 
+function getSetting(config, key, opts = {}) {
+  const segments = parseKeyPath(key);
+  if (!segments) {
+    console.log(chalk.red('  Refusing to read reserved object path.'));
+    process.exit(1);
+  }
+
+  let value = config;
+  for (const segment of segments) {
+    if (value === null || typeof value !== 'object' || !(segment in value)) {
+      console.log(chalk.red(`  Config path not found: ${key}`));
+      process.exit(1);
+    }
+    value = value[segment];
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+
+  if (value !== null && typeof value === 'object') {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+
+  console.log(String(value));
+}
+
 function parseSetInput(input) {
   if (Array.isArray(input)) {
     if (input.length >= 2) {
@@ -235,6 +275,19 @@ function parseSetInput(input) {
   return null;
 }
 
+function parseKeyPath(input) {
+  if (typeof input !== 'string' || input.trim() === '') {
+    return null;
+  }
+
+  const segments = input.split('.');
+  const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
+  if (segments.some(segment => segment === '' || forbiddenKeys.has(segment))) {
+    return null;
+  }
+  return segments;
+}
+
 function validateEditedConfig(config, context) {
   if (context.version === 4) {
     return validateV4Config(config, context.root);

package/src/commands/restart.js

@@ -297,6 +297,9 @@ export async function restartCommand(opts) {
       console.log(chalk.red(`Failed to assign turn: ${assignment.error}`));
       process.exit(1);
     }
+    for (const warning of assignment.warnings || []) {
+      console.log(chalk.yellow(`Warning: ${warning}`));
+    }
 
     // assignGovernedTurn already writes a checkpoint at turn_assigned
 

package/src/commands/resume.js

@@ -259,6 +259,7 @@ export async function resumeCommand(opts) {
     console.log(chalk.red(`Failed to assign turn: ${assignResult.error}`));
     process.exit(1);
   }
+  printAssignmentWarnings(assignResult);
   state = assignResult.state;
 
   // Write dispatch bundle
@@ -415,6 +416,12 @@ function printDispatchBundleWarnings(bundleResult) {
   }
 }
 
+function printAssignmentWarnings(assignResult) {
+  for (const warning of assignResult.warnings || []) {
+    console.log(chalk.yellow(`Warning: ${warning}`));
+  }
+}
+
 function printAssignmentHookFailure(result, roleId) {
   const recovery = deriveRecoveryDescriptor(result.state);
   const hookName = result.hookResults?.blocker?.hook_name

package/src/commands/status.js

@@ -277,7 +277,10 @@ function renderGovernedStatus(context, opts) {
 
   if (state?.budget_status) {
     console.log('');
-    console.log(`  ${chalk.dim('Budget:')}   spent $${formatUsd(state.budget_status.spent_usd)} / remaining $${formatUsd(state.budget_status.remaining_usd)}`);
+    const budgetLabel = state.budget_status.warn_mode
+      ? `spent $${formatUsd(state.budget_status.spent_usd)} / remaining $${formatUsd(state.budget_status.remaining_usd)} ${chalk.yellow('[OVER BUDGET]')}`
+      : `spent $${formatUsd(state.budget_status.spent_usd)} / remaining $${formatUsd(state.budget_status.remaining_usd)}`;
+    console.log(`  ${chalk.dim('Budget:')}   ${budgetLabel}`);
   }
 
   console.log('');

package/src/commands/step.js

@@ -293,6 +293,7 @@ export async function stepCommand(opts) {
         console.log(chalk.red(`Failed to assign turn: ${assignResult.error}`));
         process.exit(1);
       }
+      printAssignmentWarnings(assignResult);
       state = assignResult.state;
 
       const bundleResult = writeDispatchBundle(root, state, config);
@@ -948,6 +949,12 @@ function printDispatchBundleWarnings(bundleResult) {
   }
 }
 
+function printAssignmentWarnings(assignResult) {
+  for (const warning of assignResult.warnings || []) {
+    console.log(chalk.yellow(`Warning: ${warning}`));
+  }
+}
+
 function printAssignmentHookFailure(result, roleId) {
   const recovery = deriveRecoveryDescriptor(result.state);
   const hookName = result.hookResults?.blocker?.hook_name

package/src/lib/governed-state.js

@@ -575,7 +575,7 @@ function attachLegacyCurrentTurnAlias(state) {
 function formatBudgetRecoveryAction(isReadyToResume) {
   return isReadyToResume
     ? 'Run agentxchain resume to assign the next turn'
-    : 'Increase per_run_max_usd in agentxchain.json, then run agentxchain resume';
+    : 'Increase budget with agentxchain config --set budget.per_run_max_usd <usd>, then run agentxchain resume';
 }
 
 function formatBudgetRecoveryDetail(spentUsd, limitUsd, remainingUsd, isReadyToResume) {
@@ -1936,13 +1936,19 @@ export function assignGovernedTurn(root, config, roleId) {
     return { ok: false, error: `Cannot assign turn: ${activeCount} active turn(s) already at capacity (max_concurrent_turns = ${maxConcurrent})` };
   }
 
-  // DEC-BUDGET-ENFORCE-001: Pre-assignment budget exhaustion guard
-  if (state.budget_status?.remaining_usd != null && state.budget_status.remaining_usd <= 0) {
-    return { ok: false, error: `Cannot assign turn: run budget exhausted (spent $${(state.budget_status.spent_usd || 0).toFixed(2)} of $${((state.budget_status.spent_usd || 0) + state.budget_status.remaining_usd).toFixed(2)} limit). Increase per_run_max_usd in agentxchain.json, then run agentxchain resume` };
-  }
-
   // DEC-PARALLEL-011: Budget reservation
   const warnings = [];
+
+  // DEC-BUDGET-ENFORCE-001 + DEC-BUDGET-WARN-001: Pre-assignment budget exhaustion guard
+  if (state.budget_status?.remaining_usd != null && state.budget_status.remaining_usd <= 0) {
+    const onExceed = config.budget?.on_exceed || 'pause_and_escalate';
+    if (onExceed === 'warn') {
+      // Allow assignment but add a warning
+      warnings.push(`Budget exhausted (spent $${(state.budget_status.spent_usd || 0).toFixed(2)} of $${((state.budget_status.spent_usd || 0) + state.budget_status.remaining_usd).toFixed(2)} limit). Run continues in warn mode per on_exceed policy.`);
+    } else {
+      return { ok: false, error: `Cannot assign turn: run budget exhausted (spent $${(state.budget_status.spent_usd || 0).toFixed(2)} of $${((state.budget_status.spent_usd || 0) + state.budget_status.remaining_usd).toFixed(2)} limit). Increase budget with agentxchain config --set budget.per_run_max_usd <usd>, then run agentxchain resume` };
+    }
+  }
   const reservations = { ...(state.budget_reservations || {}) };
   const turnId = generateId('turn');
   const estimatedCost = estimateTurnBudget(config, roleId);
@@ -1950,7 +1956,8 @@ export function assignGovernedTurn(root, config, roleId) {
   if (estimatedCost > 0 && state.budget_status?.remaining_usd != null) {
     const alreadyReserved = Object.values(reservations).reduce((sum, r) => sum + (r.reserved_usd || 0), 0);
     const available = state.budget_status.remaining_usd - alreadyReserved;
-    if (estimatedCost > available) {
+    const onExceedReserve = config.budget?.on_exceed || 'pause_and_escalate';
+    if (estimatedCost > available && onExceedReserve !== 'warn') {
       return { ok: false, error: `Cannot assign turn: estimated cost $${estimatedCost.toFixed(2)} exceeds available budget $${available.toFixed(2)} (after reservations)` };
     }
     reservations[turnId] = {
@@ -2617,6 +2624,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     accepted_integration_ref: derivedRef,
     next_recommended_role: deriveNextRecommendedRole(turnResult, state, config),
     budget_status: {
+      ...(state.budget_status || {}),
       spent_usd: (state.budget_status?.spent_usd || 0) + costUsd,
       remaining_usd: state.budget_status?.remaining_usd != null
         ? state.budget_status.remaining_usd - costUsd
@@ -2657,7 +2665,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   if (turnReservation && costUsd > turnReservation.reserved_usd) {
     budgetWarning = `Actual cost $${costUsd.toFixed(2)} exceeded reservation $${turnReservation.reserved_usd.toFixed(2)} for this turn`;
   }
-  // Budget exhaustion enforcement
+  // Budget exhaustion enforcement (DEC-BUDGET-ENFORCE-001 + DEC-BUDGET-WARN-001)
   if (
     updatedState.budget_status.remaining_usd != null &&
     updatedState.budget_status.remaining_usd <= 0 &&
@@ -2665,9 +2673,9 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     updatedState.status !== 'completed'
   ) {
     const onExceed = config.budget?.on_exceed || 'pause_and_escalate';
+    const limit = (updatedState.budget_status.spent_usd + updatedState.budget_status.remaining_usd);
+    const overBy = Math.abs(updatedState.budget_status.remaining_usd);
     if (onExceed === 'pause_and_escalate') {
-      const limit = (updatedState.budget_status.spent_usd + updatedState.budget_status.remaining_usd);
-      const overBy = Math.abs(updatedState.budget_status.remaining_usd);
       updatedState.status = 'blocked';
       updatedState.blocked_on = 'budget:exhausted';
       updatedState.blocked_reason = buildBlockedReason({
@@ -2675,7 +2683,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         recovery: {
           typed_reason: 'budget_exhausted',
           owner: 'human',
-          recovery_action: 'Increase per_run_max_usd in agentxchain.json, then run agentxchain resume',
+          recovery_action: 'Increase budget with agentxchain config --set budget.per_run_max_usd <usd>, then run agentxchain resume',
           turn_retained: false,
           detail: `Run budget exhausted: spent $${updatedState.budget_status.spent_usd.toFixed(2)} of $${limit.toFixed(2)} limit ($${overBy.toFixed(2)} over)`,
         },
@@ -2685,6 +2693,15 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       updatedState.budget_status.exhausted = true;
       updatedState.budget_status.exhausted_at = now;
       updatedState.budget_status.exhausted_after_turn = currentTurn.turn_id;
+    } else if (onExceed === 'warn') {
+      // DEC-BUDGET-WARN-001: Do not block — mark exhaustion and emit warning
+      if (!updatedState.budget_status.exhausted) {
+        updatedState.budget_status.exhausted = true;
+        updatedState.budget_status.exhausted_at = now;
+        updatedState.budget_status.exhausted_after_turn = currentTurn.turn_id;
+      }
+      updatedState.budget_status.warn_mode = true;
+      budgetWarning = `Budget exhausted: spent $${updatedState.budget_status.spent_usd.toFixed(2)} of $${limit.toFixed(2)} limit ($${overBy.toFixed(2)} over). Run continues in warn mode.`;
     }
   }
 
@@ -3081,6 +3098,22 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     });
   }
 
+  // DEC-BUDGET-WARN-001: Emit budget_exceeded_warn event when warn mode triggers
+  if (updatedState.budget_status?.warn_mode && budgetWarning) {
+    emitRunEvent(root, 'budget_exceeded_warn', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      payload: {
+        spent_usd: updatedState.budget_status.spent_usd,
+        limit_usd: updatedState.budget_status.spent_usd + updatedState.budget_status.remaining_usd,
+        remaining_usd: updatedState.budget_status.remaining_usd,
+        warning: budgetWarning,
+      },
+    });
+  }
+
   if (updatedState.pending_phase_transition) {
     emitPendingLifecycleNotification(root, config, updatedState, 'phase_transition_pending', {
       from: updatedState.pending_phase_transition.from,

package/src/lib/normalized-config.js

@@ -61,6 +61,7 @@ const VALID_API_PROXY_PREFLIGHT_FIELDS = [
   'tokenizer',
   'safety_margin_tokens',
 ];
+const VALID_BUDGET_ON_EXCEED = ['pause_and_escalate', 'warn'];
 
 function validateMcpRuntime(runtimeId, runtime, errors) {
   const transport = typeof runtime?.transport === 'string' && runtime.transport.trim()
@@ -537,6 +538,12 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...policyValidation.errors);
   }
 
+  // Budget (optional but validated if present)
+  if (data.budget !== undefined) {
+    const budgetValidation = validateBudgetConfig(data.budget);
+    errors.push(...budgetValidation.errors);
+  }
+
   // Approval Policy (optional but validated if present)
   if (data.approval_policy !== undefined) {
     errors.push(...validateApprovalPolicy(data.approval_policy, data.routing));
@@ -551,6 +558,80 @@ export function validateV4Config(data, projectRoot) {
   return { ok: errors.length === 0, errors };
 }
 
+export function validateBudgetConfig(budget) {
+  const errors = [];
+
+  if (budget === null) {
+    return { ok: true, errors };
+  }
+
+  if (!budget || typeof budget !== 'object' || Array.isArray(budget)) {
+    errors.push('budget must be an object');
+    return { ok: false, errors };
+  }
+
+  validateBudgetUsdLimit('budget.per_turn_max_usd', budget.per_turn_max_usd, errors);
+  validateBudgetUsdLimit('budget.per_run_max_usd', budget.per_run_max_usd, errors);
+
+  if (
+    Number.isFinite(budget.per_turn_max_usd) &&
+    Number.isFinite(budget.per_run_max_usd) &&
+    budget.per_turn_max_usd > budget.per_run_max_usd
+  ) {
+    errors.push('budget.per_turn_max_usd must be less than or equal to budget.per_run_max_usd when both are set');
+  }
+
+  if (budget.on_exceed !== undefined) {
+    if (typeof budget.on_exceed !== 'string' || !VALID_BUDGET_ON_EXCEED.includes(budget.on_exceed)) {
+      errors.push(`budget.on_exceed must be one of: ${VALID_BUDGET_ON_EXCEED.join(', ')}`);
+    }
+  }
+
+  if (budget.cost_rates !== undefined) {
+    if (!budget.cost_rates || typeof budget.cost_rates !== 'object' || Array.isArray(budget.cost_rates)) {
+      errors.push('budget.cost_rates must be an object');
+    } else {
+      for (const [model, rates] of Object.entries(budget.cost_rates)) {
+        if (typeof model !== 'string' || !model.trim()) {
+          errors.push('budget.cost_rates model keys must be non-empty strings');
+          continue;
+        }
+        if (!rates || typeof rates !== 'object' || Array.isArray(rates)) {
+          errors.push(`budget.cost_rates.${model} must be an object`);
+          continue;
+        }
+        validateBudgetCostRate(`budget.cost_rates.${model}.input_per_1m`, rates.input_per_1m, errors);
+        validateBudgetCostRate(`budget.cost_rates.${model}.output_per_1m`, rates.output_per_1m, errors);
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function validateBudgetUsdLimit(path, value, errors) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    errors.push(`${path} must be a finite number when provided`);
+    return;
+  }
+  if (value <= 0) {
+    errors.push(`${path} must be greater than 0 when provided`);
+  }
+}
+
+function validateBudgetCostRate(path, value, errors) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    errors.push(`${path} must be a finite number`);
+    return;
+  }
+  if (value < 0) {
+    errors.push(`${path} must be greater than or equal to 0`);
+  }
+}
+
 export function validateSchedulesConfig(schedules, roles) {
   const errors = [];
 

package/src/lib/report.js

@@ -45,6 +45,19 @@ function normalizeBudgetStatus(budgetStatus) {
   if (Number.isFinite(budgetStatus.remaining_usd)) {
     normalized.remaining_usd = budgetStatus.remaining_usd;
   }
+  // DEC-BUDGET-WARN-004: preserve warn-mode and exhaustion fields
+  if (budgetStatus.warn_mode === true) {
+    normalized.warn_mode = true;
+  }
+  if (budgetStatus.exhausted === true) {
+    normalized.exhausted = true;
+  }
+  if (budgetStatus.exhausted_at) {
+    normalized.exhausted_at = budgetStatus.exhausted_at;
+  }
+  if (budgetStatus.exhausted_after_turn) {
+    normalized.exhausted_after_turn = budgetStatus.exhausted_after_turn;
+  }
 
   return Object.keys(normalized).length > 0 ? normalized : null;
 }
@@ -890,8 +903,9 @@ export function formatGovernanceReportText(report) {
     ];
 
     if (run.budget_status) {
+      const warnTag = run.budget_status.warn_mode ? ' [OVER BUDGET]' : '';
       lines.push(
-        `Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}`,
+        `Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}${warnTag}`,
       );
     }
 
@@ -1300,7 +1314,8 @@ export function formatGovernanceReportMarkdown(report) {
     ];
 
     if (run.budget_status) {
-      lines.push(`- Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}`);
+      const warnTag = run.budget_status.warn_mode ? ' **[OVER BUDGET]**' : '';
+      lines.push(`- Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}${warnTag}`);
     }
 
     if (run.created_at) {

package/src/lib/run-events.js

@@ -23,6 +23,7 @@ export const VALID_RUN_EVENTS = [
   'escalation_resolved',
   'gate_pending',
   'gate_approved',
+  'budget_exceeded_warn',
 ];
 
 /**