agentxchain 2.83.0 → 2.84.0

package/package.json

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

package/scripts/model-compatibility-probe.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+/**
+ * Model Compatibility Probe — api_proxy + proposed write authority
+ *
+ * Dispatches a lightweight governed turn to each target model and records
+ * whether the model can produce a well-formed turn result with proposed_changes.
+ *
+ * Usage:
+ *   node cli/scripts/model-compatibility-probe.mjs
+ *   node cli/scripts/model-compatibility-probe.mjs --json
+ *
+ * Requires ANTHROPIC_API_KEY in the environment.
+ */
+
+const ANTHROPIC_ENDPOINT = 'https://api.anthropic.com/v1/messages';
+
+const SYSTEM_PROMPT = [
+  'You are acting as a governed agent in an AgentXchain protocol run.',
+  'Your task and rules are described in the user message.',
+  'You MUST respond with a valid JSON object matching the turn result schema provided in the prompt.',
+  'Do NOT wrap the JSON in markdown code fences. Respond with raw JSON only.',
+].join('\n');
+
+const PROBE_PROMPT = `You are a governed agent with write_authority: "proposed".
+
+Your task: create a single file called \`probe-result.txt\` containing the text "model compatibility probe passed".
+
+Respond with a single raw JSON object (no markdown fences) matching this exact schema:
+
+{
+  "schema_version": "1.0",
+  "run_id": "probe_run",
+  "turn_id": "probe_turn_001",
+  "role": "dev",
+  "runtime_id": "probe_runtime",
+  "status": "completed",
+  "summary": "Created probe-result.txt for model compatibility verification.",
+  "decisions": [],
+  "objections": [],
+  "files_changed": ["probe-result.txt"],
+  "verification": { "status": "pass", "evidence": "File created successfully." },
+  "artifact": { "type": "patch", "ref": null },
+  "proposed_next_role": "human",
+  "proposed_changes": [
+    {
+      "path": "probe-result.txt",
+      "action": "create",
+      "content": "model compatibility probe passed"
+    }
+  ]
+}
+
+Return ONLY the JSON object. No explanation, no markdown fences, no extra text.`;
+
+const MODELS = [
+  { id: 'claude-haiku-4-5-20251001', label: 'Haiku 4.5', maxTokens: 2048, costInput: 1.00, costOutput: 5.00 },
+  { id: 'claude-sonnet-4-6', label: 'Sonnet 4.6', maxTokens: 2048, costInput: 3.00, costOutput: 15.00 },
+];
+
+function extractTurnResult(text) {
+  if (typeof text !== 'string' || !text.trim()) {
+    return { ok: false, error: 'Empty response text' };
+  }
+  const trimmed = text.trim();
+
+  // Direct JSON parse
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === 'object' && parsed.schema_version) {
+      return { ok: true, turnResult: parsed, method: 'direct' };
+    }
+  } catch { /* not pure JSON */ }
+
+  // Markdown fence extraction
+  const fenceMatch = trimmed.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+  if (fenceMatch) {
+    try {
+      const parsed = JSON.parse(fenceMatch[1].trim());
+      if (parsed && typeof parsed === 'object' && parsed.schema_version) {
+        return { ok: true, turnResult: parsed, method: 'fence' };
+      }
+    } catch { /* invalid JSON inside fence */ }
+  }
+
+  // Substring extraction
+  const jsonStart = trimmed.indexOf('{');
+  const jsonEnd = trimmed.lastIndexOf('}');
+  if (jsonStart >= 0 && jsonEnd > jsonStart) {
+    try {
+      const parsed = JSON.parse(trimmed.slice(jsonStart, jsonEnd + 1));
+      if (parsed && typeof parsed === 'object' && parsed.schema_version) {
+        return { ok: true, turnResult: parsed, method: 'substring' };
+      }
+    } catch { /* not valid JSON */ }
+  }
+
+  return { ok: false, error: 'Could not extract structured turn result JSON' };
+}
+
+function validateProposedChanges(turnResult) {
+  const changes = turnResult?.proposed_changes;
+  if (!Array.isArray(changes) || changes.length === 0) {
+    return { present: false, wellFormed: false, reason: 'proposed_changes missing or empty' };
+  }
+  for (const c of changes) {
+    if (!c.path || typeof c.path !== 'string') {
+      return { present: true, wellFormed: false, reason: `entry missing path` };
+    }
+    if (!['create', 'modify', 'delete'].includes(c.action)) {
+      return { present: true, wellFormed: false, reason: `invalid action: ${c.action}` };
+    }
+    if ((c.action === 'create' || c.action === 'modify') && (!c.content || typeof c.content !== 'string')) {
+      return { present: true, wellFormed: false, reason: `${c.action} entry missing content for ${c.path}` };
+    }
+  }
+  return { present: true, wellFormed: true, count: changes.length };
+}
+
+async function probeModel(model, apiKey) {
+  const startMs = Date.now();
+  const body = {
+    model: model.id,
+    max_tokens: model.maxTokens,
+    system: SYSTEM_PROMPT,
+    messages: [{ role: 'user', content: PROBE_PROMPT }],
+  };
+
+  let responseData;
+  let rawError = null;
+
+  try {
+    const res = await fetch(ANTHROPIC_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const errorBody = await res.text().catch(() => '');
+      rawError = `HTTP ${res.status}: ${errorBody.slice(0, 500)}`;
+      return {
+        model: model.id,
+        label: model.label,
+        extraction_success: false,
+        schema_valid: false,
+        proposed_changes_present: false,
+        proposed_changes_well_formed: false,
+        latency_ms: Date.now() - startMs,
+        cost_usd: 0,
+        classification: 'unsupported',
+        raw_error: rawError,
+      };
+    }
+
+    responseData = await res.json();
+  } catch (err) {
+    return {
+      model: model.id,
+      label: model.label,
+      extraction_success: false,
+      schema_valid: false,
+      proposed_changes_present: false,
+      proposed_changes_well_formed: false,
+      latency_ms: Date.now() - startMs,
+      cost_usd: 0,
+      classification: 'unsupported',
+      raw_error: err.message,
+    };
+  }
+
+  const latencyMs = Date.now() - startMs;
+
+  // Extract text from Anthropic response
+  const textBlock = responseData?.content?.find(b => b.type === 'text');
+  const responseText = textBlock?.text || '';
+
+  // Extract turn result
+  const extraction = extractTurnResult(responseText);
+
+  // Calculate cost
+  const usage = responseData?.usage || {};
+  const inputTokens = usage.input_tokens || 0;
+  const outputTokens = usage.output_tokens || 0;
+  const costUsd = (inputTokens / 1_000_000) * model.costInput + (outputTokens / 1_000_000) * model.costOutput;
+
+  if (!extraction.ok) {
+    return {
+      model: model.id,
+      label: model.label,
+      extraction_success: false,
+      extraction_method: null,
+      schema_valid: false,
+      proposed_changes_present: false,
+      proposed_changes_well_formed: false,
+      latency_ms: latencyMs,
+      input_tokens: inputTokens,
+      output_tokens: outputTokens,
+      cost_usd: Math.round(costUsd * 1_000_000) / 1_000_000,
+      classification: 'unsupported',
+      raw_error: extraction.error,
+      response_preview: responseText.slice(0, 300),
+    };
+  }
+
+  const tr = extraction.turnResult;
+  const schemaValid = typeof tr.schema_version === 'string' && tr.schema_version === '1.0';
+  const pcValidation = validateProposedChanges(tr);
+
+  let classification;
+  if (schemaValid && pcValidation.present && pcValidation.wellFormed) {
+    classification = 'reliable';
+  } else if (extraction.ok && (!pcValidation.present || !pcValidation.wellFormed)) {
+    classification = 'inconsistent';
+  } else {
+    classification = 'unsupported';
+  }
+
+  return {
+    model: model.id,
+    label: model.label,
+    extraction_success: true,
+    extraction_method: extraction.method,
+    schema_valid: schemaValid,
+    proposed_changes_present: pcValidation.present,
+    proposed_changes_well_formed: pcValidation.wellFormed,
+    proposed_changes_count: pcValidation.count || 0,
+    latency_ms: latencyMs,
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cost_usd: Math.round(costUsd * 1_000_000) / 1_000_000,
+    classification,
+    raw_error: pcValidation.reason || null,
+    status_returned: tr.status,
+    summary_returned: typeof tr.summary === 'string' ? tr.summary.slice(0, 100) : null,
+  };
+}
+
+async function main() {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    console.error('ANTHROPIC_API_KEY not set');
+    process.exit(1);
+  }
+
+  const jsonMode = process.argv.includes('--json');
+
+  if (!jsonMode) {
+    console.log('AgentXchain Model Compatibility Probe');
+    console.log('Provider: Anthropic | Write Authority: proposed');
+    console.log('─'.repeat(60));
+  }
+
+  const results = [];
+
+  for (const model of MODELS) {
+    if (!jsonMode) {
+      process.stdout.write(`Probing ${model.label} (${model.id})... `);
+    }
+
+    const result = await probeModel(model, apiKey);
+    results.push(result);
+
+    if (!jsonMode) {
+      const icon = result.classification === 'reliable' ? '✓' : result.classification === 'inconsistent' ? '~' : '✗';
+      console.log(`${icon} ${result.classification} (${result.latency_ms}ms, $${result.cost_usd})`);
+      if (result.raw_error) {
+        console.log(`  └─ ${result.raw_error}`);
+      }
+    }
+  }
+
+  const output = {
+    probe_version: '1.0',
+    timestamp: new Date().toISOString(),
+    provider: 'anthropic',
+    write_authority: 'proposed',
+    models: results,
+    total_cost_usd: results.reduce((s, r) => s + r.cost_usd, 0),
+  };
+
+  if (jsonMode) {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log('─'.repeat(60));
+    console.log(`Total cost: $${output.total_cost_usd.toFixed(6)}`);
+    console.log();
+    console.log('Matrix:');
+    for (const r of results) {
+      console.log(`  ${r.label.padEnd(12)} ${r.classification.padEnd(14)} extraction=${r.extraction_success} schema=${r.schema_valid} proposed=${r.proposed_changes_well_formed}`);
+    }
+  }
+
+  // Write results to .planning/ for durable reference
+  const { writeFileSync, mkdirSync } = await import('node:fs');
+  const { dirname, join } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const outPath = join(repoRoot, '.planning', 'MODEL_COMPATIBILITY_RESULTS.json');
+  writeFileSync(outPath, JSON.stringify(output, null, 2) + '\n');
+  if (!jsonMode) {
+    console.log(`\nResults written to: .planning/MODEL_COMPATIBILITY_RESULTS.json`);
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/release-bump.sh

@@ -62,7 +62,6 @@ ALLOWED_RELEASE_PATHS=(
   "website-v2/docs/protocol-implementor-guide.mdx"
   ".planning/LAUNCH_EVIDENCE_REPORT.md"
   "website-v2/static/llms.txt"
-  "website-v2/static/sitemap.xml"
   "cli/homebrew/agentxchain.rb"
   "cli/homebrew/README.md"
 )
@@ -148,9 +147,9 @@ if [[ ! -f "${REPO_ROOT}/${RELEASE_DOC_PATH}" ]]; then
   SURFACE_ERRORS+=("release notes page missing: ${RELEASE_DOC_PATH}")
 fi
 
-# 4c. Docs sidebar links the release page
-if ! grep -q "'releases/${RELEASE_DOC_ID}'" "${REPO_ROOT}/website-v2/sidebars.ts" 2>/dev/null; then
-  SURFACE_ERRORS+=("sidebars.ts does not link 'releases/${RELEASE_DOC_ID}'")
+# 4c. Docs sidebar auto-generates releases from dirName (release doc existence is sufficient)
+if ! grep -q "dirName.*releases" "${REPO_ROOT}/website-v2/sidebars.ts" 2>/dev/null; then
+  SURFACE_ERRORS+=("sidebars.ts does not auto-generate releases (missing dirName: 'releases')")
 fi
 
 # 4d. Homepage hero badge shows target version
@@ -181,10 +180,7 @@ if ! grep -q "${CURRENT_RELEASE_ROUTE}" "${REPO_ROOT}/website-v2/static/llms.txt
   SURFACE_ERRORS+=("website-v2/static/llms.txt does not list '${CURRENT_RELEASE_ROUTE}'")
 fi
 
-# 4i. sitemap.xml must list the current release notes route
-if ! grep -q "${CURRENT_RELEASE_ROUTE}" "${REPO_ROOT}/website-v2/static/sitemap.xml" 2>/dev/null; then
-  SURFACE_ERRORS+=("website-v2/static/sitemap.xml does not list '${CURRENT_RELEASE_ROUTE}'")
-fi
+# 4i. sitemap.xml is now auto-generated by Docusaurus at build time — no static file check needed
 
 if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
   echo "FAIL: ${#SURFACE_ERRORS[@]} version-surface(s) not aligned to ${TARGET_VERSION}:" >&2
@@ -194,7 +190,7 @@ if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
   echo "create release identity when governed surfaces are stale." >&2
   exit 1
 fi
-echo "  OK: all 9 governed version surfaces reference ${TARGET_VERSION}"
+echo "  OK: all 8 governed version surfaces reference ${TARGET_VERSION}"
 
 # 5. Auto-align Homebrew mirror to target version
 # The formula URL and README version/tarball are updated automatically.

package/src/commands/config.js

@@ -219,6 +219,12 @@ function setSetting(config, configPath, keyValPair, context) {
   console.log('');
   console.log(chalk.green(`  ✓ Set ${chalk.bold(key)} = ${val}`));
   if (oldVal !== undefined) console.log(chalk.dim(`    (was: ${oldVal})`));
+  if ((validation.warnings || []).length > 0) {
+    console.log(chalk.yellow('  Warnings:'));
+    for (const warning of validation.warnings) {
+      console.log(chalk.dim(`    - ${warning}`));
+    }
+  }
   console.log('');
 }
 

package/src/commands/doctor.js

@@ -51,8 +51,11 @@ function governedDoctor(root, rawConfig, opts) {
 
   // 1. Config validation
   const configResult = loadNormalizedConfig(rawConfig, root);
-  if (configResult.ok) {
+  if (configResult.ok && (configResult.warnings || []).length === 0) {
     checks.push({ id: 'config_valid', name: 'Config validation', level: 'pass', detail: 'Config loads and validates' });
+  } else if (configResult.ok) {
+    const warningSummary = configResult.warnings.slice(0, 2).join('; ');
+    checks.push({ id: 'config_valid', name: 'Config validation', level: 'warn', detail: warningSummary });
   } else {
     const errorSummary = configResult.errors.slice(0, 3).join('; ');
     checks.push({ id: 'config_valid', name: 'Config validation', level: 'fail', detail: errorSummary });

package/src/lib/normalized-config.js

@@ -330,9 +330,10 @@ export function detectConfigVersion(raw) {
  */
 export function validateV4Config(data, projectRoot) {
   const errors = [];
+  const warnings = [];
 
   if (!data || typeof data !== 'object') {
-    return { ok: false, errors: ['Config must be a JSON object'] };
+    return { ok: false, errors: ['Config must be a JSON object'], warnings };
   }
 
   // Top-level required sections
@@ -555,7 +556,80 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...timeoutValidation.errors);
   }
 
-  return { ok: errors.length === 0, errors };
+  warnings.push(...collectRemoteReviewOnlyGateWarnings(data));
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+export function collectRemoteReviewOnlyGateWarnings(data) {
+  const warnings = [];
+  const routing = data?.routing;
+  const gates = data?.gates;
+  const roles = data?.roles;
+  const runtimes = data?.runtimes;
+
+  if (!routing || !gates || !roles || !runtimes) {
+    return warnings;
+  }
+
+  for (const [phase, route] of Object.entries(routing)) {
+    const exitGateId = route?.exit_gate;
+    if (!exitGateId || !gates[exitGateId]) {
+      continue;
+    }
+
+    const requiredFiles = Array.isArray(gates[exitGateId]?.requires_files)
+      ? gates[exitGateId].requires_files.filter(filePath => typeof filePath === 'string' && filePath.trim())
+      : [];
+    if (requiredFiles.length === 0) {
+      continue;
+    }
+
+    const candidateRoleIds = [
+      route?.entry_role,
+      ...(Array.isArray(route?.allowed_next_roles) ? route.allowed_next_roles : []),
+    ].filter((roleId) => roleId && roleId !== 'human');
+
+    if (candidateRoleIds.length === 0) {
+      continue;
+    }
+
+    const candidateRoles = [...new Set(candidateRoleIds)]
+      .map((roleId) => {
+        const role = roles[roleId];
+        const runtime = role?.runtime ? runtimes[role.runtime] : null;
+        if (!role || !runtime) {
+          return null;
+        }
+        return { roleId, role, runtime };
+      })
+      .filter(Boolean);
+
+    if (candidateRoles.length === 0) {
+      continue;
+    }
+
+    const hasFileProducingRole = candidateRoles.some(({ role }) =>
+      role.write_authority === 'authoritative' || role.write_authority === 'proposed');
+    if (hasFileProducingRole) {
+      continue;
+    }
+
+    const allRemoteReviewOnly = candidateRoles.every(({ role, runtime }) =>
+      role.write_authority === 'review_only' && (runtime.type === 'api_proxy' || runtime.type === 'remote_agent'));
+    if (!allRemoteReviewOnly) {
+      continue;
+    }
+
+    const roleSummary = candidateRoles
+      .map(({ roleId, runtime }) => `${roleId}:${runtime.type}`)
+      .join(', ');
+    warnings.push(
+      `Routing "${phase}" exits through gate "${exitGateId}" with requires_files (${requiredFiles.join(', ')}) but all participating roles are review_only remote runtimes (${roleSummary}). Those files cannot be produced through governed turns; add a proposed/authoritative writer, remove the gate files, or expect operator-managed out-of-band artifacts.`,
+    );
+  }
+
+  return warnings;
 }
 
 export function validateBudgetConfig(budget) {
@@ -1133,6 +1207,7 @@ export function loadNormalizedConfig(raw, projectRoot) {
       ok: false,
       normalized: null,
       errors: ['Unrecognized config format. Expected version: 3 or schema_version: "1.0" / 4'],
+      warnings: [],
       version: null,
     };
   }
@@ -1152,17 +1227,17 @@ export function loadNormalizedConfig(raw, projectRoot) {
       }
     }
     if (errors.length > 0) {
-      return { ok: false, normalized: null, errors, version: 3 };
+      return { ok: false, normalized: null, errors, warnings: [], version: 3 };
     }
-    return { ok: true, normalized: normalizeV3(raw), errors: [], version: 3 };
+    return { ok: true, normalized: normalizeV3(raw), errors: [], warnings: [], version: 3 };
   }
 
   if (version === 4) {
     const validation = validateV4Config(raw, projectRoot || null);
     if (!validation.ok) {
-      return { ok: false, normalized: null, errors: validation.errors, version: 4 };
+      return { ok: false, normalized: null, errors: validation.errors, warnings: validation.warnings || [], version: 4 };
     }
-    return { ok: true, normalized: normalizeV4(raw), errors: [], version: 4 };
+    return { ok: true, normalized: normalizeV4(raw), errors: [], warnings: validation.warnings || [], version: 4 };
   }
 }
 

package/src/lib/validation.js

@@ -9,6 +9,7 @@ import {
   validateAcceptanceHintCompletion,
   validateGovernedWorkflowKit,
 } from './governed-templates.js';
+import { collectRemoteReviewOnlyGateWarnings } from './normalized-config.js';
 
 const DEFAULT_REQUIRED_FILES = [
   '.planning/PROJECT.md',
@@ -115,6 +116,9 @@ export function validateGovernedProject(root, rawConfig, config, opts = {}) {
   errors.push(...workflowKit.errors);
   warnings.push(...workflowKit.warnings);
 
+  // Config-shape warnings (dead-end gates, etc.) — mirrors doctor/config --set surfaces
+  warnings.push(...collectRemoteReviewOnlyGateWarnings(rawConfig));
+
   const mustExist = [
     config.files?.state || '.agentxchain/state.json',
     config.files?.history || '.agentxchain/history.jsonl',