@bpmsoftwaresolutions/ai-engine-client 1.1.57 → 1.1.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.57",
+  "version": "1.1.58",
   "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.58';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -454,6 +454,11 @@ 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),
       connectToTransferChannel: (request) => this.connectToTransferChannel(request),
       respondToMessageWatch: (request) => this.respondToMessageWatch(request),
     };
@@ -482,6 +487,11 @@ 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),
     };
   }
 
@@ -771,6 +781,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 +914,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 +960,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 +1079,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 +1788,299 @@ 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,
+      };
+    }
+    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 +5359,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()),