@bpmsoftwaresolutions/ai-engine-client 1.1.57 → 1.1.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.57",
+  "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.57';
+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));
@@ -454,6 +467,12 @@ export class AIEngineClient {
       verifyMessageSent: (request) => this.verifyMessageSent(request),
       verifyMessageReceived: (request) => this.verifyMessageReceived(request),
       getMessageDeliveryReceipt: (request) => this.getMessageDeliveryReceipt(request),
+      startCoordinationPingPong: (request) => this.startCoordinationPingPong(request),
+      sendCoordinationPing: (request) => this.sendCoordinationPing(request),
+      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),
     };
@@ -482,6 +501,12 @@ export class AIEngineClient {
       verifyMessageSent: (request) => this.verifyMessageSent(request),
       verifyMessageReceived: (request) => this.verifyMessageReceived(request),
       getMessageDeliveryReceipt: (request) => this.getMessageDeliveryReceipt(request),
+      startCoordinationPingPong: (request) => this.startCoordinationPingPong(request),
+      sendCoordinationPing: (request) => this.sendCoordinationPing(request),
+      sendCoordinationPong: (request) => this.sendCoordinationPong(request),
+      getCoordinationPingPongStatus: (request) => this.getCoordinationPingPongStatus(request),
+      stopCoordinationPingPong: (request) => this.stopCoordinationPingPong(request),
+      checkCoordinationPingPongPreflight: (request) => this.checkCoordinationPingPongPreflight(request),
     };
   }
 
@@ -672,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,
@@ -771,6 +869,108 @@ export class AIEngineClient {
     });
   }
 
+  async _resolveCoordinationChannelContext({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    packetId,
+    packet_id,
+    workflowRunId,
+    workflow_run_id,
+    participantRole,
+    participant_role,
+    role,
+  } = {}) {
+    const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+    const normalizedParticipantRole = cleanText(participant_role) || cleanText(participantRole) || cleanText(role);
+    const normalizedWorkflowRunId = cleanText(workflow_run_id) || cleanText(workflowRunId);
+    if (normalizedTransferChannelId) {
+      let packetId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId);
+      if (!packetId) {
+        try {
+          const status = await this.getCommunicationChannelStatus({ transferChannelId: normalizedTransferChannelId });
+          packetId = cleanText(status?.packet_id || status?.packetId || status?.work_transfer_packet_id);
+        } catch (error) {
+          void error;
+        }
+      }
+      return {
+        channel_id: normalizedTransferChannelId,
+        packet_id: packetId,
+        workflow_run_id: normalizedWorkflowRunId,
+        stop_reason: null,
+      };
+    }
+    const presence = await this.whoIsOnline({
+      workflowRunId: normalizedWorkflowRunId,
+      participantRole: normalizedParticipantRole,
+      includeStale: true,
+    });
+    const directoryRows = Array.isArray(presence?.presence)
+      ? presence.presence.filter((row) => row && typeof row === 'object')
+      : Array.isArray(presence?.online_participants)
+        ? presence.online_participants.filter((row) => row && typeof row === 'object')
+        : Array.isArray(presence?.participants)
+          ? presence.participants.filter((row) => row && typeof row === 'object')
+          : [];
+    const filteredRows = normalizedParticipantRole
+      ? directoryRows.filter((row) => cleanText(row.participant_role) === normalizedParticipantRole)
+      : [];
+    const onlineRows = filteredRows.filter((row) => Boolean(row.is_online));
+    const chooseRows = onlineRows.length > 0 ? onlineRows : filteredRows;
+    if (chooseRows.length === 1) {
+      return {
+        channel_id: cleanText(chooseRows[0].transfer_channel_id),
+        packet_id: cleanText(chooseRows[0].work_transfer_packet_id) || cleanText(chooseRows[0].packet_id),
+        workflow_run_id: cleanText(chooseRows[0].workflow_run_id) || normalizedWorkflowRunId,
+        stop_reason: null,
+      };
+    }
+    const openChannels = await this.listOpenCommunicationChannels({ workflowRunId: normalizedWorkflowRunId });
+    const openChannelRows = Array.isArray(openChannels) ? openChannels.filter((row) => row && typeof row === 'object') : [];
+    if (openChannelRows.length === 1) {
+      return {
+        channel_id: cleanText(openChannelRows[0].channel_id || openChannelRows[0].transfer_channel_id),
+        packet_id: cleanText(openChannelRows[0].packet_id || openChannelRows[0].work_transfer_packet_id),
+        workflow_run_id: cleanText(openChannelRows[0].workflow_run_id) || normalizedWorkflowRunId,
+        stop_reason: null,
+      };
+    }
+    if (openChannelRows.length > 1) {
+      return {
+        channel_id: null,
+        packet_id: null,
+        workflow_run_id: normalizedWorkflowRunId,
+        stop_reason: {
+          code: 'multiple_open_channels_need_disambiguation',
+          message: 'Multiple open channels matched the requested coordination context.',
+          details: {
+            workflow_run_id: normalizedWorkflowRunId,
+            participant_role: normalizedParticipantRole,
+            candidate_count: openChannelRows.length,
+            candidate_channel_ids: openChannelRows.map((row) => cleanText(row.channel_id || row.transfer_channel_id)).filter(Boolean),
+          },
+        },
+      };
+    }
+    return {
+      channel_id: null,
+      packet_id: null,
+      workflow_run_id: normalizedWorkflowRunId,
+      stop_reason: {
+        code: 'active_channel_not_found',
+        message: 'Active transfer channel not found.',
+        details: {
+          workflow_run_id: normalizedWorkflowRunId,
+          participant_role: normalizedParticipantRole,
+        },
+      },
+    };
+  }
+
   async markParticipantOnline({
     transferChannelId,
     transfer_channel_id,
@@ -802,7 +1002,7 @@ export class AIEngineClient {
       method: 'POST',
       body: {
         transfer_channel_id: normalizedTransferChannelId,
-        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId),
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId) || resolved.packet_id,
         workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
         participant_role: cleanText(participant_role) || cleanText(participantRole),
         current_phase: cleanText(current_phase) || cleanText(currentPhase),
@@ -848,7 +1048,7 @@ export class AIEngineClient {
       method: 'POST',
       body: {
         transfer_channel_id: normalizedTransferChannelId,
-        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId),
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId) || resolved.packet_id,
         workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
         participant_role: cleanText(participant_role) || cleanText(participantRole),
         current_phase: cleanText(current_phase) || cleanText(currentPhase),
@@ -967,7 +1167,7 @@ export class AIEngineClient {
     return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/connect`, {
       method: 'POST',
       body: {
-        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId),
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId) || resolved.packet_id,
         workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
         participant_role: cleanText(participant_role) || cleanText(participantRole),
         expected_peer_role: cleanText(expected_peer_role) || cleanText(expectedPeerRole),
@@ -1676,6 +1876,308 @@ export class AIEngineClient {
     });
   }
 
+  async startCoordinationPingPong({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    participantRole,
+    participant_role,
+    role,
+    expectedPeerRole,
+    expected_peer_role,
+    expectedMessageKind,
+    expected_message_kind,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    packetId,
+    packet_id,
+    workflowRunId,
+    workflow_run_id,
+    proposalId,
+    proposal_id,
+    mode,
+    bodyMarkdown,
+    body_markdown,
+    payload = {},
+    scope = {},
+    metadata = {},
+    staleAfterSeconds,
+    stale_after_seconds,
+  } = {}) {
+    const resolved = await this._resolveCoordinationChannelContext({
+      transferChannelId,
+      transfer_channel_id,
+      channelId,
+      channel_id,
+      workTransferPacketId,
+      work_transfer_packet_id,
+      packetId,
+      packet_id,
+      workflowRunId,
+      workflow_run_id,
+      participantRole,
+      participant_role,
+      role,
+    });
+    if (resolved.stop_reason) {
+      return {
+        started: false,
+        sent: false,
+        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: {
+        transfer_channel_id: resolved.channel_id,
+        participant_role: cleanText(participant_role) || cleanText(participantRole) || cleanText(role),
+        expected_peer_role: cleanText(expected_peer_role) || cleanText(expectedPeerRole),
+        expected_message_kind: cleanText(expected_message_kind) || cleanText(expectedMessageKind),
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId),
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId) || resolved.workflow_run_id,
+        proposal_id: cleanText(proposal_id) || cleanText(proposalId),
+        mode: cleanText(mode) || 'communication_participant',
+        body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+        payload: isPlainObject(payload) ? payload : {},
+        scope: isPlainObject(scope) ? scope : {},
+        metadata: isPlainObject(metadata) ? metadata : {},
+        stale_after_seconds: stale_after_seconds ?? staleAfterSeconds,
+      },
+    });
+  }
+
+  async sendCoordinationPing({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    participantRole,
+    participant_role,
+    role,
+    expectedPeerRole,
+    expected_peer_role,
+    bodyMarkdown,
+    body_markdown,
+    payload = {},
+    scope = {},
+    metadata = {},
+    workflowRunId,
+    workflow_run_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    packetId,
+    packet_id,
+    proposalId,
+    proposal_id,
+    expectedMessageKind,
+    expected_message_kind,
+  } = {}) {
+    const resolved = await this._resolveCoordinationChannelContext({
+      transferChannelId,
+      transfer_channel_id,
+      channelId,
+      channel_id,
+      workTransferPacketId,
+      work_transfer_packet_id,
+      packetId,
+      packet_id,
+      workflowRunId,
+      workflow_run_id,
+      participantRole,
+      participant_role,
+      role,
+    });
+    if (resolved.stop_reason) {
+      return {
+        sent: false,
+        stop_reason: resolved.stop_reason,
+      };
+    }
+    return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(resolved.channel_id)}/coordination/ping-pong/ping`, {
+      method: 'POST',
+      body: {
+        transfer_channel_id: resolved.channel_id,
+        participant_role: cleanText(participant_role) || cleanText(participantRole) || cleanText(role),
+        expected_peer_role: cleanText(expected_peer_role) || cleanText(expectedPeerRole),
+        body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+        payload: isPlainObject(payload) ? payload : {},
+        scope: isPlainObject(scope) ? scope : {},
+        metadata: isPlainObject(metadata) ? metadata : {},
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId) || resolved.workflow_run_id,
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId),
+        proposal_id: cleanText(proposal_id) || cleanText(proposalId),
+        expected_message_kind: cleanText(expected_message_kind) || cleanText(expectedMessageKind),
+      },
+    });
+  }
+
+  async sendCoordinationPong({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    participantRole,
+    participant_role,
+    role,
+    expectedPeerRole,
+    expected_peer_role,
+    bodyMarkdown,
+    body_markdown,
+    payload = {},
+    scope = {},
+    metadata = {},
+    workflowRunId,
+    workflow_run_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    packetId,
+    packet_id,
+    proposalId,
+    proposal_id,
+    expectedMessageKind,
+    expected_message_kind,
+  } = {}) {
+    const resolved = await this._resolveCoordinationChannelContext({
+      transferChannelId,
+      transfer_channel_id,
+      channelId,
+      channel_id,
+      workTransferPacketId,
+      work_transfer_packet_id,
+      packetId,
+      packet_id,
+      workflowRunId,
+      workflow_run_id,
+      participantRole,
+      participant_role,
+      role,
+    });
+    if (resolved.stop_reason) {
+      return {
+        sent: false,
+        stop_reason: resolved.stop_reason,
+      };
+    }
+    return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(resolved.channel_id)}/coordination/ping-pong/pong`, {
+      method: 'POST',
+      body: {
+        transfer_channel_id: resolved.channel_id,
+        participant_role: cleanText(participant_role) || cleanText(participantRole) || cleanText(role),
+        expected_peer_role: cleanText(expected_peer_role) || cleanText(expectedPeerRole),
+        body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+        payload: isPlainObject(payload) ? payload : {},
+        scope: isPlainObject(scope) ? scope : {},
+        metadata: isPlainObject(metadata) ? metadata : {},
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId) || resolved.workflow_run_id,
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId),
+        proposal_id: cleanText(proposal_id) || cleanText(proposalId),
+        expected_message_kind: cleanText(expected_message_kind) || cleanText(expectedMessageKind),
+      },
+    });
+  }
+
+  async getCoordinationPingPongStatus({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    packetId,
+    packet_id,
+    participantRole,
+    participant_role,
+    role,
+    workflowRunId,
+    workflow_run_id,
+  } = {}) {
+    const resolved = await this._resolveCoordinationChannelContext({
+      transferChannelId,
+      transfer_channel_id,
+      channelId,
+      channel_id,
+      workTransferPacketId,
+      work_transfer_packet_id,
+      packetId,
+      packet_id,
+      workflowRunId,
+      workflow_run_id,
+      participantRole,
+      participant_role,
+      role,
+    });
+    if (resolved.stop_reason) {
+      return {
+        verified: false,
+        stop_reason: resolved.stop_reason,
+      };
+    }
+    return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(resolved.channel_id)}/coordination/ping-pong/status`, {
+      query: {
+        participant_role: cleanText(participant_role) || cleanText(participantRole) || cleanText(role),
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId) || resolved.workflow_run_id,
+      },
+    });
+  }
+
+  async stopCoordinationPingPong({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    packetId,
+    packet_id,
+    participantRole,
+    participant_role,
+    role,
+    workflowRunId,
+    workflow_run_id,
+    metadata = {},
+  } = {}) {
+    const resolved = await this._resolveCoordinationChannelContext({
+      transferChannelId,
+      transfer_channel_id,
+      channelId,
+      channel_id,
+      workTransferPacketId,
+      work_transfer_packet_id,
+      packetId,
+      packet_id,
+      workflowRunId,
+      workflow_run_id,
+      participantRole,
+      participant_role,
+      role,
+    });
+    if (resolved.stop_reason) {
+      return {
+        stopped: false,
+        stop_reason: resolved.stop_reason,
+      };
+    }
+    return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(resolved.channel_id)}/coordination/ping-pong/stop`, {
+      method: 'POST',
+      body: {
+        transfer_channel_id: resolved.channel_id,
+        participant_role: cleanText(participant_role) || cleanText(participantRole) || cleanText(role),
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId) || resolved.workflow_run_id,
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
   async verifyMessageSent({ messageId, message_id } = {}) {
     const normalizedMessageId = cleanText(message_id) || cleanText(messageId);
     if (!normalizedMessageId) throw new Error('message_id is required.');
@@ -4954,17 +5456,27 @@ export class AIEngineClient {
       });
       const contentType = response.headers.get('content-type') || '';
       const contentDisposition = response.headers.get('content-disposition') || '';
+      const readResponseText = async () => {
+        if (typeof response.text === 'function') {
+          return response.text();
+        }
+        if (typeof response.json === 'function') {
+          const payload = await response.json();
+          return typeof payload === 'string' ? payload : JSON.stringify(payload);
+        }
+        return '';
+      };
       if (!response.ok) {
         const payload = contentType.includes('application/json')
           ? await response.json()
-          : { message: await response.text() };
+          : { message: await readResponseText() };
         const error = new Error(payload?.message || payload?.error || `Request failed with status ${response.status}.`);
         error.status = response.status;
         error.payload = payload;
         throw error;
       }
       return {
-        text: await response.text(),
+        text: await readResponseText(),
         contentType,
         fileName: parseContentDispositionFilename(contentDisposition),
         headers: Object.fromEntries(response.headers.entries()),