@bpmsoftwaresolutions/ai-engine-client 1.1.95 → 1.1.98

package/src/domains/agent-communications.js

@@ -0,0 +1,885 @@
+import { cleanText, isPlainObject, normalizeConnectionFirstMessageKind, normalizeTransferKind } from '../utils/communication.js';
+
+function normalizeTransferChannelId(request = {}) {
+  return cleanText(request.transfer_channel_id) || cleanText(request.transferChannelId) || cleanText(request.channel_id) || cleanText(request.channelId);
+}
+
+export function createAgentCommunicationsDomain(client) {
+  return {
+    startAgentConnection: (request) => startAgentConnection(client, request),
+    establishAgentCommunicationChannel: (request) => establishAgentCommunicationChannel(client, request),
+    runInterAgentMessagingLoop: (request) => runInterAgentMessagingLoop(client, request),
+  };
+}
+
+export async function startAgentConnection(client, {
+  workflowRunId,
+  workflow_run_id,
+  upstreamAgent,
+  upstream_agent,
+  upstreamAgentSessionId,
+  upstream_agent_session_id,
+  upstreamAgentId,
+  upstream_agent_id,
+  upstreamRole,
+  upstream_role,
+  recipientMode,
+  recipient_mode,
+  purpose,
+  objective,
+  mode = 'handoff',
+  firstMessage = {},
+  first_message = {},
+  expectedMessageKind,
+  expected_message_kind,
+  participantRole,
+  participant_role,
+  participantLabel,
+  participant_label,
+  senderAgentSessionId,
+  sender_agent_session_id,
+  senderActorSessionId,
+  sender_actor_session_id,
+  cleanupPolicy,
+  cleanup_policy,
+  staleAfterSeconds = 300,
+  stale_after_seconds,
+  operatorNudge,
+  operator_nudge,
+  metadata = {},
+} = {}) {
+  const normalizedFirstMessage = isPlainObject(firstMessage) ? firstMessage : isPlainObject(first_message) ? first_message : {};
+  const normalizedTransferKind = normalizeTransferKind(cleanText(mode) || 'handoff');
+  let normalizedWorkflowRunId = cleanText(workflow_run_id) || cleanText(workflowRunId);
+  if (!normalizedWorkflowRunId) {
+    try {
+      const status = await client.currentWorkflowStatus();
+      normalizedWorkflowRunId =
+        cleanText(status?.workflow_run_id)
+        || cleanText(status?.workflowRunId)
+        || cleanText(status?.current_workflow_run_id)
+        || cleanText(status?.currentWorkflowRunId)
+        || cleanText(status?.summary?.workflow_run_id)
+        || cleanText(status?.summary?.workflowRunId)
+        || cleanText(status?.summary?.current_workflow_run_id)
+        || cleanText(status?.summary?.currentWorkflowRunId);
+    } catch (error) {
+      void error;
+    }
+  }
+  if (!normalizedWorkflowRunId) {
+    throw new Error('workflow_run_id is required to start an agent connection.');
+  }
+  const normalizedUpstreamAgent = cleanText(upstream_agent) || cleanText(upstreamAgent) || cleanText(upstream_agent_session_id) || cleanText(upstreamAgentSessionId) || cleanText(upstream_agent_id) || cleanText(upstreamAgentId);
+  const normalizedRecipientMode = cleanText(recipient_mode) || cleanText(recipientMode) || (normalizedUpstreamAgent ? 'agent_session' : 'role');
+  const normalizedParticipantRole = cleanText(participant_role) || cleanText(participantRole) || 'downstream';
+  const normalizedParticipantLabel = cleanText(participant_label) || cleanText(participantLabel) || normalizedParticipantRole;
+  const normalizedSenderAgentSessionId = cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || client.agentSessionId;
+  const normalizedSenderActorSessionId = cleanText(sender_actor_session_id) || cleanText(senderActorSessionId);
+  const normalizedFirstMessageKind = normalizeConnectionFirstMessageKind(
+    cleanText(normalizedFirstMessage.kind) || cleanText(normalizedFirstMessage.message_kind) || cleanText(normalizedFirstMessage.messageKind),
+    normalizedTransferKind,
+  );
+  const normalizedExpectedMessageKind = cleanText(expected_message_kind) || cleanText(expectedMessageKind) || 'connection_accepted';
+  const normalizedObjective = cleanText(objective) || cleanText(purpose) || cleanText(normalizedFirstMessage.body) || cleanText(normalizedFirstMessage.body_markdown) || cleanText(normalizedFirstMessage.bodyMarkdown) || 'Establish governed coordination.';
+  const transferResult = await client.transferWorkPacket({
+    workflowRunId: normalizedWorkflowRunId,
+    transferKind: normalizedTransferKind,
+    objective: normalizedObjective,
+    requestedOutcome: cleanText(purpose) || normalizedObjective,
+    target: {
+      intent: normalizedTransferKind,
+      recipient_mode: normalizedRecipientMode,
+      preferred_agent_session_id: normalizedUpstreamAgent,
+      preferred_role_key: cleanText(upstream_role) || cleanText(upstreamRole),
+    },
+    artifacts: [],
+    issues: [],
+    expectedEvidence: [],
+    preferredModes: ['inline_payload', 'bundle', 'artifact_refs'],
+    capabilities: {},
+    senderAgentSessionId: normalizedSenderAgentSessionId,
+    senderActorSessionId: normalizedSenderActorSessionId,
+    subject: cleanText(purpose) || normalizedObjective,
+    bodyMarkdown:
+      cleanText(normalizedFirstMessage.body_markdown)
+      || cleanText(normalizedFirstMessage.bodyMarkdown)
+      || cleanText(normalizedFirstMessage.body)
+      || `Connection request: ${normalizedObjective}`,
+    cleanupPolicy: cleanText(cleanup_policy) || cleanText(cleanupPolicy),
+    messageKind: normalizedFirstMessageKind,
+    message_kind: normalizedFirstMessageKind,
+    metadata: isPlainObject(metadata) ? metadata : {},
+  });
+  const transferChannel = transferResult.communication_transfer_channel || {};
+  const connection = await client.connectToTransferChannel({
+    transferChannelId: transferChannel.transfer_channel_id || transferChannel.channel_id || transferResult.channel_id,
+    workTransferPacketId: transferResult.work_transfer_packet?.work_transfer_packet_id || transferResult.packet_id || transferResult.transfer_packet_id,
+    workflowRunId: normalizedWorkflowRunId,
+    participantRole: normalizedParticipantRole,
+    expectedPeerRole: cleanText(upstream_role) || cleanText(upstreamRole) || 'upstream',
+    expectedMessageKind: normalizedExpectedMessageKind,
+    proposalId: transferResult.transfer_negotiation?.proposal_id,
+    mode: 'communication_participant',
+    participantLabel: normalizedParticipantLabel,
+    senderAgentSessionId: normalizedSenderAgentSessionId,
+    senderActorSessionId: normalizedSenderActorSessionId,
+    currentPhase: 'channel_ready',
+    currentTaskSummary: cleanText(purpose) || normalizedObjective,
+    expectedPayload: {
+      purpose: cleanText(purpose) || normalizedObjective,
+      first_message_kind: normalizedFirstMessageKind,
+      first_message_body:
+        cleanText(normalizedFirstMessage.body_markdown)
+        || cleanText(normalizedFirstMessage.bodyMarkdown)
+        || cleanText(normalizedFirstMessage.body)
+        || null,
+    },
+    lastSeenMessageId: transferResult.communication_message?.agent_message_id,
+    staleAfterSeconds: stale_after_seconds ?? staleAfterSeconds,
+    operatorNudge:
+      cleanText(operator_nudge)
+      || cleanText(operatorNudge)
+      || `upstream, please send ${normalizedExpectedMessageKind}.`,
+    observedAt: transferResult.communication_message?.created_at || transferResult.transfer_receipt?.created_at,
+    metadata: {
+      ...(isPlainObject(metadata) ? metadata : {}),
+      start_agent_connection: true,
+    },
+  });
+  const handshake = connection.handshake || {};
+  const status = connection.connected ? 'waiting' : (connection.stop_reason ? 'failed' : 'waiting');
+  const transferPacketId = transferResult.work_transfer_packet?.work_transfer_packet_id || transferResult.transfer_receipt?.transfer_packet_id || transferResult.packet_id || null;
+  const channelId = connection.channel_id || transferChannel.transfer_channel_id || transferChannel.channel_id || null;
+  return {
+    status,
+    channel_id: channelId,
+    transfer_packet_id: transferPacketId,
+    correlation_id: connection.correlation_id || handshake.correlation_id || null,
+    handshake_state: connection.handshake_state || handshake.handshake_state || null,
+    waiting_side: connection.waiting_on || connection.expected_from || handshake.waiting_side || null,
+    expected_message: connection.expected_message_kind || handshake.expected_message_kind || normalizedExpectedMessageKind,
+    last_heartbeat_at: handshake.last_heartbeat_at || connection.collaboration_heartbeat?.observed_at || null,
+    last_receipt_id: handshake.last_receipt_id || transferResult.transfer_receipt?.receipt_id || null,
+    operator_nudge: connection.operator_nudge || handshake.operator_nudge || null,
+    handshake,
+    connection,
+    transfer: transferResult,
+    first_message: {
+      kind: normalizedFirstMessageKind,
+      body: cleanText(normalizedFirstMessage.body_markdown) || cleanText(normalizedFirstMessage.bodyMarkdown) || cleanText(normalizedFirstMessage.body) || null,
+    },
+    transfer_channel: transferChannel,
+    transfer_receipt: transferResult.transfer_receipt || null,
+    communication_message: transferResult.communication_message || null,
+  };
+}
+
+export async function establishAgentCommunicationChannel(client, {
+  projectIdentifier,
+  projectId,
+  claimId,
+  actorId,
+  actorMode = 'operator',
+  executionIntent = 'establish agent communication channel',
+  workflowRunLimit = 5,
+  startWorkBody = {},
+  startWorkRequest = {},
+  resumeProjectWorkOptions = {},
+  transferKind = 'coordination',
+  objective,
+  requestedOutcome,
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  workTransferPacketId,
+  work_transfer_packet_id,
+  packetId,
+  packet_id,
+  participantRole,
+  participant_role,
+  participantLabel,
+  participant_label,
+  participantKind,
+  participant_kind,
+  agentSessionId,
+  agent_session_id,
+  actorSessionId,
+  actor_session_id,
+  upstreamAgentSessionId,
+  upstream_agent_session_id,
+  upstreamActorSessionId,
+  upstream_actor_session_id,
+  downstreamAgentSessionId,
+  downstream_agent_session_id,
+  downstreamActorSessionId,
+  downstream_actor_session_id,
+  expectedMessageKind = 'connection_accepted',
+  expected_message_kind,
+  expectedNextMessage,
+  expected_next_message,
+  currentPhase = 'channel_ready',
+  current_phase,
+  currentTaskSummary,
+  current_task_summary,
+  channelKind = 'bidirectional',
+  channel_kind,
+  includeTransferChannelProjection = true,
+  includeChannelPresenceProjection = true,
+  includeOperatorProjectionMetadata = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const explicitProjectReference = cleanText(projectIdentifier) || cleanText(projectId);
+  const actorIdentity = cleanText(actorId) || client.actorId;
+  const normalizedExecutionIntent = cleanText(executionIntent) || 'establish agent communication channel';
+  const normalizedParticipantRole = cleanText(participant_role) || cleanText(participantRole) || 'downstream';
+  const normalizedParticipantLabel = cleanText(participant_label) || cleanText(participantLabel) || normalizedParticipantRole;
+  const normalizedParticipantKind = cleanText(participant_kind) || cleanText(participantKind) || (
+    cleanText(agent_session_id)
+    || cleanText(agentSessionId)
+    || cleanText(downstream_agent_session_id)
+    || cleanText(downstreamAgentSessionId)
+    || cleanText(upstream_agent_session_id)
+    || cleanText(upstreamAgentSessionId)
+  ) ? 'agent_session' : 'role';
+  const normalizedExpectedMessageKind = cleanText(expected_message_kind) || cleanText(expectedMessageKind) || cleanText(expected_next_message) || cleanText(expectedNextMessage) || 'connection_accepted';
+  const normalizedCurrentPhase = cleanText(current_phase) || cleanText(currentPhase) || 'channel_ready';
+  const normalizedCurrentTaskSummary = cleanText(current_task_summary) || cleanText(currentTaskSummary) || normalizedExecutionIntent;
+  const normalizedObjective = cleanText(objective) || cleanText(requestedOutcome) || normalizedExecutionIntent;
+  const normalizedChannelKind = cleanText(channel_kind) || cleanText(channelKind) || 'bidirectional';
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const hasExplicitChannelReference = Boolean(
+    cleanText(transfer_channel_id)
+    || cleanText(transferChannelId)
+    || cleanText(channel_id)
+    || cleanText(channelId)
+  );
+
+  let continuation = null;
+  let startWorkResult = null;
+  if (explicitProjectReference) {
+    if (typeof client.resumeProjectWork !== 'function') {
+      missingSurfaces.push('resumeProjectWork');
+    } else {
+      continuation = await client.resumeProjectWork({
+        projectIdentifier: explicitProjectReference,
+        projectId: explicitProjectReference,
+        actorMode,
+        executionIntent: normalizedExecutionIntent,
+        requireClaim: false,
+        workflowRunLimit,
+        ...normalizedMetadata.resume_project_work_options,
+        ...resumeProjectWorkOptions,
+      });
+    }
+  } else if (Object.keys(isPlainObject(startWorkRequest) ? startWorkRequest : {}).length > 0 || Object.keys(isPlainObject(startWorkBody) ? startWorkBody : {}).length > 0) {
+    if (typeof client.startWork !== 'function') {
+      missingSurfaces.push('startWork');
+    } else {
+      startWorkResult = await client.startWork({
+        ...(isPlainObject(startWorkBody) ? startWorkBody : {}),
+        ...(isPlainObject(startWorkRequest) ? startWorkRequest : {}),
+      });
+    }
+  } else {
+    throw new Error('projectIdentifier is required.');
+  }
+
+  const projectPayload = isPlainObject(continuation?.project)
+    ? continuation.project
+    : isPlainObject(startWorkResult?.project)
+      ? startWorkResult.project
+      : isPlainObject(continuation?.summary)
+        ? continuation.summary
+        : {};
+  const resolvedProjectId = cleanText(projectPayload.project_id) || cleanText(projectPayload.projectId) || explicitProjectReference;
+  const resolvedWorkflowId = cleanText(projectPayload.workflow_id) || cleanText(projectPayload.workflowId) || cleanText(continuation?.workflow_id) || cleanText(startWorkResult?.workflow_id);
+  const resolvedWorkflowRunId = cleanText(projectPayload.workflow_run_id) || cleanText(projectPayload.workflowRunId) || cleanText(continuation?.workflow_run_id) || cleanText(startWorkResult?.workflow_run_id) || cleanText(startWorkResult?.workflowRunId);
+  if (!resolvedProjectId || !resolvedWorkflowRunId) {
+    throw new Error('project/work identifiers are ambiguous.');
+  }
+
+  const transferPacket = await client.transferWorkPacket({
+    workflowRunId: resolvedWorkflowRunId,
+    transferKind,
+    objective: normalizedObjective,
+    requestedOutcome: normalizedObjective,
+    target: {
+      intent: transferKind,
+      recipient_mode: normalizedParticipantKind === 'agent_session' ? 'agent_session' : 'role',
+      preferred_agent_session_id: cleanText(downstream_agent_session_id) || cleanText(downstreamAgentSessionId) || cleanText(upstream_agent_session_id) || cleanText(upstreamAgentSessionId) || cleanText(agent_session_id) || cleanText(agentSessionId),
+      preferred_role_key: normalizedParticipantRole,
+    },
+    artifacts: [],
+    issues: [],
+    expectedEvidence: [],
+    preferredModes: ['inline_payload', 'bundle', 'artifact_refs'],
+    capabilities: {},
+    senderAgentSessionId: cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+    senderActorSessionId: cleanText(actor_session_id) || cleanText(actorSessionId),
+    subject: normalizedObjective,
+    bodyMarkdown: normalizedCurrentTaskSummary,
+    messageKind: normalizedExpectedMessageKind,
+    metadata: {
+      ...normalizedMetadata,
+      source: 'establishAgentCommunicationChannel',
+      project_id: resolvedProjectId,
+      workflow_id: resolvedWorkflowId,
+      workflow_run_id: resolvedWorkflowRunId,
+    },
+  });
+  const normalizedTransferPacket = isPlainObject(transferPacket) ? transferPacket : {};
+  const transferChannel = isPlainObject(normalizedTransferPacket.communication_transfer_channel)
+    ? normalizedTransferPacket.communication_transfer_channel
+    : {};
+  const resolvedTransferPacketId = cleanText(work_transfer_packet_id)
+    || cleanText(workTransferPacketId)
+    || cleanText(packet_id)
+    || cleanText(packetId)
+    || cleanText(normalizedTransferPacket.work_transfer_packet?.work_transfer_packet_id)
+    || cleanText(normalizedTransferPacket.transfer_packet_id)
+    || cleanText(normalizedTransferPacket.packet_id);
+  const resolvedTransferChannelId = cleanText(transfer_channel_id)
+    || cleanText(transferChannelId)
+    || cleanText(channel_id)
+    || cleanText(channelId)
+    || cleanText(transferChannel.transfer_channel_id)
+    || cleanText(transferChannel.channel_id);
+
+  if (!resolvedTransferPacketId) {
+    throw new Error('transfer packet could not be established.');
+  }
+  if (!resolvedTransferChannelId) {
+    throw new Error('channel ownership is ambiguous.');
+  }
+
+  const openChannelSurface = typeof client.openTransferChannel === 'function'
+    ? client.openTransferChannel.bind(client)
+    : typeof client.openAgentChannel === 'function'
+      ? client.openAgentChannel.bind(client)
+      : typeof client.connectToTransferChannel === 'function'
+        ? client.connectToTransferChannel.bind(client)
+        : null;
+  if (!openChannelSurface) missingSurfaces.push('openTransferChannel');
+  const openChannel = openChannelSurface
+    ? await openChannelSurface({
+        transferChannelId: resolvedTransferChannelId,
+        workTransferPacketId: resolvedTransferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        channelKind: normalizedChannelKind,
+        upstreamAgentSessionId: cleanText(upstream_agent_session_id) || cleanText(upstreamAgentSessionId),
+        upstreamActorSessionId: cleanText(upstream_actor_session_id) || cleanText(upstreamActorSessionId),
+        downstreamAgentSessionId: cleanText(downstream_agent_session_id) || cleanText(downstreamAgentSessionId) || cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+        downstreamActorSessionId: cleanText(downstream_actor_session_id) || cleanText(downstreamActorSessionId) || cleanText(actor_session_id) || cleanText(actorSessionId),
+        evidenceRequiredForClosure: true,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'establishAgentCommunicationChannel',
+          project_id: resolvedProjectId,
+          workflow_id: resolvedWorkflowId,
+          workflow_run_id: resolvedWorkflowRunId,
+        },
+      })
+    : null;
+  const openChannelPayload = isPlainObject(openChannel?.transfer_channel)
+    ? openChannel.transfer_channel
+    : isPlainObject(openChannel?.collaboration_participant)
+      ? openChannel.collaboration_participant
+      : isPlainObject(openChannel)
+        ? openChannel
+        : {};
+  const openedChannelId = cleanText(openChannelPayload.transfer_channel_id) || cleanText(openChannelPayload.channel_id) || resolvedTransferChannelId;
+
+  const joinSurfaceName = hasExplicitChannelReference ? 'resumeTransferChannel' : 'joinTransferChannel';
+  const joinSurface = typeof client[joinSurfaceName] === 'function'
+    ? client[joinSurfaceName].bind(client)
+    : typeof client.joinTransferChannel === 'function'
+      ? client.joinTransferChannel.bind(client)
+      : typeof client.resumeTransferChannel === 'function'
+        ? client.resumeTransferChannel.bind(client)
+        : null;
+  if (!joinSurface) missingSurfaces.push(joinSurfaceName);
+  const participantRecord = joinSurface
+    ? await joinSurface({
+        transferChannelId: openedChannelId,
+        workTransferPacketId: resolvedTransferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: normalizedParticipantRole,
+        participantKind: normalizedParticipantKind,
+        participantLabel: normalizedParticipantLabel,
+        agentSessionId: cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+        actorSessionId: cleanText(actor_session_id) || cleanText(actorSessionId),
+        currentPhase: normalizedCurrentPhase,
+        currentTaskSummary: normalizedCurrentTaskSummary,
+        lastSeenMessageId: cleanText(normalizedTransferPacket.communication_message?.agent_message_id),
+        lastSeenAt: cleanText(normalizedTransferPacket.communication_message?.created_at) || cleanText(openChannel?.created_at),
+        lastSeenHeartbeatAt: cleanText(openChannel?.heartbeat?.observed_at) || cleanText(openChannel?.collaboration_heartbeat?.observed_at),
+        metadata: {
+          ...normalizedMetadata,
+          source: 'establishAgentCommunicationChannel',
+          project_id: resolvedProjectId,
+          workflow_id: resolvedWorkflowId,
+          workflow_run_id: resolvedWorkflowRunId,
+        },
+      })
+    : null;
+
+  const heartbeatSurface = typeof client.postCollaborationHeartbeat === 'function'
+    ? client.postCollaborationHeartbeat.bind(client)
+    : typeof client.postAgentHeartbeat === 'function'
+      ? client.postAgentHeartbeat.bind(client)
+      : null;
+  if (!heartbeatSurface) missingSurfaces.push('postCollaborationHeartbeat');
+  const heartbeat = heartbeatSurface
+    ? await heartbeatSurface({
+        transferChannelId: openedChannelId,
+        workTransferPacketId: resolvedTransferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: normalizedParticipantRole,
+        activityState: 'active',
+        agentSessionId: cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+        actorSessionId: cleanText(actor_session_id) || cleanText(actorSessionId),
+        currentPhase: normalizedCurrentPhase,
+        currentTaskSummary: normalizedCurrentTaskSummary,
+        isActive: true,
+        observedAt: cleanText(normalizedTransferPacket.communication_message?.created_at) || cleanText(openChannel?.created_at),
+        metadata: {
+          ...normalizedMetadata,
+          source: 'establishAgentCommunicationChannel',
+          project_id: resolvedProjectId,
+          workflow_id: resolvedWorkflowId,
+          workflow_run_id: resolvedWorkflowRunId,
+        },
+      })
+    : null;
+
+  const status = await client.getCommunicationChannelStatus({ transferChannelId: openedChannelId }).catch(() => null);
+  const participants = await client.getCommunicationChannelParticipants({ transferChannelId: openedChannelId }).catch(() => null);
+  const transferChannelProjectionSurface = typeof client.getTransferChannelProjection === 'function'
+    ? client.getTransferChannelProjection.bind(client)
+    : typeof client.getLogaTransferChannelThreadProjection === 'function'
+      ? client.getLogaTransferChannelThreadProjection.bind(client)
+      : null;
+  if (!transferChannelProjectionSurface) missingSurfaces.push('getTransferChannelProjection');
+  const transferChannelProjection = includeTransferChannelProjection && transferChannelProjectionSurface
+    ? await transferChannelProjectionSurface(openedChannelId).catch(() => null)
+    : null;
+  const channelPresence = includeChannelPresenceProjection
+    ? await client.getChannelPresence({ transferChannelId: openedChannelId }).catch(() => null)
+    : null;
+
+  const statusPayload = isPlainObject(status) ? status : {};
+  const participantPayload = isPlainObject(participants) ? participants : {};
+  const participantRows = Array.isArray(participantPayload.participants)
+    ? participantPayload.participants.filter((row) => isPlainObject(row))
+    : Array.isArray(participantPayload.collaboration_participants)
+      ? participantPayload.collaboration_participants.filter((row) => isPlainObject(row))
+      : [];
+  const waitingSide = cleanText(statusPayload.waiting_side)
+    || cleanText(statusPayload.operator_state?.waiting_side)
+    || cleanText(openChannel?.waiting_side)
+    || cleanText(heartbeat?.waiting_side)
+    || null;
+  const nextMessage = cleanText(statusPayload.next_message_kind)
+    || cleanText(statusPayload.expected_message_kind)
+    || cleanText(statusPayload.next_action)
+    || cleanText(openChannel?.expected_message_kind)
+    || cleanText(heartbeat?.expected_message_kind)
+    || normalizedExpectedMessageKind;
+  const heartbeatStatus = cleanText(heartbeat?.collaboration_heartbeat?.activity_state)
+    || cleanText(heartbeat?.activity_state)
+    || cleanText(heartbeat?.status)
+    || 'active';
+
+  const operatorProjectionMetadata = includeOperatorProjectionMetadata
+    ? {
+        transfer_channel_projection: transferChannelProjection,
+        channel_status: statusPayload,
+        channel_participants: participantPayload,
+        channel_presence: channelPresence,
+      }
+    : null;
+
+  const established = Boolean(openedChannelId && resolvedTransferPacketId && heartbeat);
+  return {
+    status: missingSurfaces.length > 0 ? 'partial' : established ? 'ready' : 'blocked',
+    project_id: resolvedProjectId,
+    workflow_id: resolvedWorkflowId,
+    workflow_run_id: resolvedWorkflowRunId,
+    transfer_packet_id: resolvedTransferPacketId,
+    channel_id: openedChannelId,
+    participants: participantRows.length > 0 ? participantRows : [participantRecord].filter(Boolean),
+    waiting_side: waitingSide,
+    expected_next_message: nextMessage,
+    heartbeat_status: heartbeatStatus,
+    operator_projection_metadata: operatorProjectionMetadata,
+    missing_surfaces: [...new Set(missingSurfaces)],
+    project_continuation: continuation,
+    start_work: startWorkResult,
+    transfer_packet: normalizedTransferPacket,
+    open_channel: openChannel,
+    channel_participant: participantRecord,
+    heartbeat,
+    status_payload: statusPayload,
+  };
+}
+
+export async function runInterAgentMessagingLoop(client, {
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  workTransferPacketId,
+  work_transfer_packet_id,
+  workflowRunId,
+  workflow_run_id,
+  participantRole,
+  participant_role,
+  watchingAgentRole,
+  watching_agent_role,
+  expectedFromRole,
+  expected_from_role,
+  expectedMessageKind,
+  expected_message_kind,
+  expectedNextMessage,
+  expected_next_message,
+  replyRequest = {},
+  reply_request = {},
+  replyBodyMarkdown,
+  reply_body_markdown,
+  replyMessageKind,
+  reply_message_kind,
+  replyPayload = {},
+  reply_payload = {},
+  replyScope = {},
+  reply_scope = {},
+  replyEvidenceRefs = [],
+  reply_evidence_refs = [],
+  replyRecipientAgentSessionId,
+  reply_recipient_agent_session_id,
+  replyRecipientActorSessionId,
+  reply_recipient_actor_session_id,
+  replySenderAgentSessionId,
+  reply_sender_agent_session_id,
+  replySenderActorSessionId,
+  reply_sender_actor_session_id,
+  watchRequest = {},
+  watch_request = {},
+  acknowledgeRequest = {},
+  acknowledge_request = {},
+  heartbeatRequest = {},
+  heartbeat_request = {},
+  closeWhenAcknowledged = false,
+  close_when_acknowledged = false,
+  requestClosure = false,
+  request_closure = false,
+  closureReason,
+  closure_reason,
+  failureReason,
+  failure_reason,
+  closureEvidence = {},
+  closure_evidence = {},
+  closureEvidenceManifestSha256,
+  closure_evidence_manifest_sha256,
+  includeTransferChannelProjection = true,
+  includeOperatorProjectionMetadata = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  let normalizedPacketId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId);
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const normalizedReplyRequest = isPlainObject(reply_request) ? reply_request : (isPlainObject(replyRequest) ? replyRequest : {});
+  const normalizedWatchRequest = isPlainObject(watch_request) ? watch_request : (isPlainObject(watchRequest) ? watchRequest : {});
+  const normalizedAcknowledgeRequest = isPlainObject(acknowledge_request) ? acknowledge_request : (isPlainObject(acknowledgeRequest) ? acknowledgeRequest : {});
+  const normalizedHeartbeatRequest = isPlainObject(heartbeat_request) ? heartbeat_request : (isPlainObject(heartbeatRequest) ? heartbeatRequest : {});
+  const normalizedClosureEvidence = isPlainObject(closure_evidence) ? closure_evidence : (isPlainObject(closureEvidence) ? closureEvidence : {});
+  const shouldClose = Boolean(close_when_acknowledged || closeWhenAcknowledged || request_closure || requestClosure);
+
+  if (!normalizedPacketId) {
+    try {
+      const status = await client.getCommunicationChannelStatus({ transferChannelId: normalizedTransferChannelId });
+      normalizedPacketId = cleanText(status?.packet_id || status?.packetId || status?.work_transfer_packet_id);
+    } catch (error) {
+      void error;
+    }
+  }
+  if (!normalizedPacketId) {
+    throw new Error('work_transfer_packet_id is required.');
+  }
+
+  const resumeSurface = typeof client.resumeTransferChannel === 'function'
+    ? client.resumeTransferChannel.bind(client)
+    : null;
+  if (!resumeSurface) missingSurfaces.push('resumeTransferChannel');
+  const resumedChannel = resumeSurface
+    ? await resumeSurface({
+        transferChannelId: normalizedTransferChannelId,
+        workTransferPacketId: normalizedPacketId,
+        workflowRunId: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        participantRole: cleanText(participant_role) || cleanText(participantRole) || cleanText(watching_agent_role) || cleanText(watchingAgentRole) || 'downstream',
+        participantKind: 'agent_session',
+        participantLabel: cleanText(participant_role) || cleanText(participantRole) || cleanText(watching_agent_role) || cleanText(watchingAgentRole) || 'downstream',
+        agentSessionId: client.agentSessionId,
+        currentPhase: 'message_loop',
+        currentTaskSummary: cleanText(expected_next_message) || cleanText(expectedNextMessage) || 'Await expected message.',
+        lastSeenMessageId: cleanText(normalizedReplyRequest.transfer_channel_message_id) || cleanText(normalizedReplyRequest.transferChannelMessageId),
+        metadata: {
+          ...normalizedMetadata,
+          source: 'runInterAgentMessagingLoop',
+        },
+      })
+    : null;
+
+  const replySurface = typeof client.replyToTransferChannel === 'function'
+    ? client.replyToTransferChannel.bind(client)
+    : null;
+  if (!replySurface) missingSurfaces.push('replyToTransferChannel');
+  const replyBody = normalizedReplyRequest.body_markdown || normalizedReplyRequest.bodyMarkdown || reply_body_markdown || replyBodyMarkdown;
+  const shouldReply = Boolean(
+    replyBody
+    || normalizedReplyRequest.body
+    || normalizedReplyRequest.message_kind
+    || normalizedReplyRequest.messageKind
+    || cleanText(reply_message_kind)
+    || cleanText(replyMessageKind)
+    || Object.keys(normalizedReplyRequest).length > 0
+  );
+  const replyResult = shouldReply && replySurface
+    ? await replySurface({
+        transferChannelId: normalizedTransferChannelId,
+        senderAgentSessionId: cleanText(normalizedReplyRequest.sender_agent_session_id) || cleanText(normalizedReplyRequest.senderAgentSessionId) || cleanText(reply_sender_agent_session_id) || cleanText(replySenderAgentSessionId) || client.agentSessionId,
+        senderActorSessionId: cleanText(normalizedReplyRequest.sender_actor_session_id) || cleanText(normalizedReplyRequest.senderActorSessionId) || cleanText(reply_sender_actor_session_id) || cleanText(replySenderActorSessionId),
+        recipientAgentSessionId: cleanText(normalizedReplyRequest.recipient_agent_session_id) || cleanText(normalizedReplyRequest.recipientAgentSessionId) || cleanText(reply_recipient_agent_session_id) || cleanText(replyRecipientAgentSessionId),
+        recipientActorSessionId: cleanText(normalizedReplyRequest.recipient_actor_session_id) || cleanText(normalizedReplyRequest.recipientActorSessionId) || cleanText(reply_recipient_actor_session_id) || cleanText(replyRecipientActorSessionId),
+        messageKind: cleanText(normalizedReplyRequest.message_kind) || cleanText(normalizedReplyRequest.messageKind) || cleanText(reply_message_kind) || cleanText(replyMessageKind) || cleanText(expected_next_message) || cleanText(expectedNextMessage) || 'response',
+        bodyMarkdown: cleanText(reply_body_markdown) || cleanText(replyBodyMarkdown) || cleanText(normalizedReplyRequest.body_markdown) || cleanText(normalizedReplyRequest.bodyMarkdown) || cleanText(normalizedReplyRequest.body),
+        transferChannelMessageStatus: cleanText(normalizedReplyRequest.message_status) || cleanText(normalizedReplyRequest.messageStatus),
+        payload: isPlainObject(normalizedReplyRequest.payload) ? normalizedReplyRequest.payload : (isPlainObject(reply_payload) ? reply_payload : (isPlainObject(replyPayload) ? replyPayload : {})),
+        scope: isPlainObject(normalizedReplyRequest.scope) ? normalizedReplyRequest.scope : (isPlainObject(reply_scope) ? reply_scope : (isPlainObject(replyScope) ? replyScope : {})),
+        requiredResponseSchema: isPlainObject(normalizedReplyRequest.required_response_schema) ? normalizedReplyRequest.required_response_schema : (isPlainObject(normalizedReplyRequest.requiredResponseSchema) ? normalizedReplyRequest.requiredResponseSchema : null),
+        evidenceRefs: Array.isArray(normalizedReplyRequest.evidence_refs) ? normalizedReplyRequest.evidence_refs : (Array.isArray(reply_evidence_refs) ? reply_evidence_refs : replyEvidenceRefs),
+        metadata: {
+          ...normalizedMetadata,
+          source: 'runInterAgentMessagingLoop',
+        },
+        closureReason: cleanText(normalizedReplyRequest.closure_reason) || cleanText(normalizedReplyRequest.closureReason) || cleanText(closure_reason) || cleanText(closureReason),
+        failureReason: cleanText(normalizedReplyRequest.failure_reason) || cleanText(normalizedReplyRequest.failureReason) || cleanText(failure_reason) || cleanText(failureReason),
+        currentWaitingSide: cleanText(normalizedReplyRequest.current_waiting_side) || cleanText(normalizedReplyRequest.currentWaitingSide),
+      })
+    : null;
+
+  const normalizedReplyPayload = isPlainObject(replyResult) ? replyResult : {};
+  const messageId = cleanText(normalizedReplyPayload.transfer_channel_message?.transfer_channel_message_id)
+    || cleanText(normalizedReplyPayload.communication_message?.transfer_channel_message_id)
+    || cleanText(normalizedReplyPayload.communication_message?.agent_message_id)
+    || cleanText(normalizedReplyPayload.transfer_channel_message_id)
+    || cleanText(normalizedReplyPayload.message_id)
+    || cleanText(normalizedReplyPayload.communication_message?.message_id)
+    || null;
+  const receiptId = cleanText(normalizedReplyPayload.transfer_channel_receipt?.transfer_channel_receipt_id)
+    || cleanText(normalizedReplyPayload.transfer_channel_receipt_id)
+    || cleanText(normalizedReplyPayload.receipt_id)
+    || null;
+
+  const watchSurface = typeof client.startMessageWatch === 'function'
+    ? client.startMessageWatch.bind(client)
+    : null;
+  if (!watchSurface) missingSurfaces.push('startMessageWatch');
+  const startedWatch = watchSurface
+    ? await watchSurface({
+        transferChannelId: normalizedTransferChannelId,
+        workTransferPacketId: normalizedPacketId,
+        workflowRunId: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        watchingAgentRole: cleanText(watching_agent_role) || cleanText(watchingAgentRole) || 'upstream',
+        expectedFromRole: cleanText(expected_from_role) || cleanText(expectedFromRole) || cleanText(participant_role) || cleanText(participantRole) || 'downstream',
+        expectedMessageKind: cleanText(expected_message_kind) || cleanText(expectedMessageKind) || cleanText(expected_next_message) || cleanText(expectedNextMessage) || 'response',
+        watchType: cleanText(normalizedWatchRequest.watch_type) || cleanText(normalizedWatchRequest.watchType) || 'expected_peer_message',
+        watchingAgentSessionId: cleanText(normalizedWatchRequest.watching_agent_session_id) || cleanText(normalizedWatchRequest.watchingAgentSessionId) || client.agentSessionId,
+        watchingActorSessionId: cleanText(normalizedWatchRequest.watching_actor_session_id) || cleanText(normalizedWatchRequest.watchingActorSessionId),
+        expectedPayload: isPlainObject(normalizedWatchRequest.expected_payload) ? normalizedWatchRequest.expected_payload : (isPlainObject(normalizedWatchRequest.expectedPayload) ? normalizedWatchRequest.expectedPayload : {}),
+        lastSeenMessageId: cleanText(normalizedWatchRequest.last_seen_message_id) || cleanText(normalizedWatchRequest.lastSeenMessageId) || messageId,
+        lastCheckedAt: normalizedWatchRequest.last_checked_at || normalizedWatchRequest.lastCheckedAt,
+        staleAfterSeconds: normalizedWatchRequest.stale_after_seconds ?? normalizedWatchRequest.staleAfterSeconds,
+        currentStatus: cleanText(normalizedWatchRequest.current_status) || cleanText(normalizedWatchRequest.currentStatus) || 'watching',
+        operatorNudge: cleanText(normalizedWatchRequest.operator_nudge) || cleanText(normalizedWatchRequest.operatorNudge),
+        blockedReason: cleanText(normalizedWatchRequest.blocked_reason) || cleanText(normalizedWatchRequest.blockedReason),
+        metadata: {
+          ...normalizedMetadata,
+          source: 'runInterAgentMessagingLoop',
+        },
+      })
+    : null;
+
+  const watchPayload = isPlainObject(startedWatch) ? startedWatch : {};
+  const watchRecord = isPlainObject(watchPayload.message_watch)
+    ? watchPayload.message_watch
+    : (isPlainObject(watchPayload.messageWatch) ? watchPayload.messageWatch : watchPayload);
+  const watchId = cleanText(watchRecord.message_watch_id)
+    || cleanText(watchRecord.watch_id)
+    || null;
+  const observedMessageId = messageId || cleanText(normalizedAcknowledgeRequest.observed_message_id) || cleanText(normalizedAcknowledgeRequest.observedMessageId);
+  const ackSurface = typeof client.acknowledgeExpectedMessage === 'function'
+    ? client.acknowledgeExpectedMessage.bind(client)
+    : null;
+  if (!ackSurface) missingSurfaces.push('acknowledgeExpectedMessage');
+  const acknowledgedResult = ackSurface
+    ? await ackSurface({
+        transferChannelId: normalizedTransferChannelId,
+        messageWatchId: watchId || cleanText(normalizedAcknowledgeRequest.message_watch_id) || cleanText(normalizedAcknowledgeRequest.messageWatchId) || cleanText(normalizedAcknowledgeRequest.watch_id) || cleanText(normalizedAcknowledgeRequest.watchId),
+        observedMessageId,
+        observedMessageKind: cleanText(normalizedAcknowledgeRequest.observed_message_kind) || cleanText(normalizedAcknowledgeRequest.observedMessageKind) || cleanText(expected_next_message) || cleanText(expectedNextMessage),
+        lastCheckedAt: normalizedAcknowledgeRequest.last_checked_at || normalizedAcknowledgeRequest.lastCheckedAt,
+        operatorNudge: cleanText(normalizedAcknowledgeRequest.operator_nudge) || cleanText(normalizedAcknowledgeRequest.operatorNudge),
+        metadata: {
+          ...normalizedMetadata,
+          source: 'runInterAgentMessagingLoop',
+        },
+      })
+    : null;
+  const acknowledged = Boolean(acknowledgedResult);
+
+  const heartbeatSurface = typeof client.postCollaborationHeartbeat === 'function'
+    ? client.postCollaborationHeartbeat.bind(client)
+    : typeof client.postAgentHeartbeat === 'function'
+      ? client.postAgentHeartbeat.bind(client)
+      : null;
+  if (!heartbeatSurface) missingSurfaces.push('postCollaborationHeartbeat');
+  const heartbeatResult = heartbeatSurface
+    ? await heartbeatSurface({
+        transferChannelId: normalizedTransferChannelId,
+        workTransferPacketId: normalizedPacketId,
+        workflowRunId: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        participantRole: cleanText(participant_role) || cleanText(participantRole) || cleanText(watching_agent_role) || cleanText(watchingAgentRole) || 'downstream',
+        activityState: 'active',
+        agentSessionId: client.agentSessionId,
+        actorSessionId: cleanText(normalizedHeartbeatRequest.actor_session_id) || cleanText(normalizedHeartbeatRequest.actorSessionId),
+        currentPhase: cleanText(normalizedHeartbeatRequest.current_phase) || cleanText(normalizedHeartbeatRequest.currentPhase) || 'message_loop',
+        currentTaskSummary: cleanText(normalizedHeartbeatRequest.current_task_summary) || cleanText(normalizedHeartbeatRequest.currentTaskSummary) || cleanText(expected_next_message) || cleanText(expectedNextMessage) || 'Await expected message.',
+        isActive: normalizedHeartbeatRequest.is_active ?? normalizedHeartbeatRequest.isActive ?? true,
+        observedAt: normalizedHeartbeatRequest.observed_at || normalizedHeartbeatRequest.observedAt,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'runInterAgentMessagingLoop',
+        },
+      })
+    : null;
+
+  const transferChannelProjectionSurface = typeof client.getTransferChannelProjection === 'function'
+    ? client.getTransferChannelProjection.bind(client)
+    : typeof client.getLogaTransferChannelThreadProjection === 'function'
+      ? client.getLogaTransferChannelThreadProjection.bind(client)
+      : null;
+  if (!transferChannelProjectionSurface) missingSurfaces.push('getTransferChannelProjection');
+  const transferChannelProjection = includeTransferChannelProjection && transferChannelProjectionSurface
+    ? await transferChannelProjectionSurface(normalizedTransferChannelId).catch(() => null)
+    : null;
+
+  const closureRequested = Boolean(shouldClose && acknowledged);
+  const closeSurface = typeof client.closeTransferChannel === 'function'
+    ? client.closeTransferChannel.bind(client)
+    : null;
+  if (!closeSurface) missingSurfaces.push('closeTransferChannel');
+  const closeResult = closureRequested && closeSurface
+    ? await closeSurface({
+        transferChannelId: normalizedTransferChannelId,
+        closureStatus: 'closed',
+        closureReason: cleanText(closure_reason) || cleanText(closureReason) || 'expected message loop completed',
+        failureReason: cleanText(failure_reason) || cleanText(failureReason),
+        evidence: normalizedClosureEvidence,
+        evidenceManifestSha256: cleanText(closure_evidence_manifest_sha256) || cleanText(closureEvidenceManifestSha256),
+        closedByAgentSessionId: client.agentSessionId,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'runInterAgentMessagingLoop',
+        },
+      })
+    : null;
+
+  const closePayload = isPlainObject(closeResult) ? closeResult : {};
+  const channelClosed = Boolean(
+    closePayload.closed
+    || closePayload.closed_channel
+    || closePayload.channel_closed
+    || closePayload.closed_at
+    || closePayload.transfer_channel?.channel_status === 'closed'
+    || closePayload.communication_transfer_channel?.channel_status === 'closed'
+  );
+  const statusPayload = {
+    transfer_channel: resumedChannel || null,
+    watch: startedWatch || null,
+    reply: replyResult || null,
+    acknowledge: acknowledgedResult || null,
+    heartbeat: heartbeatResult || null,
+    close: closeResult || null,
+    transfer_channel_projection: transferChannelProjection,
+  };
+
+  const waitingSide = cleanText(
+    watchRecord.waiting_side
+    || watchRecord.expected_from_role
+    || watchRecord.expectedFromRole
+    || normalizedReplyPayload.current_waiting_side
+    || normalizedReplyPayload.currentWaitingSide
+    || normalizedReplyPayload.waiting_side
+    || normalizedReplyPayload.waitingSide
+    || heartbeatResult?.waiting_side
+    || resumedChannel?.waiting_side
+  ) || null;
+  const expectedNext = cleanText(
+    watchRecord.expected_message_kind
+    || watchRecord.expectedMessageKind
+    || normalizedReplyPayload.next_message_kind
+    || normalizedReplyPayload.expected_next_message
+    || normalizedReplyPayload.expectedNextMessage
+    || heartbeatResult?.expected_message_kind
+    || expected_message_kind
+    || expectedMessageKind
+    || expected_next_message
+    || expectedNextMessage
+  ) || null;
+  const heartbeatStatus = cleanText(
+    heartbeatResult?.collaboration_heartbeat?.activity_state
+    || heartbeatResult?.activity_state
+    || heartbeatResult?.status
+    || heartbeatResult?.heartbeat_status
+  ) || (heartbeatResult ? 'active' : 'missing');
+
+  const operatorProjectionMetadata = includeOperatorProjectionMetadata
+    ? {
+        transfer_channel_projection: transferChannelProjection,
+        watch: startedWatch,
+        reply: replyResult,
+        acknowledge: acknowledgedResult,
+        heartbeat: heartbeatResult,
+        close: closeResult,
+      }
+    : null;
+
+  const established = Boolean(normalizedTransferChannelId && normalizedPacketId);
+  return {
+    status: missingSurfaces.length > 0 ? 'partial' : channelClosed ? 'closed' : established ? 'waiting' : 'blocked',
+    channel_id: normalizedTransferChannelId,
+    message_id: messageId || null,
+    receipt_id: receiptId || null,
+    watch_id: watchId || null,
+    waiting_side: waitingSide,
+    expected_next_message: expectedNext,
+    acknowledged,
+    heartbeat_status: heartbeatStatus,
+    closure_requested: closureRequested,
+    channel_closed: channelClosed,
+    operator_projection_metadata: operatorProjectionMetadata,
+    missing_surfaces: [...new Set(missingSurfaces)],
+    transfer_channel: resumedChannel,
+    message_watch: startedWatch,
+    reply: replyResult,
+    acknowledge: acknowledgedResult,
+    heartbeat: heartbeatResult,
+    close: closeResult,
+    status_payload: statusPayload,
+  };
+}