agentxchain 2.135.1 → 2.136.1

package/src/lib/runtime-capabilities.js

@@ -4,10 +4,28 @@ function normalizeMcpTransport(runtime) {
     : 'stdio';
 }
 
+const DECLARABLE_CAPABILITY_FIELDS = new Set([
+  'can_write_files',
+  'proposal_support',
+  'workflow_artifact_ownership',
+]);
+
+function mergeExplicitCapabilities(base, runtime) {
+  const declared = runtime?.capabilities;
+  if (!declared || typeof declared !== 'object' || Array.isArray(declared)) return base;
+  const merged = { ...base };
+  for (const field of DECLARABLE_CAPABILITY_FIELDS) {
+    if (typeof declared[field] === 'string' && declared[field].length > 0) {
+      merged[field] = declared[field];
+    }
+  }
+  return merged;
+}
+
 export function getRuntimeCapabilityContract(runtime = {}) {
   switch (runtime?.type) {
     case 'manual':
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'manual',
         transport: 'manual',
         can_write_files: 'direct',
@@ -15,10 +33,10 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'none',
         requires_local_binary: false,
         workflow_artifact_ownership: 'yes',
-      };
+      }, runtime);
 
     case 'local_cli':
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'local_cli',
         transport: 'local_cli',
         can_write_files: 'direct',
@@ -26,10 +44,10 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'optional',
         requires_local_binary: true,
         workflow_artifact_ownership: 'yes',
-      };
+      }, runtime);
 
     case 'api_proxy':
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'api_proxy',
         transport: 'provider_api',
         can_write_files: 'proposal_only',
@@ -37,10 +55,10 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'native',
         requires_local_binary: false,
         workflow_artifact_ownership: 'proposal_apply_required',
-      };
+      }, runtime);
 
     case 'remote_agent':
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'remote_agent',
         transport: 'remote_http',
         can_write_files: 'proposal_only',
@@ -48,13 +66,13 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'native',
         requires_local_binary: false,
         workflow_artifact_ownership: 'proposal_apply_required',
-      };
+      }, runtime);
 
     case 'mcp': {
       const transport = normalizeMcpTransport(runtime) === 'streamable_http'
         ? 'mcp_streamable_http'
         : 'mcp_stdio';
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'mcp',
         transport,
         can_write_files: 'tool_defined',
@@ -62,11 +80,11 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'tool_defined',
         requires_local_binary: transport === 'mcp_stdio',
         workflow_artifact_ownership: 'tool_defined',
-      };
+      }, runtime);
     }
 
     default:
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: runtime?.type || 'unknown',
         transport: 'unknown',
         can_write_files: 'unknown',
@@ -74,7 +92,7 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'unknown',
         requires_local_binary: false,
         workflow_artifact_ownership: 'unknown',
-      };
+      }, runtime);
   }
 }
 
@@ -91,79 +109,69 @@ export function getRoleRuntimeCapabilityContract(roleId, role = {}, runtime = {}
   let workflowArtifactOwnership = 'unknown';
 
   if (authority === 'review_only') {
-    switch (runtime?.type) {
-      case 'manual':
-        effectiveWritePath = 'planning_only';
-        workflowArtifactOwnership = 'yes';
-        appendNote(notes, 'Manual review roles can satisfy workflow-kit ownership for planning artifacts.');
-        break;
-      case 'local_cli':
-        effectiveWritePath = 'invalid_review_only_binding';
-        workflowArtifactOwnership = 'invalid';
-        appendNote(notes, 'review_only + local_cli is invalid because local_cli exposes direct repo writes.');
-        break;
-      case 'api_proxy':
-      case 'remote_agent':
-        effectiveWritePath = 'review_artifact_only';
-        workflowArtifactOwnership = 'no';
-        appendNote(notes, 'Review-only remote turns can attest and produce review artifacts, not workflow-kit files.');
-        break;
-      case 'mcp':
-        effectiveWritePath = 'tool_defined';
-        workflowArtifactOwnership = 'tool_defined';
-        appendNote(notes, 'MCP review-only file production depends on the configured tool, not runtime type alone.');
-        break;
-      default:
-        effectiveWritePath = 'unknown';
-        workflowArtifactOwnership = 'unknown';
-        break;
+    if (runtime?.type === 'manual') {
+      effectiveWritePath = 'planning_only';
+      workflowArtifactOwnership = 'yes';
+      appendNote(notes, 'Manual review roles can satisfy workflow-kit ownership for planning artifacts.');
+    } else if (base.can_write_files === 'direct' && runtime?.type === 'local_cli') {
+      effectiveWritePath = 'invalid_review_only_binding';
+      workflowArtifactOwnership = 'invalid';
+      appendNote(notes, 'review_only + local_cli is invalid because local_cli exposes direct repo writes.');
+    } else if (base.can_write_files === 'tool_defined' || base.workflow_artifact_ownership === 'tool_defined') {
+      effectiveWritePath = 'tool_defined';
+      workflowArtifactOwnership = 'tool_defined';
+      appendNote(notes, 'Review-only file production depends on the configured tool contract, not runtime type alone.');
+    } else if (base.can_write_files === 'proposal_only') {
+      effectiveWritePath = 'review_artifact_only';
+      workflowArtifactOwnership = 'no';
+      appendNote(notes, 'Review-only remote turns can attest and produce review artifacts, not workflow-kit files.');
+    } else if (base.can_write_files === 'direct') {
+      effectiveWritePath = base.workflow_artifact_ownership === 'yes' ? 'planning_only' : 'review_artifact_only';
+      workflowArtifactOwnership = base.workflow_artifact_ownership === 'yes' ? 'yes' : 'no';
+      appendNote(notes, 'Review-only roles constrain direct-write runtimes to planning or review artifact production only.');
+    } else {
+      effectiveWritePath = 'unknown';
+      workflowArtifactOwnership = 'unknown';
     }
   } else if (authority === 'proposed') {
-    switch (runtime?.type) {
-      case 'manual':
-      case 'local_cli':
-        effectiveWritePath = 'patch_authoring';
-        workflowArtifactOwnership = 'yes';
-        appendNote(notes, 'This role can prepare patch-shaped work while still satisfying workflow-kit artifact ownership.');
-        break;
-      case 'api_proxy':
-      case 'remote_agent':
-        effectiveWritePath = 'proposal_apply_required';
-        workflowArtifactOwnership = 'proposal_apply_required';
-        appendNote(notes, 'Accepted proposals are staged under .agentxchain/proposed and require proposal apply before gate files exist in the repo.');
-        break;
-      case 'mcp':
-        effectiveWritePath = 'tool_defined';
-        workflowArtifactOwnership = 'tool_defined';
-        appendNote(notes, 'MCP proposed-authoring behavior depends on the governed tool implementation.');
-        break;
-      default:
-        effectiveWritePath = 'unknown';
-        workflowArtifactOwnership = 'unknown';
-        break;
+    if (runtime?.type === 'manual') {
+      effectiveWritePath = 'patch_authoring';
+      workflowArtifactOwnership = 'yes';
+      appendNote(notes, 'This role can prepare patch-shaped work while still satisfying workflow-kit artifact ownership.');
+    } else if (base.can_write_files === 'direct') {
+      effectiveWritePath = 'patch_authoring';
+      workflowArtifactOwnership = base.workflow_artifact_ownership;
+      appendNote(notes, 'This role can prepare patch-shaped work while still satisfying workflow-kit artifact ownership.');
+    } else if (base.can_write_files === 'proposal_only') {
+      effectiveWritePath = 'proposal_apply_required';
+      workflowArtifactOwnership = 'proposal_apply_required';
+      appendNote(notes, 'Accepted proposals are staged under .agentxchain/proposed and require proposal apply before gate files exist in the repo.');
+    } else if (base.can_write_files === 'tool_defined' || base.workflow_artifact_ownership === 'tool_defined') {
+      effectiveWritePath = 'tool_defined';
+      workflowArtifactOwnership = 'tool_defined';
+      appendNote(notes, 'Proposed-authoring behavior depends on the governed tool implementation.');
+    } else {
+      effectiveWritePath = 'unknown';
+      workflowArtifactOwnership = 'unknown';
     }
   } else if (authority === 'authoritative') {
-    switch (runtime?.type) {
-      case 'manual':
-      case 'local_cli':
-        effectiveWritePath = 'direct';
-        workflowArtifactOwnership = 'yes';
-        break;
-      case 'api_proxy':
-      case 'remote_agent':
-        effectiveWritePath = 'invalid_authoritative_binding';
-        workflowArtifactOwnership = 'invalid';
-        appendNote(notes, `${runtime.type} does not support authoritative roles in v1.`);
-        break;
-      case 'mcp':
-        effectiveWritePath = 'tool_defined';
-        workflowArtifactOwnership = 'tool_defined';
-        appendNote(notes, 'MCP authoritative repo writes are tool-defined, not guaranteed by runtime type.');
-        break;
-      default:
-        effectiveWritePath = 'unknown';
-        workflowArtifactOwnership = 'unknown';
-        break;
+    if (base.can_write_files === 'direct') {
+      effectiveWritePath = 'direct';
+      workflowArtifactOwnership = base.workflow_artifact_ownership;
+      if (runtime?.type === 'mcp') {
+        appendNote(notes, 'Authoritative MCP repo writes are accepted because the connector declared a direct write path.');
+      }
+    } else if (base.can_write_files === 'proposal_only') {
+      effectiveWritePath = 'invalid_authoritative_binding';
+      workflowArtifactOwnership = 'invalid';
+      appendNote(notes, `${runtime.type} does not support authoritative roles in v1.`);
+    } else if (base.can_write_files === 'tool_defined' || base.workflow_artifact_ownership === 'tool_defined') {
+      effectiveWritePath = 'tool_defined';
+      workflowArtifactOwnership = 'tool_defined';
+      appendNote(notes, 'Authoritative repo writes are tool-defined, not guaranteed by runtime type alone.');
+    } else {
+      effectiveWritePath = 'unknown';
+      workflowArtifactOwnership = 'unknown';
     }
   }
 
@@ -213,6 +221,18 @@ export function summarizeRuntimeCapabilityContract(contract) {
   ].join('; ');
 }
 
+export { DECLARABLE_CAPABILITY_FIELDS };
+
+export function getCapabilityDeclarationWarnings(runtime = {}) {
+  const warnings = [];
+  const declared = runtime?.capabilities;
+  if (!declared || typeof declared !== 'object' || Array.isArray(declared)) return warnings;
+  if (declared.can_write_files === 'direct' && (runtime.type === 'api_proxy' || runtime.type === 'remote_agent')) {
+    warnings.push(`Runtime type "${runtime.type}" declares can_write_files=direct, which the reference runner does not support in v1. A third-party runner may.`);
+  }
+  return warnings;
+}
+
 export function summarizeRoleRuntimeCapability(contract) {
   return [
     `${contract.role_id}(${contract.role_write_authority})`,
@@ -220,3 +240,34 @@ export function summarizeRoleRuntimeCapability(contract) {
     `owned_by=${contract.workflow_artifact_ownership}`,
   ].join('; ');
 }
+
+export function buildRuntimeCapabilityReport(runtimeId, runtime, roles) {
+  const mergedContract = getRuntimeCapabilityContract(runtime);
+  const declaredCapabilities = (runtime?.capabilities && typeof runtime.capabilities === 'object' && !Array.isArray(runtime.capabilities))
+    ? { ...runtime.capabilities }
+    : {};
+  const declarationWarnings = getCapabilityDeclarationWarnings(runtime);
+
+  const roleBindings = [];
+  for (const [roleId, role] of Object.entries(roles || {})) {
+    const boundRuntime = role.runtime_id || role.runtime;
+    if (boundRuntime !== runtimeId) continue;
+    const roleContract = getRoleRuntimeCapabilityContract(roleId, role, runtime);
+    roleBindings.push({
+      role_id: roleContract.role_id,
+      role_write_authority: roleContract.role_write_authority,
+      effective_write_path: roleContract.effective_write_path,
+      workflow_artifact_ownership: roleContract.workflow_artifact_ownership,
+      notes: roleContract.notes,
+    });
+  }
+
+  return {
+    runtime_id: runtimeId,
+    runtime_type: runtime?.type || 'unknown',
+    declared_capabilities: declaredCapabilities,
+    merged_contract: mergedContract,
+    declaration_warnings: declarationWarnings,
+    role_bindings: roleBindings,
+  };
+}