@bpmsoftwaresolutions/ai-engine-client 1.1.85 → 1.1.87

package/src/domains/ping-pong.js

@@ -0,0 +1,358 @@
+import { AI_ENGINE_CLIENT_VERSION } from '../constants/client.js';
+import { cleanText, isPlainObject } from '../utils/communication.js';
+
+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 buildEligibilityError(message, details = {}) {
+  const error = new Error(message);
+  error.details = details;
+  return error;
+}
+
+export function createPingPongDomain(client) {
+  return {
+    checkCoordinationPingPongPreflight: (request) => checkCoordinationPingPongPreflight(client, request),
+    startCoordinationPingPong: (request) => startCoordinationPingPong(client, request),
+    sendCoordinationPing: (request) => sendCoordinationPing(client, request),
+    sendCoordinationPong: (request) => sendCoordinationPong(client, request),
+    getCoordinationPingPongStatus: (request) => getCoordinationPingPongStatus(client, request),
+    stopCoordinationPingPong: (request) => stopCoordinationPingPong(client, request),
+    pingAgentCommunicationPeer: (request) => sendCoordinationPing(client, request),
+    pongAgentCommunicationPeer: (request) => sendCoordinationPong(client, request),
+  };
+}
+
+export async function checkCoordinationPingPongPreflight(client, { packageVersion } = {}) {
+  const capabilities = await client.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: buildEligibilityError('Coordination Ping Pong is not ready to start.', { 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 function resolveCoordinationChannelContext(client, {
+  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 client.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 client.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 client.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 },
+    },
+  };
+}
+
+export async function startCoordinationPingPong(client, request = {}) {
+  const resolved = await resolveCoordinationChannelContext(client, request);
+  if (resolved.stop_reason) {
+    return { started: false, sent: false, stop_reason: resolved.stop_reason };
+  }
+  const preflight = await checkCoordinationPingPongPreflight(client, { packageVersion: client.clientVersion });
+  if (!preflight.ok) {
+    return { started: false, sent: false, stop_reason: preflight.stop_reason, coordination_ping_pong_preflight: preflight };
+  }
+  const {
+    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,
+  } = request;
+  return client._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,
+    },
+  });
+}
+
+export async function sendCoordinationPing(client, request = {}) {
+  const resolved = await resolveCoordinationChannelContext(client, request);
+  if (resolved.stop_reason) return { sent: false, stop_reason: resolved.stop_reason };
+  const {
+    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,
+  } = request;
+  return client._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),
+    },
+  });
+}
+
+export async function sendCoordinationPong(client, request = {}) {
+  const resolved = await resolveCoordinationChannelContext(client, request);
+  if (resolved.stop_reason) return { sent: false, stop_reason: resolved.stop_reason };
+  const {
+    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,
+  } = request;
+  return client._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),
+    },
+  });
+}
+
+export async function getCoordinationPingPongStatus(client, request = {}) {
+  const resolved = await resolveCoordinationChannelContext(client, request);
+  if (resolved.stop_reason) return { verified: false, stop_reason: resolved.stop_reason };
+  const { participantRole, participant_role, role, workflowRunId, workflow_run_id } = request;
+  return client._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,
+    },
+  });
+}
+
+export async function stopCoordinationPingPong(client, request = {}) {
+  const resolved = await resolveCoordinationChannelContext(client, request);
+  if (resolved.stop_reason) return { stopped: false, stop_reason: resolved.stop_reason };
+  const { participantRole, participant_role, role, workflowRunId, workflow_run_id, metadata = {} } = request;
+  return client._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 : {},
+    },
+  });
+}