agentxchain 2.2.0 → 2.4.0

package/src/lib/normalized-config.js

@@ -13,9 +13,11 @@
  */
 
 import { validateHooksConfig } from './hook-runner.js';
+import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
-const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy'];
+const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp'];
+const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai'];
 const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_PHASES = ['planning', 'implementation', 'qa'];
 const VALID_API_PROXY_RETRY_JITTER = ['none', 'full'];
@@ -44,6 +46,36 @@ const VALID_API_PROXY_PREFLIGHT_FIELDS = [
   'safety_margin_tokens',
 ];
 
+function validateMcpRuntime(runtimeId, runtime, errors) {
+  const command = runtime?.command;
+
+  if (typeof command === 'string') {
+    if (!command.trim()) {
+      errors.push(`Runtime "${runtimeId}": mcp command must be a non-empty string`);
+    }
+  } else if (Array.isArray(command)) {
+    if (command.length === 0 || command.some((part) => typeof part !== 'string' || !part.trim())) {
+      errors.push(`Runtime "${runtimeId}": mcp command array must contain at least one non-empty string and no empty parts`);
+    }
+  } else {
+    errors.push(`Runtime "${runtimeId}": mcp requires "command" as a string or string array`);
+  }
+
+  if ('args' in runtime) {
+    if (!Array.isArray(runtime.args) || runtime.args.some((part) => typeof part !== 'string')) {
+      errors.push(`Runtime "${runtimeId}": mcp args must be an array of strings`);
+    }
+  }
+
+  if ('tool_name' in runtime && (typeof runtime.tool_name !== 'string' || !runtime.tool_name.trim())) {
+    errors.push(`Runtime "${runtimeId}": mcp tool_name must be a non-empty string`);
+  }
+
+  if ('cwd' in runtime && (typeof runtime.cwd !== 'string' || !runtime.cwd.trim())) {
+    errors.push(`Runtime "${runtimeId}": mcp cwd must be a non-empty string`);
+  }
+}
+
 function validateApiProxyRetryPolicy(runtimeId, retryPolicy, errors) {
   if (!retryPolicy || typeof retryPolicy !== 'object' || Array.isArray(retryPolicy)) {
     errors.push(`Runtime "${runtimeId}": retry_policy must be an object`);
@@ -146,6 +178,12 @@ function validateApiProxyPreflightTokenization(runtimeId, runtime, errors) {
   }
 
   if (preflight.enabled === true) {
+    if (!SUPPORTED_TOKEN_COUNTER_PROVIDERS.includes(runtime.provider)) {
+      errors.push(
+        `Runtime "${runtimeId}": preflight_tokenization tokenizer "provider_local" is not supported for provider "${runtime.provider}". Supported providers: ${SUPPORTED_TOKEN_COUNTER_PROVIDERS.join(', ')}`
+      );
+    }
+
     if (!Number.isInteger(runtime.context_window_tokens) || runtime.context_window_tokens <= 0) {
       errors.push(`Runtime "${runtimeId}": context_window_tokens is required when preflight_tokenization.enabled is true`);
       return;
@@ -239,6 +277,8 @@ export function validateV4Config(data, projectRoot) {
       if (rt.type === 'api_proxy') {
         if (typeof rt.provider !== 'string' || !rt.provider.trim()) {
           errors.push(`Runtime "${id}": api_proxy requires "provider" (e.g. "anthropic", "openai")`);
+        } else if (!VALID_API_PROXY_PROVIDERS.includes(rt.provider)) {
+          errors.push(`Runtime "${id}": api_proxy provider must be one of: ${VALID_API_PROXY_PROVIDERS.join(', ')}`);
         }
         if (typeof rt.model !== 'string' || !rt.model.trim()) {
           errors.push(`Runtime "${id}": api_proxy requires "model" (e.g. "claude-sonnet-4-6")`);
@@ -253,6 +293,9 @@ export function validateV4Config(data, projectRoot) {
           validateApiProxyPreflightTokenization(id, rt, errors);
         }
       }
+      if (rt.type === 'mcp') {
+        validateMcpRuntime(id, rt, errors);
+      }
     }
   }
 

package/src/lib/protocol-conformance.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_FIXTURE_ROOT = resolve(__dirname, '..', '..', '..', '.agentxchain-conformance', 'fixtures');
-const VALID_RESPONSE_STATUSES = new Set(['pass', 'fail', 'error']);
+const VALID_RESPONSE_STATUSES = new Set(['pass', 'fail', 'error', 'not_implemented']);
 const VALID_TIERS = new Set([1, 2, 3]);
 
 function readJsonFile(filePath) {
@@ -119,16 +119,18 @@ function createTierSummary(status = 'skipped', note = null) {
     fixtures_passed: 0,
     fixtures_failed: 0,
     fixtures_errored: 0,
+    fixtures_not_implemented: 0,
     surfaces: {},
     failures: [],
     errors: [],
+    not_implemented: [],
     ...(note ? { note } : {}),
   };
 }
 
 function ensureSurfaceSummary(tierSummary, surface) {
   if (!tierSummary.surfaces[surface]) {
-    tierSummary.surfaces[surface] = { passed: 0, failed: 0, errored: 0 };
+    tierSummary.surfaces[surface] = { passed: 0, failed: 0, errored: 0, not_implemented: 0 };
   }
   return tierSummary.surfaces[surface];
 }
@@ -149,7 +151,7 @@ function executeFixture(targetRoot, adapterCommand, fixture) {
     };
   }
 
-  if (![0, 1, 2].includes(result.status ?? -1)) {
+  if (![0, 1, 2, 3].includes(result.status ?? -1)) {
     return {
       status: 'error',
       message: `Adapter exited with unsupported status ${result.status}`,
@@ -182,7 +184,7 @@ function executeFixture(targetRoot, adapterCommand, fixture) {
     };
   }
 
-  const expectedExitCode = parsed.status === 'pass' ? 0 : parsed.status === 'fail' ? 1 : 2;
+  const expectedExitCode = parsed.status === 'pass' ? 0 : parsed.status === 'fail' ? 1 : parsed.status === 'not_implemented' ? 3 : 2;
   if (result.status !== expectedExitCode) {
     return {
       status: 'error',
@@ -210,6 +212,17 @@ export function verifyProtocolConformance({
 
   const resolvedTargetRoot = resolve(targetRoot);
   const capabilities = loadCapabilities(resolvedTargetRoot);
+
+  // Enforce surface claims when capabilities.surfaces exists and --surface is requested
+  if (surface && capabilities.surfaces && typeof capabilities.surfaces === 'object') {
+    if (!capabilities.surfaces[surface]) {
+      throw new Error(
+        `Surface "${surface}" is not claimed in capabilities.json. ` +
+        `Claimed surfaces: ${Object.keys(capabilities.surfaces).join(', ')}`
+      );
+    }
+  }
+
   const fixtureEntries = selectFixtureFiles(fixtureRoot, requestedTier, surface);
   const claimedTiers = new Set(capabilities.tiers);
   const report = {
@@ -250,6 +263,17 @@ export function verifyProtocolConformance({
       continue;
     }
 
+    if (adapterResult.status === 'not_implemented') {
+      tierSummary.fixtures_not_implemented += 1;
+      surfaceSummary.not_implemented += 1;
+      tierSummary.not_implemented.push({
+        fixture_id: fixture.fixture_id,
+        surface: fixture.surface,
+        message: adapterResult.message || 'Not implemented',
+      });
+      continue;
+    }
+
     if (adapterResult.status === 'fail') {
       tierSummary.fixtures_failed += 1;
       surfaceSummary.failed += 1;

package/src/lib/repo-observer.js

@@ -25,6 +25,7 @@ import { join } from 'path';
 const OPERATIONAL_PATH_PREFIXES = [
   '.agentxchain/dispatch/',
   '.agentxchain/staging/',
+  '.agentxchain/intake/',
   '.agentxchain/locks/',
   '.agentxchain/transactions/',
 ];
@@ -269,13 +270,13 @@ export function buildObservedArtifact(observation, baseline) {
  *
  * Normalization rules (spec §5.3):
  *   - manual + external pass → attested_pass
- *   - local_cli + pass + machine evidence all zero → pass
- *   - local_cli + pass + no reproducible evidence → not_reproducible
+ *   - executable runtime + pass + machine evidence all zero → pass
+ *   - executable runtime + pass + no reproducible evidence → not_reproducible
  *   - any external fail → fail
  *   - external skipped → skipped
  *
  * @param {object} verification — the actor-supplied verification object
- * @param {string} runtimeType — 'manual' | 'local_cli' | 'api_proxy'
+ * @param {string} runtimeType — 'manual' | 'local_cli' | 'api_proxy' | 'mcp'
  * @returns {{ status: string, reason: string, reproducible: boolean }}
  */
 export function normalizeVerification(verification, runtimeType) {
@@ -298,18 +299,18 @@ export function normalizeVerification(verification, runtimeType) {
     return { status: 'attested_pass', reason: 'API proxy runtime — no direct execution environment', reproducible: false };
   }
 
-  // local_cli — check for machine evidence
+  // local_cli / mcp — check for machine evidence
   const evidence = verification?.machine_evidence;
   if (Array.isArray(evidence) && evidence.length > 0) {
     const allZero = evidence.every(e => typeof e.exit_code === 'number' && e.exit_code === 0);
     if (allZero) {
-      return { status: 'pass', reason: 'local_cli turn provided machine evidence with zero exit codes', reproducible: true };
+      return { status: 'pass', reason: `${runtimeType} turn provided machine evidence with zero exit codes`, reproducible: true };
     }
-    return { status: 'not_reproducible', reason: 'local_cli turn has machine evidence with non-zero exit codes despite claiming pass', reproducible: false };
+    return { status: 'not_reproducible', reason: `${runtimeType} turn has machine evidence with non-zero exit codes despite claiming pass`, reproducible: false };
   }
 
-  // local_cli + pass but no machine evidence
-  return { status: 'not_reproducible', reason: 'local_cli turn claimed pass but provided no machine evidence', reproducible: false };
+  // executable runtime + pass but no machine evidence
+  return { status: 'not_reproducible', reason: `${runtimeType} turn claimed pass but provided no machine evidence`, reproducible: false };
 }
 
 // ── Declared vs Observed Comparison ─────────────────────────────────────────

package/src/lib/validation.js

@@ -2,6 +2,12 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { validateStagedTurnResult, STAGING_PATH } from './turn-result-validator.js';
 import { getActiveTurn } from './governed-state.js';
+import {
+  validateGovernedProjectTemplate,
+  validateGovernedTemplateRegistry,
+  validateProjectPlanningArtifacts,
+  validateAcceptanceHintCompletion,
+} from './governed-templates.js';
 
 const DEFAULT_REQUIRED_FILES = [
   '.planning/PROJECT.md',
@@ -87,6 +93,23 @@ export function validateGovernedProject(root, rawConfig, config, opts = {}) {
   const errors = [];
   const warnings = [];
 
+  const templateRegistry = validateGovernedTemplateRegistry();
+  errors.push(...templateRegistry.errors);
+  warnings.push(...templateRegistry.warnings);
+
+  const projectTemplate = validateGovernedProjectTemplate(rawConfig?.template);
+  errors.push(...projectTemplate.errors);
+  warnings.push(...projectTemplate.warnings);
+
+  // Validate planning artifact completeness against the configured template
+  const planningArtifacts = validateProjectPlanningArtifacts(root, rawConfig?.template);
+  errors.push(...planningArtifacts.errors);
+  warnings.push(...planningArtifacts.warnings);
+
+  // Validate acceptance hint completion against the configured template
+  const acceptanceHints = validateAcceptanceHintCompletion(root, rawConfig?.template);
+  warnings.push(...acceptanceHints.warnings);
+
   const mustExist = [
     config.files?.state || '.agentxchain/state.json',
     config.files?.history || '.agentxchain/history.jsonl',

package/src/templates/governed/library.json

@@ -0,0 +1,31 @@
+{
+  "id": "library",
+  "display_name": "Library",
+  "description": "Governed scaffold for reusable packages with public-API, compatibility, and adoption planning.",
+  "version": "1",
+  "protocol_compatibility": ["1.0", "1.1"],
+  "planning_artifacts": [
+    {
+      "filename": "public-api.md",
+      "content_template": "# Public API — {{project_name}}\n\n## Supported Entrypoints\n- Package name:\n- Import / require paths:\n- Stable vs experimental exports:\n\n## Consumer-Facing Surface\n| Export / command | Consumer use case | Stability | Notes |\n|------------------|-------------------|-----------|-------|\n| | | | |\n\n## Breaking-Change Triggers\n- What counts as breaking:\n- What can ship behind deprecation first:\n- What must stay internal:\n"
+    },
+    {
+      "filename": "compatibility-policy.md",
+      "content_template": "# Compatibility Policy — {{project_name}}\n\n## Versioning Contract\n- Semver policy:\n- Supported runtime versions:\n- Supported platforms / environments:\n\n## Deprecation And Migration\n| Surface | Deprecation path | Migration guidance | Removal target |\n|---------|------------------|--------------------|----------------|\n| | | | |\n\n## Compatibility Risks\n- Dependency upgrade hazards:\n- Packaging / module-format risks:\n- Consumer breakage watchpoints:\n"
+    },
+    {
+      "filename": "release-adoption.md",
+      "content_template": "# Release And Adoption — {{project_name}}\n\n## Consumer Smoke Proof\n- Install command:\n- Import / usage smoke check:\n- Example consumer environment:\n\n## Release Notes Inputs\n- User-visible changes:\n- Upgrade steps:\n- Rollback or pinning advice:\n\n## Adoption Risks\n- Migration blockers:\n- Documentation gaps:\n- Support expectations after release:\n"
+    }
+  ],
+  "prompt_overrides": {
+    "pm": "Define the exported surface, compatibility promise, and consumer upgrade expectations before the team treats the package as ready to ship.",
+    "dev": "Treat exported entrypoints, backward compatibility, and package-consumer install or import paths as product behavior, not release polish.",
+    "qa": "Verify public API stability, install/import smoke, migration notes, and compatibility risks across supported runtimes before sign-off."
+  },
+  "acceptance_hints": [
+    "Public API surface reviewed and intentionally versioned",
+    "Compatibility or migration expectations documented for consumers",
+    "Install/import or package-consumer smoke path verified"
+  ]
+}