@bpmsoftwaresolutions/ai-engine-client 1.1.97 → 1.1.99

package/src/domains/agent-communications.js

@@ -1,4 +1,14 @@
-import { cleanText, isPlainObject, normalizeConnectionFirstMessageKind, normalizeTransferKind } from '../utils/communication.js';
+import {
+  cleanText,
+  isPlainObject,
+  normalizeConnectionFirstMessageKind,
+  normalizeMessageKind,
+  normalizeRecipientMode,
+  normalizeTransferKind,
+  normalizeTransferLifecycleStatus,
+  normalizeTransferMode,
+  normalizeThreadType,
+} from '../utils/communication.js';
 
 function normalizeTransferChannelId(request = {}) {
   return cleanText(request.transfer_channel_id) || cleanText(request.transferChannelId) || cleanText(request.channel_id) || cleanText(request.channelId);
@@ -9,6 +19,29 @@ export function createAgentCommunicationsDomain(client) {
     startAgentConnection: (request) => startAgentConnection(client, request),
     establishAgentCommunicationChannel: (request) => establishAgentCommunicationChannel(client, request),
     runInterAgentMessagingLoop: (request) => runInterAgentMessagingLoop(client, request),
+    bootstrapCommunication: (request) => bootstrapCommunication(client, request),
+    negotiateCommunicationTransfer: (request) => negotiateCommunicationTransfer(client, request),
+    resolveCommunicationTarget: (request) => resolveCommunicationTarget(client, request),
+    createCommunicationEvidencePacket: (request) => createCommunicationEvidencePacket(client, request),
+    listCommunicationFrictionTaxonomy: (request) => listCommunicationFrictionTaxonomy(client, request),
+    recordCommunicationFrictionEvent: (request) => recordCommunicationFrictionEvent(client, request),
+    openCommunicationThread: (request) => openCommunicationThread(client, request),
+    getCommunicationThread: (threadId) => getCommunicationThread(client, threadId),
+    listCommunicationInbox: (request) => listCommunicationInbox(client, request),
+    getMyInbox: (request) => getMyInbox(client, request),
+    verifyMessageSent: (request) => verifyMessageSent(client, request),
+    verifyMessageReceived: (request) => verifyMessageReceived(client, request),
+    getMessageDeliveryReceipt: (request) => getMessageDeliveryReceipt(client, request),
+    _sendAgentCommsMessage: (request) => _sendAgentCommsMessage(client, request),
+    sendCommunicationMessage: (request) => sendCommunicationMessage(client, request),
+    acceptCommunicationTransferPacket: (request) => acceptCommunicationTransferPacket(client, request),
+    closeCommunicationTransferPacket: (request) => closeCommunicationTransferPacket(client, request),
+    getCommunicationTransferHealth: (request) => getCommunicationTransferHealth(client, request),
+    acceptCommunicationMessage: (messageId) => acceptCommunicationMessage(client, messageId),
+    respondToCommunicationMessage: (request) => respondToCommunicationMessage(client, request),
+    attachCommunicationMessageEvidence: (request) => attachCommunicationMessageEvidence(client, request),
+    createCommunicationHandoff: (request) => createCommunicationHandoff(client, request),
+    acceptCommunicationHandoff: (handoffId) => acceptCommunicationHandoff(client, handoffId),
   };
 }
 
@@ -883,3 +916,545 @@ export async function runInterAgentMessagingLoop(client, {
     status_payload: statusPayload,
   };
 }
+
+export async function bootstrapCommunication(client) {
+  return client._request('/api/agent-communications/bootstrap');
+}
+
+export async function negotiateCommunicationTransfer(client, {
+  preferredModes,
+  preferred_modes,
+  preferred,
+  capabilities = {},
+  estimatedPayloadKb,
+  estimated_payload_kb,
+  requiresReceipts = true,
+  requires_receipts = true,
+  supportsHashValidation = true,
+  supports_hash_validation = true,
+  transferKind,
+  transfer_kind,
+  workflowRunId,
+  workflow_run_id,
+} = {}) {
+  const normalizedPreferredModes = Array.isArray(preferred_modes)
+    ? preferred_modes
+    : (Array.isArray(preferredModes) ? preferredModes : (Array.isArray(preferred) ? preferred : ['bundle', 'artifact_refs', 'inline_payload']));
+  return client._request('/api/agent-communications/transfers/negotiate', {
+    method: 'POST',
+    body: {
+      preferred_modes: normalizedPreferredModes.map((mode) => normalizeTransferMode(mode)),
+      capabilities: isPlainObject(capabilities) ? capabilities : {},
+      estimated_payload_kb: Number(estimated_payload_kb ?? estimatedPayloadKb ?? 0) || undefined,
+      requires_receipts: Boolean(requires_receipts ?? requiresReceipts),
+      supports_hash_validation: Boolean(supports_hash_validation ?? supportsHashValidation),
+      transfer_kind: normalizeTransferKind(transfer_kind ?? transferKind ?? 'upstream_remediation'),
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+    },
+  });
+}
+
+export async function resolveCommunicationTarget(client, {
+  intent,
+  transferKind,
+  transfer_kind,
+  recipientMode,
+  recipient_mode,
+  preferredRoleKey,
+  preferred_role_key,
+  preferredAgentSessionId,
+  preferred_agent_session_id,
+  workflowRunId,
+  workflow_run_id,
+} = {}) {
+  return client._request('/api/agent-communications/targets/resolve', {
+    method: 'POST',
+    body: {
+      intent: cleanText(intent) || cleanText(transfer_kind) || cleanText(transferKind),
+      recipient_mode: normalizeRecipientMode(recipient_mode ?? recipientMode ?? 'role'),
+      preferred_role_key: cleanText(preferred_role_key) || cleanText(preferredRoleKey),
+      preferred_agent_session_id: cleanText(preferred_agent_session_id) || cleanText(preferredAgentSessionId),
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+    },
+  });
+}
+
+export async function createCommunicationEvidencePacket(client, {
+  workflowRunId,
+  workflow_run_id,
+  transferKind,
+  transfer_kind,
+  objective,
+  requestedOutcome,
+  requested_outcome,
+  artifacts = [],
+  artifactRefs,
+  artifact_refs,
+  issues = [],
+  issueRefs,
+  issue_refs,
+  expectedEvidence = [],
+  expected_evidence,
+  metadata = {},
+} = {}) {
+  return client._request('/api/agent-communications/evidence-packets', {
+    method: 'POST',
+    body: {
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      transfer_kind: normalizeTransferKind(transfer_kind ?? transferKind ?? 'upstream_remediation'),
+      objective: cleanText(objective),
+      requested_outcome: cleanText(requested_outcome) || cleanText(requestedOutcome),
+      artifacts: Array.isArray(artifacts) ? artifacts : (Array.isArray(artifact_refs) ? artifact_refs : (Array.isArray(artifactRefs) ? artifactRefs : [])),
+      issues: Array.isArray(issues) ? issues : (Array.isArray(issue_refs) ? issue_refs : (Array.isArray(issueRefs) ? issueRefs : [])),
+      expected_evidence: Array.isArray(expected_evidence) ? expected_evidence : (Array.isArray(expectedEvidence) ? expectedEvidence : []),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function listCommunicationFrictionTaxonomy(client, {
+  categoryGroup,
+  category_group,
+  isActive,
+  is_active,
+} = {}) {
+  return client._request('/api/agent-communications/friction-taxonomy', {
+    query: {
+      category_group: cleanText(category_group) || cleanText(categoryGroup),
+      is_active: is_active !== undefined ? String(Boolean(is_active)) : (isActive !== undefined ? String(Boolean(isActive)) : undefined),
+    },
+  });
+}
+
+export async function recordCommunicationFrictionEvent(client, {
+  workflowRunId,
+  workflow_run_id,
+  workTransferPacketId,
+  work_transfer_packet_id,
+  communicationThreadId,
+  communication_thread_id,
+  communicationMessageId,
+  communication_message_id,
+  taxonomyKey,
+  taxonomy_key,
+  frictionType,
+  friction_type,
+  severity,
+  observedBehavior,
+  observed_behavior,
+  attemptedAction,
+  attempted_action,
+  resolutionPath,
+  resolution_path,
+  missingSurfaceKey,
+  missing_surface_key,
+  promotionCandidate,
+  promotion_candidate,
+  repeatedCount,
+  repeated_count,
+  metadata = {},
+} = {}) {
+  return client._request('/api/agent-communications/friction-events', {
+    method: 'POST',
+    body: {
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId),
+      communication_thread_id: cleanText(communication_thread_id) || cleanText(communicationThreadId),
+      communication_message_id: cleanText(communication_message_id) || cleanText(communicationMessageId),
+      taxonomy_key: cleanText(taxonomy_key) || cleanText(taxonomyKey) || 'enum_drift',
+      friction_type: cleanText(friction_type) || cleanText(frictionType) || 'discovery',
+      severity: cleanText(severity) || 'warning',
+      observed_behavior: cleanText(observed_behavior) || cleanText(observedBehavior),
+      attempted_action: cleanText(attempted_action) || cleanText(attemptedAction),
+      resolution_path: cleanText(resolution_path) || cleanText(resolutionPath),
+      missing_surface_key: cleanText(missing_surface_key) || cleanText(missingSurfaceKey),
+      promotion_candidate: Boolean(promotion_candidate ?? promotionCandidate),
+      repeated_count: Number(repeated_count ?? repeatedCount ?? 1) || 1,
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function openCommunicationThread(client, {
+  workflowRunId,
+  workflow_run_id,
+  threadType,
+  thread_type,
+  subject,
+  objective,
+  parentThreadId,
+  parent_thread_id,
+  createdByAgentSessionId,
+  created_by_agent_session_id,
+  createdByActorSessionId,
+  created_by_actor_session_id,
+  metadata,
+} = {}) {
+  return client._request('/api/agent-communications/threads', {
+    method: 'POST',
+    body: {
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      parent_thread_id: cleanText(parent_thread_id) || cleanText(parentThreadId),
+      thread_type: normalizeThreadType(cleanText(thread_type) || cleanText(threadType)),
+      subject: cleanText(subject),
+      objective: cleanText(objective),
+      created_by_agent_session_id: cleanText(created_by_agent_session_id) || cleanText(createdByAgentSessionId),
+      created_by_actor_session_id: cleanText(created_by_actor_session_id) || cleanText(createdByActorSessionId),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function getCommunicationThread(client, threadId) {
+  return client._request(`/api/agent-communications/threads/${encodeURIComponent(threadId)}`);
+}
+
+export async function listCommunicationInbox(client, {
+  recipientAgentSessionId,
+  recipient_agent_session_id,
+  recipientRoleKey,
+  recipient_role_key,
+  workflowRunId,
+  workflow_run_id,
+} = {}) {
+  return client._request('/api/agent-communications/inbox', {
+    query: {
+      recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+      recipient_role_key: cleanText(recipient_role_key) || cleanText(recipientRoleKey),
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+    },
+  });
+}
+
+export async function getMyInbox(client, {
+  recipientAgentSessionId,
+  recipient_agent_session_id,
+  recipientRoleKey,
+  recipient_role_key,
+  workflowRunId,
+  workflow_run_id,
+} = {}) {
+  return client._request('/api/agent-communications/inbox/me', {
+    query: {
+      recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+      recipient_role_key: cleanText(recipient_role_key) || cleanText(recipientRoleKey),
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+    },
+  });
+}
+
+export async function verifyMessageSent(client, { messageId, message_id } = {}) {
+  const normalizedMessageId = cleanText(message_id) || cleanText(messageId);
+  if (!normalizedMessageId) throw new Error('message_id is required.');
+  return client._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/verify-sent`, {
+    method: 'POST',
+    body: { message_id: normalizedMessageId },
+  });
+}
+
+export async function verifyMessageReceived(client, {
+  messageId,
+  message_id,
+  recipientAgentSessionId,
+  recipient_agent_session_id,
+  recipientRole,
+  recipient_role,
+  role,
+  participantId,
+  participant_id,
+} = {}) {
+  const normalizedMessageId = cleanText(message_id) || cleanText(messageId);
+  if (!normalizedMessageId) throw new Error('message_id is required.');
+  return client._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/verify-received`, {
+    method: 'POST',
+    body: {
+      message_id: normalizedMessageId,
+      recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+      recipient_role: cleanText(recipient_role) || cleanText(recipientRole) || cleanText(role),
+      participant_id: cleanText(participant_id) || cleanText(participantId),
+    },
+  });
+}
+
+export async function getMessageDeliveryReceipt(client, { messageId, message_id } = {}) {
+  const normalizedMessageId = cleanText(message_id) || cleanText(messageId);
+  if (!normalizedMessageId) throw new Error('message_id is required.');
+  return client._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/delivery-receipt`, {
+    method: 'GET',
+  });
+}
+
+export async function _sendAgentCommsMessage(client, request = {}) {
+  const hasThreadContext = Boolean(
+    cleanText(request.communication_thread_id)
+    || cleanText(request.communicationThreadId)
+    || cleanText(request.thread_id)
+    || cleanText(request.threadId)
+    || cleanText(request.recipient_role_key)
+    || cleanText(request.recipientRoleKey)
+  );
+  const hasTransferChannelContext = Boolean(
+    cleanText(request.transfer_channel_id)
+    || cleanText(request.transferChannelId)
+    || cleanText(request.channel_id)
+    || cleanText(request.channelId)
+    || cleanText(request.sender_role)
+    || cleanText(request.senderRole)
+    || cleanText(request.recipient_role)
+    || cleanText(request.recipientRole)
+    || cleanText(request.role)
+    || cleanText(request.participant_role)
+    || cleanText(request.participantRole)
+    || cleanText(request.participant_id)
+    || cleanText(request.participantId)
+    || cleanText(request.recipient_participant_id)
+    || cleanText(request.recipientParticipantId)
+  );
+  if (hasTransferChannelContext && !hasThreadContext) {
+    if (
+      cleanText(request.participant_id)
+      || cleanText(request.participantId)
+      || cleanText(request.recipient_participant_id)
+      || cleanText(request.recipientParticipantId)
+      || cleanText(request.recipient_agent_session_id)
+      || cleanText(request.recipientAgentSessionId)
+    ) {
+      return client.sendToParticipant(request);
+    }
+    return client.sendToRole(request);
+  }
+  return client.sendCommunicationMessage(request);
+}
+
+export async function sendCommunicationMessage(client, {
+  communicationThreadId,
+  communication_thread_id,
+  threadId,
+  communicationBundleId,
+  communication_bundle_id,
+  senderAgentSessionId,
+  sender_agent_session_id,
+  recipientAgentSessionId,
+  recipient_agent_session_id,
+  recipientRoleKey,
+  recipient_role_key,
+  messageKind,
+  message_kind,
+  bodyMarkdown,
+  body_markdown,
+  messageStatus,
+  message_status,
+  payload = {},
+  scope = {},
+  requiredResponseSchema = {},
+  required_response_schema = {},
+  metadata = {},
+} = {}) {
+  return client._request('/api/agent-communications/messages', {
+    method: 'POST',
+    body: {
+      communication_thread_id: cleanText(communication_thread_id) || cleanText(communicationThreadId) || cleanText(threadId),
+      communication_bundle_id: cleanText(communication_bundle_id) || cleanText(communicationBundleId),
+      sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || client.agentSessionId,
+      recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+      recipient_role_key: cleanText(recipient_role_key) || cleanText(recipientRoleKey),
+      message_kind: normalizeMessageKind(cleanText(message_kind) || cleanText(messageKind)),
+      message_status: cleanText(message_status) || cleanText(messageStatus) || 'sent',
+      body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+      payload: isPlainObject(payload) ? payload : {},
+      scope: isPlainObject(scope) ? scope : {},
+      required_response_schema: isPlainObject(requiredResponseSchema)
+        ? requiredResponseSchema
+        : (isPlainObject(required_response_schema) ? required_response_schema : {}),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function acceptCommunicationTransferPacket(client, {
+  workTransferPacketId,
+  work_transfer_packet_id,
+  acceptedByAgentSessionId,
+  accepted_by_agent_session_id,
+  acceptedByActorSessionId,
+  accepted_by_actor_session_id,
+  acceptedByClaimId,
+  accepted_by_claim_id,
+  advanceToInProgress,
+  advance_to_in_progress,
+  metadata = {},
+} = {}) {
+  const normalizedPacketId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId);
+  if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+  return client._request(`/api/agent-communications/transfers/${encodeURIComponent(normalizedPacketId)}/accept`, {
+    method: 'POST',
+    body: {
+      accepted_by_agent_session_id: cleanText(accepted_by_agent_session_id) || cleanText(acceptedByAgentSessionId),
+      accepted_by_actor_session_id: cleanText(accepted_by_actor_session_id) || cleanText(acceptedByActorSessionId),
+      accepted_by_claim_id: cleanText(accepted_by_claim_id) || cleanText(acceptedByClaimId),
+      advance_to_in_progress: Boolean(advance_to_in_progress ?? advanceToInProgress),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function closeCommunicationTransferPacket(client, {
+  workTransferPacketId,
+  work_transfer_packet_id,
+  closureStatus,
+  closure_status,
+  closureReason,
+  closure_reason,
+  failureReason,
+  failure_reason,
+  closedByAgentSessionId,
+  closed_by_agent_session_id,
+  closedByActorSessionId,
+  closed_by_actor_session_id,
+  closedByClaimId,
+  closed_by_claim_id,
+  evidence = {},
+  evidenceManifestSha256,
+  evidence_manifest_sha256,
+  metadata = {},
+} = {}) {
+  const normalizedPacketId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId);
+  if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+  return client._request(`/api/agent-communications/transfers/${encodeURIComponent(normalizedPacketId)}/close`, {
+    method: 'POST',
+    body: {
+      closure_status: normalizeTransferLifecycleStatus(cleanText(closure_status) || cleanText(closureStatus) || 'closed'),
+      closure_reason: cleanText(closure_reason) || cleanText(closureReason),
+      failure_reason: cleanText(failure_reason) || cleanText(failureReason),
+      closed_by_agent_session_id: cleanText(closed_by_agent_session_id) || cleanText(closedByAgentSessionId),
+      closed_by_actor_session_id: cleanText(closed_by_actor_session_id) || cleanText(closedByActorSessionId),
+      closed_by_claim_id: cleanText(closed_by_claim_id) || cleanText(closedByClaimId),
+      evidence: isPlainObject(evidence) ? evidence : {},
+      evidence_manifest_sha256: cleanText(evidence_manifest_sha256) || cleanText(evidenceManifestSha256),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function getCommunicationTransferHealth(client, {
+  workflowRunId,
+  workflow_run_id,
+  workTransferPacketId,
+  work_transfer_packet_id,
+} = {}) {
+  return client._request('/api/agent-communications/transfers/health', {
+    query: {
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId),
+    },
+  });
+}
+
+export async function acceptCommunicationMessage(client, messageId) {
+  return client._request(`/api/agent-communications/messages/${encodeURIComponent(messageId)}/accept`, {
+    method: 'POST',
+    body: {},
+  });
+}
+
+export async function respondToCommunicationMessage(client, {
+  agentMessageId,
+  agent_message_id,
+  messageId,
+  status,
+  bodyMarkdown,
+  body_markdown,
+  payload = {},
+  metadata = {},
+  evidenceRefs,
+  evidence_refs,
+} = {}) {
+  const normalizedMessageId = cleanText(agent_message_id) || cleanText(agentMessageId) || cleanText(messageId);
+  if (!normalizedMessageId) {
+    throw new Error('agent_message_id is required.');
+  }
+  return client._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/respond-with-evidence`, {
+    method: 'POST',
+    body: {
+      status: cleanText(status) || 'answered',
+      body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+      payload: isPlainObject(payload) ? payload : {},
+      metadata: isPlainObject(metadata) ? metadata : {},
+      evidence_refs: Array.isArray(evidence_refs) ? evidence_refs : (Array.isArray(evidenceRefs) ? evidenceRefs : []),
+    },
+  });
+}
+
+export async function attachCommunicationMessageEvidence(client, {
+  agentMessageId,
+  agent_message_id,
+  messageId,
+  evidenceType,
+  evidence_type,
+  evidenceRef,
+  evidence_ref,
+  sourceTruth,
+  source_truth,
+  trustLevel,
+  trust_level,
+  metadata = {},
+} = {}) {
+  const normalizedMessageId = cleanText(agent_message_id) || cleanText(agentMessageId) || cleanText(messageId);
+  if (!normalizedMessageId) {
+    throw new Error('agent_message_id is required.');
+  }
+  return client._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/evidence-links`, {
+    method: 'POST',
+    body: {
+      evidence_type: cleanText(evidence_type) || cleanText(evidenceType),
+      evidence_ref: cleanText(evidence_ref) || cleanText(evidenceRef),
+      source_truth: cleanText(source_truth) || cleanText(sourceTruth),
+      trust_level: cleanText(trust_level) || cleanText(trustLevel) || 'candidate',
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function createCommunicationHandoff(client, {
+  workflowRunId,
+  workflow_run_id,
+  title,
+  agentSessionId,
+  agent_session_id,
+  handoffKind,
+  handoff_kind,
+  handoffPriority,
+  handoff_priority,
+  summaryText,
+  summary_text,
+  handoffPayload = {},
+  handoff_payload = {},
+  createdBy,
+  created_by,
+  supersedesHandoffId,
+  supersedes_handoff_id,
+} = {}) {
+  return client._request('/api/agent-communications/handoffs', {
+    method: 'POST',
+    body: {
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      title: cleanText(title),
+      agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+      handoff_kind: cleanText(handoff_kind) || cleanText(handoffKind) || 'general',
+      handoff_priority: cleanText(handoff_priority) || cleanText(handoffPriority) || 'normal',
+      summary_text: cleanText(summary_text) || cleanText(summaryText),
+      handoff_payload: isPlainObject(handoffPayload)
+        ? handoffPayload
+        : (isPlainObject(handoff_payload) ? handoff_payload : {}),
+      created_by: cleanText(created_by) || cleanText(createdBy),
+      supersedes_handoff_id: cleanText(supersedes_handoff_id) || cleanText(supersedesHandoffId),
+    },
+  });
+}
+
+export async function acceptCommunicationHandoff(client, handoffId) {
+  return client._request(`/api/agent-communications/handoffs/${encodeURIComponent(handoffId)}/accept`, {
+    method: 'POST',
+    body: {},
+  });
+}