agentxchain 2.9.0 → 2.11.0

package/src/lib/adapters/api-proxy-adapter.js

@@ -762,7 +762,7 @@ export async function dispatchApiProxy(root, state, config, options = {}) {
     return errorReturn(root, turn.turn_id, classified);
   }
 
-  const endpoint = PROVIDER_ENDPOINTS[provider];
+  const endpoint = runtime.base_url || PROVIDER_ENDPOINTS[provider];
   if (!endpoint) {
     const classified = classifyError(
       'unsupported_provider',

package/src/lib/governed-templates.js

@@ -248,6 +248,42 @@ export function validateProjectPlanningArtifacts(root, templateId) {
 }
 
 const TEMPLATE_GUIDANCE_HEADER = '## Template Guidance';
+const GOVERNED_WORKFLOW_KIT_BASE_FILES = Object.freeze([
+  '.planning/PM_SIGNOFF.md',
+  '.planning/ROADMAP.md',
+  '.planning/acceptance-matrix.md',
+  '.planning/ship-verdict.md',
+]);
+const GOVERNED_WORKFLOW_KIT_STRUCTURAL_CHECKS = Object.freeze([
+  {
+    id: 'pm_signoff_approved_field',
+    file: '.planning/PM_SIGNOFF.md',
+    pattern: /^Approved\s*:/im,
+    description: 'PM signoff declares an Approved field',
+  },
+  {
+    id: 'roadmap_phases_section',
+    file: '.planning/ROADMAP.md',
+    pattern: /^##\s+Phases\b/im,
+    description: 'Roadmap defines a ## Phases section',
+  },
+  {
+    id: 'acceptance_matrix_table_header',
+    file: '.planning/acceptance-matrix.md',
+    pattern: /^\|\s*Req\s*#\s*\|/im,
+    description: 'Acceptance matrix includes the requirement table header',
+  },
+  {
+    id: 'ship_verdict_heading',
+    file: '.planning/ship-verdict.md',
+    pattern: /^##\s+Verdict\s*:/im,
+    description: 'Ship verdict declares a verdict heading',
+  },
+]);
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.trim()))];
+}
 
 export function validateAcceptanceHintCompletion(root, templateId) {
   const effectiveTemplateId = templateId || 'generic';
@@ -358,6 +394,64 @@ export function validateAcceptanceHintCompletion(root, templateId) {
   };
 }
 
+export function validateGovernedWorkflowKit(root, config = {}) {
+  const errors = [];
+  const warnings = [];
+  const gateRequiredFiles = uniqueStrings(
+    Object.values(config?.gates || {}).flatMap((gate) => Array.isArray(gate?.requires_files) ? gate.requires_files : [])
+  );
+  const requiredFiles = uniqueStrings([...GOVERNED_WORKFLOW_KIT_BASE_FILES, ...gateRequiredFiles]);
+  const present = [];
+  const missing = [];
+
+  for (const relPath of requiredFiles) {
+    if (existsSync(join(root, relPath))) {
+      present.push(relPath);
+    } else {
+      missing.push(relPath);
+      errors.push(`Workflow kit requires "${relPath}" but it is missing.`);
+    }
+  }
+
+  const structuralChecks = GOVERNED_WORKFLOW_KIT_STRUCTURAL_CHECKS.map((check) => {
+    const absPath = join(root, check.file);
+    if (!existsSync(absPath)) {
+      return {
+        id: check.id,
+        file: check.file,
+        ok: false,
+        skipped: true,
+        description: check.description,
+      };
+    }
+
+    const content = readFileSync(absPath, 'utf8');
+    const ok = check.pattern.test(content);
+    if (!ok) {
+      errors.push(`Workflow kit file "${check.file}" must preserve its structural marker: ${check.description}.`);
+    }
+
+    return {
+      id: check.id,
+      file: check.file,
+      ok,
+      skipped: false,
+      description: check.description,
+    };
+  });
+
+  return {
+    ok: errors.length === 0,
+    required_files: requiredFiles,
+    gate_required_files: gateRequiredFiles,
+    present,
+    missing,
+    structural_checks: structuralChecks,
+    errors,
+    warnings,
+  };
+}
+
 export function validateGovernedProjectTemplate(templateId, source = 'agentxchain.json') {
   const effectiveTemplateId = templateId || 'generic';
   const effectiveSource = templateId ? source : 'implicit_default';

package/src/lib/normalized-config.js

@@ -344,6 +344,20 @@ export function validateV4Config(data, projectRoot) {
         if (typeof rt.auth_env !== 'string' || !rt.auth_env.trim()) {
           errors.push(`Runtime "${id}": api_proxy requires "auth_env" (environment variable name for API key)`);
         }
+        if ('base_url' in rt) {
+          if (typeof rt.base_url !== 'string' || !rt.base_url.trim()) {
+            errors.push(`Runtime "${id}": api_proxy base_url must be a non-empty string when provided`);
+          } else {
+            try {
+              const parsed = new URL(rt.base_url);
+              if (!['http:', 'https:'].includes(parsed.protocol)) {
+                errors.push(`Runtime "${id}": api_proxy base_url must use http or https`);
+              }
+            } catch {
+              errors.push(`Runtime "${id}": api_proxy base_url must be a valid absolute URL`);
+            }
+          }
+        }
         if ('retry_policy' in rt) {
           validateApiProxyRetryPolicy(id, rt.retry_policy, errors);
         }

package/src/lib/protocol-conformance.js

@@ -1,10 +1,13 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_FIXTURE_ROOT = resolve(__dirname, '..', '..', '..', '.agentxchain-conformance', 'fixtures');
+const DEFAULT_REMOTE_TIMEOUT_MS = 30_000;
 const VALID_RESPONSE_STATUSES = new Set(['pass', 'fail', 'error', 'not_implemented']);
 const VALID_TIERS = new Set([1, 2, 3]);
 
@@ -56,13 +59,7 @@ function validateFixtureShape(fixture, filePath) {
   return errors;
 }
 
-function loadCapabilities(targetRoot) {
-  const capabilitiesPath = join(targetRoot, '.agentxchain-conformance', 'capabilities.json');
-  if (!existsSync(capabilitiesPath)) {
-    throw new Error(`Missing capabilities file at ${capabilitiesPath}`);
-  }
-
-  const capabilities = readJsonFile(capabilitiesPath);
+function validateCapabilities(capabilities, { remote = false } = {}) {
   const errors = [];
 
   if (typeof capabilities.implementation !== 'string' || !capabilities.implementation.trim()) {
@@ -80,14 +77,26 @@ function loadCapabilities(targetRoot) {
   if (!capabilities.adapter || typeof capabilities.adapter !== 'object' || Array.isArray(capabilities.adapter)) {
     errors.push('capabilities.adapter must be an object');
   } else {
-    if (capabilities.adapter.protocol !== 'stdio-fixture-v1') {
-      errors.push('capabilities.adapter.protocol must be "stdio-fixture-v1"');
+    const expectedProtocol = remote ? 'http-fixture-v1' : 'stdio-fixture-v1';
+    if (capabilities.adapter.protocol !== expectedProtocol) {
+      errors.push(`capabilities.adapter.protocol must be "${expectedProtocol}"`);
     }
-    if (!Array.isArray(capabilities.adapter.command) || capabilities.adapter.command.length === 0) {
+    if (!remote && (!Array.isArray(capabilities.adapter.command) || capabilities.adapter.command.length === 0)) {
       errors.push('capabilities.adapter.command must be a non-empty array');
     }
   }
 
+  return errors;
+}
+
+function loadLocalCapabilities(targetRoot) {
+  const capabilitiesPath = join(targetRoot, '.agentxchain-conformance', 'capabilities.json');
+  if (!existsSync(capabilitiesPath)) {
+    throw new Error(`Missing capabilities file at ${capabilitiesPath}`);
+  }
+
+  const capabilities = readJsonFile(capabilitiesPath);
+  const errors = validateCapabilities(capabilities);
   if (errors.length > 0) {
     throw new Error(`Invalid capabilities.json: ${errors.join('; ')}`);
   }
@@ -95,6 +104,84 @@ function loadCapabilities(targetRoot) {
   return capabilities;
 }
 
+function normalizeRemoteBase(remote) {
+  let url;
+  try {
+    url = new URL(remote);
+  } catch (error) {
+    throw new Error(`Invalid remote URL "${remote}": ${error.message}`);
+  }
+
+  const normalized = url.toString();
+  return normalized.endsWith('/') ? normalized.slice(0, -1) : normalized;
+}
+
+function buildRemoteUrl(remoteBase, path) {
+  return new URL(path.replace(/^\//, ''), `${remoteBase}/`).toString();
+}
+
+function buildRemoteHeaders(token, extraHeaders = {}) {
+  return {
+    ...extraHeaders,
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+  };
+}
+
+function isTimeoutError(error) {
+  return error?.name === 'TimeoutError'
+    || error?.name === 'AbortError'
+    || error?.cause?.name === 'TimeoutError'
+    || error?.cause?.name === 'AbortError';
+}
+
+function formatRemoteFetchError(error, timeout, prefix) {
+  if (isTimeoutError(error)) {
+    return `${prefix} timeout after ${timeout}ms`;
+  }
+  return `${prefix} network error: ${error.message}`;
+}
+
+async function loadRemoteCapabilities(remote, token, timeout) {
+  const remoteBase = normalizeRemoteBase(remote);
+  const capabilitiesUrl = buildRemoteUrl(remoteBase, '/conform/capabilities');
+
+  try {
+    const response = await requestRemote(capabilitiesUrl, {
+      headers: buildRemoteHeaders(token),
+      timeout,
+    });
+
+    if (response.statusCode !== 200) {
+      throw new Error(`Failed to fetch remote capabilities: HTTP ${response.statusCode}`);
+    }
+
+    let capabilities;
+    try {
+      capabilities = JSON.parse(response.body);
+    } catch (error) {
+      throw new Error(`Invalid capabilities response: ${error.message}`);
+    }
+
+    const errors = validateCapabilities(capabilities, { remote: true });
+    if (errors.length > 0) {
+      throw new Error(`Invalid capabilities.json: ${errors.join('; ')}`);
+    }
+
+    return {
+      capabilities,
+      remoteBase,
+      executeUrl: buildRemoteUrl(remoteBase, '/conform/execute'),
+    };
+  } catch (error) {
+    if (error.message.startsWith('Failed to fetch remote capabilities:')
+      || error.message.startsWith('Invalid capabilities response:')
+      || error.message.startsWith('Invalid capabilities.json:')) {
+      throw error;
+    }
+    throw new Error(formatRemoteFetchError(error, timeout, 'Failed to fetch remote capabilities'));
+  }
+}
+
 function selectFixtureFiles(fixtureRoot, requestedTier, surface) {
   if (!existsSync(fixtureRoot)) {
     throw new Error(`Fixture root not found at ${fixtureRoot}`);
@@ -135,7 +222,7 @@ function ensureSurfaceSummary(tierSummary, surface) {
   return tierSummary.surfaces[surface];
 }
 
-function executeFixture(targetRoot, adapterCommand, fixture) {
+function executeLocalFixture(targetRoot, adapterCommand, fixture) {
   const [executable, ...args] = adapterCommand;
   const result = spawnSync(executable, args, {
     cwd: targetRoot,
@@ -196,12 +283,128 @@ function executeFixture(targetRoot, adapterCommand, fixture) {
   return parsed;
 }
 
+async function executeRemoteFixture(executeUrl, token, timeout, fixture) {
+  let response;
+  try {
+    response = await requestRemote(executeUrl, {
+      method: 'POST',
+      headers: buildRemoteHeaders(token, {
+        'content-type': 'application/json',
+      }),
+      body: JSON.stringify(fixture),
+      timeout,
+    });
+  } catch (error) {
+    return {
+      status: 'error',
+      message: formatRemoteFetchError(error, timeout, 'HTTP fixture execution'),
+      actual: null,
+    };
+  }
+
+  const rawBody = response.body;
+
+  if (response.statusCode !== 200) {
+    let actual = null;
+    let message = rawBody.trim() || `HTTP ${response.statusCode}`;
+
+    if (rawBody.trim()) {
+      try {
+        const parsed = JSON.parse(rawBody);
+        actual = parsed;
+        if (typeof parsed.message === 'string' && parsed.message.trim()) {
+          message = parsed.message.trim();
+        }
+      } catch {
+        actual = { body: rawBody };
+      }
+    }
+
+    return {
+      status: 'error',
+      message: `HTTP ${response.statusCode}: ${message}`,
+      actual,
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(rawBody.trim() || '{}');
+  } catch (error) {
+    return {
+      status: 'error',
+      message: `Malformed response: ${error.message}`,
+      actual: {
+        body: rawBody,
+      },
+    };
+  }
+
+  if (!VALID_RESPONSE_STATUSES.has(parsed.status)) {
+    return {
+      status: 'error',
+      message: 'Adapter response missing valid "status"',
+      actual: parsed,
+    };
+  }
+
+  return parsed;
+}
+
+function requestRemote(urlString, { method = 'GET', headers = {}, body = null, timeout }) {
+  const url = new URL(urlString);
+  const requestImpl = url.protocol === 'https:' ? httpsRequest : httpRequest;
+  const requestHeaders = {
+    connection: 'close',
+    ...headers,
+  };
+
+  if (body != null && requestHeaders['content-length'] == null && requestHeaders['Content-Length'] == null) {
+    requestHeaders['content-length'] = Buffer.byteLength(body);
+  }
+
+  return new Promise((resolveRequest, rejectRequest) => {
+    const req = requestImpl(url, {
+      method,
+      headers: requestHeaders,
+    }, (res) => {
+      let responseBody = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        responseBody += chunk;
+      });
+      res.on('end', () => {
+        resolveRequest({
+          statusCode: res.statusCode ?? 0,
+          body: responseBody,
+        });
+      });
+    });
+
+    req.on('error', rejectRequest);
+    req.setTimeout(timeout, () => {
+      const error = new Error(`timeout after ${timeout}ms`);
+      error.name = 'TimeoutError';
+      req.destroy(error);
+    });
+
+    if (body) {
+      req.write(body);
+    }
+
+    req.end();
+  });
+}
+
 export function getDefaultFixtureRoot() {
   return DEFAULT_FIXTURE_ROOT;
 }
 
-export function verifyProtocolConformance({
+export async function verifyProtocolConformance({
   targetRoot,
+  remote = null,
+  token = null,
+  timeout = DEFAULT_REMOTE_TIMEOUT_MS,
   requestedTier = 1,
   surface = null,
   fixtureRoot = DEFAULT_FIXTURE_ROOT,
@@ -209,9 +412,18 @@ export function verifyProtocolConformance({
   if (!Number.isInteger(requestedTier) || !VALID_TIERS.has(requestedTier)) {
     throw new Error(`Tier must be 1, 2, or 3. Received "${requestedTier}"`);
   }
+  if (!Number.isInteger(timeout) || timeout <= 0) {
+    throw new Error(`Timeout must be a positive integer number of milliseconds. Received "${timeout}"`);
+  }
+  if (!!targetRoot === !!remote) {
+    throw new Error('Specify exactly one of targetRoot or remote');
+  }
 
-  const resolvedTargetRoot = resolve(targetRoot);
-  const capabilities = loadCapabilities(resolvedTargetRoot);
+  const resolvedTargetRoot = targetRoot ? resolve(targetRoot) : null;
+  const remoteTarget = remote ? normalizeRemoteBase(remote) : null;
+  const localCapabilities = resolvedTargetRoot ? loadLocalCapabilities(resolvedTargetRoot) : null;
+  const remoteCapabilities = remoteTarget ? await loadRemoteCapabilities(remoteTarget, token, timeout) : null;
+  const capabilities = localCapabilities || remoteCapabilities.capabilities;
 
   // Enforce surface claims when capabilities.surfaces exists and --surface is requested
   if (surface && capabilities.surfaces && typeof capabilities.surfaces === 'object') {
@@ -231,6 +443,7 @@ export function verifyProtocolConformance({
     tier_requested: requestedTier,
     timestamp: new Date().toISOString(),
     target_root: resolvedTargetRoot,
+    remote: remoteTarget,
     fixture_root: fixtureRoot,
     results: {},
     overall: 'pass',
@@ -253,7 +466,9 @@ export function verifyProtocolConformance({
     }
 
     const surfaceSummary = ensureSurfaceSummary(tierSummary, fixture.surface);
-    const adapterResult = executeFixture(resolvedTargetRoot, capabilities.adapter.command, fixture);
+    const adapterResult = resolvedTargetRoot
+      ? executeLocalFixture(resolvedTargetRoot, capabilities.adapter.command, fixture)
+      : await executeRemoteFixture(remoteCapabilities.executeUrl, token, timeout, fixture);
 
     tierSummary.fixtures_run += 1;
 

package/src/lib/reference-conformance-adapter.js

@@ -283,6 +283,33 @@ function isAssertionObject(value) {
   return value && typeof value === 'object' && !Array.isArray(value) && typeof value.assert === 'string';
 }
 
+function matchUnorderedArray(expectedItems, actual) {
+  if (!Array.isArray(expectedItems) || !Array.isArray(actual) || expectedItems.length !== actual.length) {
+    return false;
+  }
+
+  const used = new Set();
+
+  for (const expectedItem of expectedItems) {
+    let matchedIndex = -1;
+    for (let index = 0; index < actual.length; index += 1) {
+      if (used.has(index)) continue;
+      if (matchExpected(expectedItem, actual[index])) {
+        matchedIndex = index;
+        break;
+      }
+    }
+
+    if (matchedIndex === -1) {
+      return false;
+    }
+
+    used.add(matchedIndex);
+  }
+
+  return true;
+}
+
 function matchExpected(expected, actual) {
   if (isAssertionObject(expected)) {
     if (expected.assert === 'nonempty_string') {
@@ -294,6 +321,9 @@ function matchExpected(expected, actual) {
     if (expected.assert === 'present') {
       return actual !== undefined;
     }
+    if (expected.assert === 'unordered_array') {
+      return matchUnorderedArray(expected.items, actual);
+    }
     return false;
   }
 
@@ -520,6 +550,22 @@ function applyManifestFixtureMutations(root, fixture, turnId) {
       // Missing files are surfaced by manifest verification, not fixture setup.
     }
   }
+
+  if (fixture.setup.post_finalize_delete_manifest) {
+    try {
+      unlinkSync(join(bundleDir, 'MANIFEST.json'));
+    } catch {
+      // Missing manifest is surfaced by manifest verification, not fixture setup.
+    }
+  }
+
+  const corruptedManifest = fixture.setup.post_finalize_corrupt_manifest?.[turnId];
+  if (corruptedManifest !== undefined) {
+    const nextManifestContent = typeof corruptedManifest === 'string'
+      ? corruptedManifest
+      : JSON.stringify(corruptedManifest, null, 2);
+    writeFileSync(join(bundleDir, 'MANIFEST.json'), nextManifestContent);
+  }
 }
 
 function executeFixtureOperation(workspace, fixture) {
@@ -757,6 +803,7 @@ function executeFixtureOperation(workspace, fixture) {
         hook_ok: hookResult.ok,
         blocked: hookResult.blocked || false,
         audit_entry: auditEntry,
+        audit_entries: hookResult.results || [],
       };
     }
 

package/src/lib/role-resolution.js

@@ -0,0 +1,103 @@
+/**
+ * Shared governed role-resolution contract for operator commands.
+ *
+ * Keeps `step` and `run` aligned on:
+ *   - explicit role override validation
+ *   - routing-legal next-role recommendations
+ *   - phase entry-role fallback
+ *   - first-role final fallback
+ */
+
+function getPhaseId(state, config) {
+  if (state?.phase) {
+    return state.phase;
+  }
+
+  const firstPhase = config?.phases?.[0];
+  if (typeof firstPhase === 'string') {
+    return firstPhase;
+  }
+  if (firstPhase?.id) {
+    return firstPhase.id;
+  }
+
+  return null;
+}
+
+export function resolveGovernedRole({ override = null, state = null, config }) {
+  const roles = Object.keys(config?.roles || {});
+  const phase = getPhaseId(state, config);
+  const routing = phase ? config?.routing?.[phase] : null;
+  const warnings = [];
+
+  if (override) {
+    if (!config?.roles?.[override]) {
+      return {
+        roleId: null,
+        warnings,
+        error: `Unknown role: "${override}"`,
+        availableRoles: roles,
+        phase,
+      };
+    }
+
+    if (routing?.allowed_next_roles && !routing.allowed_next_roles.includes(override) && override !== 'human') {
+      warnings.push(`role "${override}" is not in allowed_next_roles for phase "${phase}"`);
+    }
+
+    return {
+      roleId: override,
+      warnings,
+      error: null,
+      availableRoles: roles,
+      phase,
+    };
+  }
+
+  if (state?.next_recommended_role && config?.roles?.[state.next_recommended_role]) {
+    const recommended = state.next_recommended_role;
+    const isLegal = !routing?.allowed_next_roles || routing.allowed_next_roles.includes(recommended);
+    if (isLegal) {
+      return {
+        roleId: recommended,
+        warnings,
+        error: null,
+        availableRoles: roles,
+        phase,
+      };
+    }
+  }
+
+  if (routing?.entry_role && config?.roles?.[routing.entry_role]) {
+    return {
+      roleId: routing.entry_role,
+      warnings,
+      error: null,
+      availableRoles: roles,
+      phase,
+    };
+  }
+
+  if (roles.length > 0) {
+    warnings.push(
+      phase
+        ? `No entry_role for phase "${phase}". Defaulting to "${roles[0]}".`
+        : `No routing phase resolved. Defaulting to "${roles[0]}".`,
+    );
+    return {
+      roleId: roles[0],
+      warnings,
+      error: null,
+      availableRoles: roles,
+      phase,
+    };
+  }
+
+  return {
+    roleId: null,
+    warnings,
+    error: 'No roles defined in config.',
+    availableRoles: roles,
+    phase,
+  };
+}