@bpmsoftwaresolutions/ai-engine-client 1.1.58 → 1.1.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.58",
+  "version": "1.1.59",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -1,5 +1,5 @@
 const DEFAULT_TIMEOUT_MS = 30000;
-export const AI_ENGINE_CLIENT_VERSION = '1.1.58';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.59';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -207,6 +207,19 @@ function cleanText(value) {
   return text || null;
 }
 
+function compareSemanticVersions(left, right) {
+  const leftParts = String(left || '').split('.').map((part) => Number.parseInt(part, 10) || 0);
+  const rightParts = String(right || '').split('.').map((part) => Number.parseInt(part, 10) || 0);
+  const width = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < width; index += 1) {
+    const a = leftParts[index] || 0;
+    const b = rightParts[index] || 0;
+    if (a > b) return 1;
+    if (a < b) return -1;
+  }
+  return 0;
+}
+
 function looksLikeUuid(value) {
   const text = cleanText(value);
   return Boolean(text && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(text));
@@ -459,6 +472,7 @@ export class AIEngineClient {
       sendCoordinationPong: (request) => this.sendCoordinationPong(request),
       getCoordinationPingPongStatus: (request) => this.getCoordinationPingPongStatus(request),
       stopCoordinationPingPong: (request) => this.stopCoordinationPingPong(request),
+      checkCoordinationPingPongPreflight: (request) => this.checkCoordinationPingPongPreflight(request),
       connectToTransferChannel: (request) => this.connectToTransferChannel(request),
       respondToMessageWatch: (request) => this.respondToMessageWatch(request),
     };
@@ -492,6 +506,7 @@ export class AIEngineClient {
       sendCoordinationPong: (request) => this.sendCoordinationPong(request),
       getCoordinationPingPongStatus: (request) => this.getCoordinationPingPongStatus(request),
       stopCoordinationPingPong: (request) => this.stopCoordinationPingPong(request),
+      checkCoordinationPingPongPreflight: (request) => this.checkCoordinationPingPongPreflight(request),
     };
   }
 
@@ -682,6 +697,79 @@ export class AIEngineClient {
     return this._request('/api/agent-communications/deployment-capabilities');
   }
 
+  async checkCoordinationPingPongPreflight({
+    packageVersion,
+  } = {}) {
+    const capabilities = await this.getCollaborationCapabilities();
+    const requiredMethods = [
+      'startCoordinationPingPong',
+      'sendCoordinationPing',
+      'sendCoordinationPong',
+      'getCoordinationPingPongStatus',
+      'stopCoordinationPingPong',
+    ];
+    const resolvedPackageVersion = cleanText(packageVersion) || AI_ENGINE_CLIENT_VERSION;
+    const minimumClientVersion = cleanText(capabilities.minimum_client_version) || resolvedPackageVersion;
+    const supported = Boolean(capabilities.coordination_ping_pong_supported);
+    const reportedMethods = Array.isArray(capabilities.required_methods) && capabilities.required_methods.length > 0
+      ? capabilities.required_methods
+      : capabilities.collaboration_choreography_methods;
+    const missingMethods = requiredMethods.filter((method) => !Array.isArray(reportedMethods) || !reportedMethods.includes(method));
+    const issues = [];
+    if (!supported) {
+      issues.push({
+        drift_type: 'capability_drift',
+        rule: 'coordination_ping_pong_unsupported',
+        message: 'Coordination Ping Pong is not supported by the deployed collaboration capability surface.',
+      });
+    }
+    if (compareSemanticVersions(resolvedPackageVersion, minimumClientVersion) < 0) {
+      issues.push({
+        drift_type: 'capability_drift',
+        rule: 'package_version_below_minimum',
+        message: `Package version ${resolvedPackageVersion} is below required minimum ${minimumClientVersion}.`,
+        package_version: resolvedPackageVersion,
+        required_minimum_version: minimumClientVersion,
+      });
+    }
+    if (missingMethods.length > 0) {
+      issues.push({
+        drift_type: 'deployment_drift',
+        rule: 'missing_ping_pong_methods',
+        message: `Missing required coordination methods: ${missingMethods.join(', ')}.`,
+        missing_methods: missingMethods,
+      });
+    }
+    if (issues.length > 0) {
+      return {
+        ok: false,
+        supported: false,
+        minimum_client_version: minimumClientVersion,
+        package_version: resolvedPackageVersion,
+        coordination_ping_pong_supported: supported,
+        required_methods: requiredMethods,
+        capabilities,
+        issues,
+        stop_reason: {
+          code: 'coordination_ping_pong_preflight_failed',
+          message: 'Coordination Ping Pong is not ready to start.',
+          details: { issues },
+        },
+      };
+    }
+    return {
+      ok: true,
+      supported: true,
+      minimum_client_version: minimumClientVersion,
+      package_version: resolvedPackageVersion,
+      coordination_ping_pong_supported: supported,
+      required_methods: requiredMethods,
+      capabilities,
+      issues: [],
+      stop_reason: null,
+    };
+  }
+
   async listCommunicationChannels({
     workflowRunId,
     workflow_run_id,
@@ -1839,6 +1927,15 @@ export class AIEngineClient {
         stop_reason: resolved.stop_reason,
       };
     }
+    const preflight = await this.checkCoordinationPingPongPreflight({ packageVersion: this.clientVersion });
+    if (!preflight.ok) {
+      return {
+        started: false,
+        sent: false,
+        stop_reason: preflight.stop_reason,
+        coordination_ping_pong_preflight: preflight,
+      };
+    }
     return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(resolved.channel_id)}/coordination/ping-pong/start`, {
       method: 'POST',
       body: {