agentxchain 2.59.0 → 2.61.0

package/README.md

@@ -74,7 +74,7 @@ agentxchain status
 agentxchain step --role pm
 ```
 
-If you skipped `--goal` during scaffold, set `project.goal` in `agentxchain.json` before the first governed turn instead of re-running init in place.
+If you skipped `--goal` during scaffold, run `agentxchain config --set project.goal "Build an API change planner for release teams"` before the first governed turn instead of re-running init in place.
 
 The default governed dev runtime is `claude --print --dangerously-skip-permissions` with stdin prompt delivery. The non-interactive governed path needs write access, so do not pretend bare `claude --print` is sufficient for unattended implementation turns. If your local coding agent uses a different launch contract, set it during scaffold creation:
 

package/bin/agentxchain.js

@@ -192,7 +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('--set <key_value>', 'Set a config value (e.g. --set "rules.max_consecutive_claims 3")')
+  .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.59.0",
+  "version": "2.61.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/config.js

@@ -2,31 +2,43 @@ import { readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
-import { loadConfig, CONFIG_FILE } from '../lib/config.js';
+import { loadProjectContext, CONFIG_FILE } from '../lib/config.js';
 import { validateConfigSchema } from '../lib/schema.js';
+import { validateV4Config } from '../lib/normalized-config.js';
 
 export async function configCommand(opts) {
-  const result = loadConfig();
-  if (!result) {
+  const context = loadProjectContext();
+  if (!context) {
     console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
     process.exit(1);
   }
 
-  const { root, config } = result;
+  const { root, rawConfig, version } = context;
+  const config = rawConfig;
   const configPath = join(root, CONFIG_FILE);
 
+  if (version === 4 && opts.addAgent) {
+    printLegacyOnlyMutationError('--add-agent');
+    return;
+  }
+
   if (opts.addAgent) {
     await addAgent(config, configPath);
     return;
   }
 
+  if (version === 4 && opts.removeAgent) {
+    printLegacyOnlyMutationError('--remove-agent');
+    return;
+  }
+
   if (opts.removeAgent) {
     removeAgent(config, configPath, opts.removeAgent);
     return;
   }
 
   if (opts.set) {
-    setSetting(config, configPath, opts.set);
+    setSetting(config, configPath, opts.set, { version, root });
     return;
   }
 
@@ -35,10 +47,15 @@ export async function configCommand(opts) {
     return;
   }
 
-  printConfig(config);
+  if (version === 4) {
+    printGovernedConfig(config);
+    return;
+  }
+
+  printLegacyConfig(config);
 }
 
-function printConfig(config) {
+function printLegacyConfig(config) {
   console.log('');
   console.log(chalk.bold('  AgentXchain Config'));
   console.log(chalk.dim('  ' + '─'.repeat(40)));
@@ -69,6 +86,32 @@ function printConfig(config) {
   console.log('');
 }
 
+function printGovernedConfig(config) {
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Governed Config'));
+  console.log(chalk.dim('  ' + '─'.repeat(40)));
+  console.log('');
+  console.log(`  ${chalk.dim('Project:')}   ${config.project?.name || '(unknown)'}`);
+  console.log(`  ${chalk.dim('Project ID:')} ${config.project?.id || '(unknown)'}`);
+  console.log(`  ${chalk.dim('Goal:')}      ${config.project?.goal || '(not set)'}`);
+  console.log(`  ${chalk.dim('Template:')}  ${config.template || 'generic'}`);
+  console.log(`  ${chalk.dim('Roles:')}     ${Object.keys(config.roles || {}).length}`);
+  console.log(`  ${chalk.dim('Runtimes:')}  ${Object.keys(config.runtimes || {}).length}`);
+  console.log('');
+  console.log(chalk.dim('  Commands:'));
+  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`);
+  console.log('');
+}
+
+function printLegacyOnlyMutationError(flag) {
+  console.log(chalk.red(`  ${flag} is legacy-only.`));
+  console.log(chalk.dim('  Governed repos use roles and runtimes instead of legacy v3 agents.'));
+  console.log(chalk.dim('  Use `agentxchain config --set <path> <value>` for governed config changes.'));
+  process.exit(1);
+}
+
 async function addAgent(config, configPath) {
   const answers = await inquirer.prompt([
     {
@@ -117,16 +160,15 @@ function removeAgent(config, configPath, id) {
   console.log('');
 }
 
-function setSetting(config, configPath, keyValPair) {
-  const parts = keyValPair.split(/\s+/);
-  if (parts.length < 2) {
+function setSetting(config, configPath, keyValPair, context) {
+  const parsed = parseSetInput(keyValPair);
+  if (!parsed) {
     console.log(chalk.red('  Usage: agentxchain config --set <key> <value>'));
-    console.log(chalk.dim('  Example: agentxchain config --set rules.max_consecutive_claims 3'));
+    console.log(chalk.dim('  Example: agentxchain config --set project.goal "Build a governed CLI"'));
     process.exit(1);
   }
 
-  const key = parts[0];
-  const rawVal = parts.slice(1).join(' ');
+  const { key, rawVal } = parsed;
   const segments = key.split('.');
   const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
 
@@ -152,7 +194,7 @@ function setSetting(config, configPath, keyValPair) {
   else if (!isNaN(rawVal) && rawVal !== '') val = Number(rawVal);
 
   target[lastKey] = val;
-  const validation = validateConfigSchema(config);
+  const validation = validateEditedConfig(config, context);
   if (!validation.ok) {
     target[lastKey] = oldVal;
     if (oldVal === undefined) {
@@ -168,3 +210,34 @@ function setSetting(config, configPath, keyValPair) {
   if (oldVal !== undefined) console.log(chalk.dim(`    (was: ${oldVal})`));
   console.log('');
 }
+
+function parseSetInput(input) {
+  if (Array.isArray(input)) {
+    if (input.length >= 2) {
+      return { key: input[0], rawVal: input.slice(1).join(' ') };
+    }
+    if (input.length === 1 && typeof input[0] === 'string') {
+      const parts = input[0].trim().split(/\s+/);
+      if (parts.length >= 2) {
+        return { key: parts[0], rawVal: parts.slice(1).join(' ') };
+      }
+    }
+    return null;
+  }
+
+  if (typeof input === 'string') {
+    const parts = input.trim().split(/\s+/);
+    if (parts.length >= 2) {
+      return { key: parts[0], rawVal: parts.slice(1).join(' ') };
+    }
+  }
+
+  return null;
+}
+
+function validateEditedConfig(config, context) {
+  if (context.version === 4) {
+    return validateV4Config(config, context.root);
+  }
+  return validateConfigSchema(config);
+}

package/src/commands/init.js

@@ -978,7 +978,8 @@ async function initGoverned(opts) {
   console.log('');
   if (!config?.project?.goal) {
     console.log(`  ${chalk.dim('Tip:')} Add a project goal to guide agent context:`);
-    console.log(`    ${chalk.bold('agentxchain init --governed --goal "Build a ..."')} ${chalk.dim('# or set project.goal in agentxchain.json')}`);
+    console.log(`    ${chalk.bold('agentxchain init --governed --goal "Build a ..."')} ${chalk.dim('# preferred during scaffold')}`);
+    console.log(`    ${chalk.bold('agentxchain config --set project.goal "Build a ..."')} ${chalk.dim('# add it later without hand-editing JSON')}`);
     console.log('');
   }
   console.log(`  ${chalk.dim('Guide:')} https://agentxchain.dev/docs/getting-started`);

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) {
@@ -1938,7 +1938,7 @@ export function assignGovernedTurn(root, config, roleId) {
 
   // 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` };
+    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` };
   }
 
   // DEC-PARALLEL-011: Budget reservation
@@ -2675,7 +2675,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)`,
         },

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'];
 
 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(', ')} (warn is not implemented)`);
+    }
+  }
+
+  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 = [];