@bpmsoftwaresolutions/ai-engine-client 1.1.85 → 1.1.87

package/src/domains/transfer-channels.js

@@ -0,0 +1,664 @@
+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);
+}
+
+async function resolveTransferPacketId(client, transferChannelId, request = {}) {
+  let normalizedPacketId = cleanText(request.work_transfer_packet_id) || cleanText(request.workTransferPacketId) || cleanText(request.packet_id) || cleanText(request.packetId);
+  if (!normalizedPacketId) {
+    try {
+      const status = await client.getCommunicationChannelStatus({ transferChannelId });
+      normalizedPacketId = cleanText(status?.packet_id || status?.packetId || status?.work_transfer_packet_id);
+    } catch (error) {
+      void error;
+    }
+  }
+  return normalizedPacketId;
+}
+
+export function createTransferChannelsDomain(client) {
+  return {
+    listCommunicationChannels: (request) => listCommunicationChannels(client, request),
+    listOpenCommunicationChannels: (request) => listOpenCommunicationChannels(client, request),
+    getCommunicationChannelStatus: (request) => getCommunicationChannelStatus(client, request),
+    getCommunicationChannelParticipants: (request) => getCommunicationChannelParticipants(client, request),
+    openTransferChannel: (request) => openTransferChannel(client, request),
+    joinTransferChannel: (request) => joinTransferChannel(client, request),
+    resumeTransferChannel: (request) => resumeTransferChannel(client, request),
+    replyToTransferChannel: (request) => replyToTransferChannel(client, request),
+    closeTransferChannel: (request) => closeTransferChannel(client, request),
+    requestTransferClosure: (request) => requestTransferClosure(client, request),
+    openAgentChannel: (request) => openAgentChannel(client, request),
+    connectToTransferChannel: (request) => connectToTransferChannel(client, request),
+    startAgentConnection: (request) => startAgentConnection(client, request),
+    postAgentHeartbeat: (request) => postAgentHeartbeat(client, request),
+    closeAgentChannel: (request) => closeAgentChannel(client, request),
+  };
+}
+
+export async function listCommunicationChannels(client, {
+  workflowRunId,
+  workflow_run_id,
+  workTransferPacketId,
+  work_transfer_packet_id,
+  status,
+  channelStatus,
+  channel_status,
+} = {}) {
+  return client._request('/api/agent-communications/transfer-channels', {
+    query: {
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId),
+      status: cleanText(status) || cleanText(channel_status) || cleanText(channelStatus),
+    },
+  });
+}
+
+export async function listOpenCommunicationChannels(client, request = {}) {
+  return listCommunicationChannels(client, { ...request, status: 'open' });
+}
+
+export async function getCommunicationChannelStatus(client, {
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+} = {}) {
+  const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+  if (!normalizedTransferChannelId) throw new Error('transferChannelId is required.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/status`);
+}
+
+export async function getCommunicationChannelParticipants(client, {
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+} = {}) {
+  const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+  if (!normalizedTransferChannelId) throw new Error('transferChannelId is required.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/participants`);
+}
+
+export async function openTransferChannel(client, {
+  workTransferPacketId,
+  work_transfer_packet_id,
+  packetId,
+  packet_id,
+  workflowRunId,
+  workflow_run_id,
+  channelKind = 'bidirectional',
+  channel_kind,
+  upstreamAgentSessionId,
+  upstream_agent_session_id,
+  upstreamActorSessionId,
+  upstream_actor_session_id,
+  downstreamAgentSessionId,
+  downstream_agent_session_id,
+  downstreamActorSessionId,
+  downstream_actor_session_id,
+  evidenceRequiredForClosure,
+  evidence_required_for_closure,
+  metadata = {},
+} = {}) {
+  const normalizedPacketId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId);
+  if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+  return client._request('/api/agent-communications/transfer-channels', {
+    method: 'POST',
+    body: {
+      work_transfer_packet_id: normalizedPacketId,
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      channel_kind: cleanText(channel_kind) || cleanText(channelKind) || 'bidirectional',
+      upstream_agent_session_id: cleanText(upstream_agent_session_id) || cleanText(upstreamAgentSessionId),
+      upstream_actor_session_id: cleanText(upstream_actor_session_id) || cleanText(upstreamActorSessionId),
+      downstream_agent_session_id: cleanText(downstream_agent_session_id) || cleanText(downstreamAgentSessionId),
+      downstream_actor_session_id: cleanText(downstream_actor_session_id) || cleanText(downstreamActorSessionId),
+      evidence_required_for_closure: evidence_required_for_closure ?? evidenceRequiredForClosure ?? true,
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function joinTransferChannel(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  const normalizedPacketId = await resolveTransferPacketId(client, normalizedTransferChannelId, request);
+  if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+  const {
+    workflowRunId,
+    workflow_run_id,
+    participantRole,
+    participant_role,
+    participantKind,
+    participant_kind,
+    participantLabel,
+    participant_label,
+    agentSessionId,
+    agent_session_id,
+    actorSessionId,
+    actor_session_id,
+    currentPhase,
+    current_phase,
+    currentTaskSummary,
+    current_task_summary,
+    lastSeenMessageId,
+    last_seen_message_id,
+    lastSeenAt,
+    last_seen_at,
+    lastSeenHeartbeatAt,
+    last_seen_heartbeat_at,
+    metadata = {},
+  } = request;
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/join`, {
+    method: 'POST',
+    body: {
+      work_transfer_packet_id: normalizedPacketId,
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      participant_role: cleanText(participant_role) || cleanText(participantRole),
+      participant_kind: cleanText(participant_kind) || cleanText(participantKind) || 'agent_session',
+      participant_label: cleanText(participant_label) || cleanText(participantLabel),
+      agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+      actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
+      current_phase: cleanText(current_phase) || cleanText(currentPhase),
+      current_task_summary: cleanText(current_task_summary) || cleanText(currentTaskSummary),
+      last_seen_message_id: cleanText(last_seen_message_id) || cleanText(lastSeenMessageId),
+      last_seen_at: last_seen_at || lastSeenAt,
+      last_seen_heartbeat_at: last_seen_heartbeat_at || lastSeenHeartbeatAt,
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function resumeTransferChannel(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  const normalizedPacketId = await resolveTransferPacketId(client, normalizedTransferChannelId, request);
+  if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+  const {
+    workflowRunId,
+    workflow_run_id,
+    participantRole,
+    participant_role,
+    participantKind,
+    participant_kind,
+    participantLabel,
+    participant_label,
+    agentSessionId,
+    agent_session_id,
+    actorSessionId,
+    actor_session_id,
+    currentPhase,
+    current_phase,
+    currentTaskSummary,
+    current_task_summary,
+    lastSeenMessageId,
+    last_seen_message_id,
+    lastSeenAt,
+    last_seen_at,
+    lastSeenHeartbeatAt,
+    last_seen_heartbeat_at,
+    metadata = {},
+  } = request;
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/resume`, {
+    method: 'POST',
+    body: {
+      work_transfer_packet_id: normalizedPacketId,
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      participant_role: cleanText(participant_role) || cleanText(participantRole),
+      participant_kind: cleanText(participant_kind) || cleanText(participantKind) || 'agent_session',
+      participant_label: cleanText(participant_label) || cleanText(participantLabel),
+      agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+      actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
+      current_phase: cleanText(current_phase) || cleanText(currentPhase),
+      current_task_summary: cleanText(current_task_summary) || cleanText(currentTaskSummary),
+      last_seen_message_id: cleanText(last_seen_message_id) || cleanText(lastSeenMessageId),
+      last_seen_at: last_seen_at || lastSeenAt,
+      last_seen_heartbeat_at: last_seen_heartbeat_at || lastSeenHeartbeatAt,
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function replyToTransferChannel(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  const {
+    senderAgentSessionId,
+    sender_agent_session_id,
+    senderActorSessionId,
+    sender_actor_session_id,
+    recipientAgentSessionId,
+    recipient_agent_session_id,
+    recipientActorSessionId,
+    recipient_actor_session_id,
+    messageKind,
+    message_kind,
+    bodyMarkdown,
+    body_markdown,
+    transferChannelMessageStatus,
+    transfer_channel_message_status,
+    messageStatus,
+    message_status,
+    payload = {},
+    scope = {},
+    requiredResponseSchema = {},
+    required_response_schema = {},
+    evidenceRefs = [],
+    evidence_refs = [],
+    metadata = {},
+    closureReason,
+    closure_reason,
+    failureReason,
+    failure_reason,
+    currentWaitingSide,
+    current_waiting_side,
+  } = request;
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/messages`, {
+    method: 'POST',
+    body: {
+      sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || client.agentSessionId,
+      sender_actor_session_id: cleanText(sender_actor_session_id) || cleanText(senderActorSessionId),
+      recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+      recipient_actor_session_id: cleanText(recipient_actor_session_id) || cleanText(recipientActorSessionId),
+      message_kind: cleanText(message_kind) || cleanText(messageKind) || 'clarification_request',
+      body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+      transfer_channel_message_status: cleanText(transfer_channel_message_status) || cleanText(transferChannelMessageStatus) || cleanText(message_status) || cleanText(messageStatus),
+      payload: isPlainObject(payload) ? payload : {},
+      scope: isPlainObject(scope) ? scope : {},
+      required_response_schema: isPlainObject(required_response_schema) ? required_response_schema : (isPlainObject(requiredResponseSchema) ? requiredResponseSchema : {}),
+      evidence_refs: Array.isArray(evidence_refs) ? evidence_refs : evidenceRefs,
+      metadata: isPlainObject(metadata) ? metadata : {},
+      closure_reason: cleanText(closure_reason) || cleanText(closureReason),
+      failure_reason: cleanText(failure_reason) || cleanText(failureReason),
+      current_waiting_side: cleanText(current_waiting_side) || cleanText(currentWaitingSide),
+    },
+  });
+}
+
+export async function requestTransferClosure(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  const {
+    senderAgentSessionId,
+    sender_agent_session_id,
+    senderActorSessionId,
+    sender_actor_session_id,
+    bodyMarkdown,
+    body_markdown,
+    closureReason,
+    closure_reason,
+    evidenceRefs = [],
+    evidence_refs = [],
+    metadata = {},
+  } = request;
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/closure-request`, {
+    method: 'POST',
+    body: {
+      sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || client.agentSessionId,
+      sender_actor_session_id: cleanText(sender_actor_session_id) || cleanText(senderActorSessionId),
+      body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+      closure_reason: cleanText(closure_reason) || cleanText(closureReason),
+      evidence_refs: Array.isArray(evidence_refs) ? evidence_refs : evidenceRefs,
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function closeTransferChannel(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  const {
+    closureStatus,
+    closure_status,
+    closureReason,
+    closure_reason,
+    failureReason,
+    failure_reason,
+    evidence = {},
+    evidenceManifestSha256,
+    evidence_manifest_sha256,
+    closedByAgentSessionId,
+    closed_by_agent_session_id,
+    closedByActorSessionId,
+    closed_by_actor_session_id,
+    closedByClaimId,
+    closed_by_claim_id,
+    metadata = {},
+  } = request;
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/close`, {
+    method: 'POST',
+    body: {
+      closure_status: cleanText(closure_status) || cleanText(closureStatus) || 'closed',
+      closure_reason: cleanText(closure_reason) || cleanText(closureReason),
+      failure_reason: cleanText(failure_reason) || cleanText(failureReason),
+      evidence: isPlainObject(evidence) ? evidence : {},
+      evidence_manifest_sha256: cleanText(evidence_manifest_sha256) || cleanText(evidenceManifestSha256),
+      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),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function openAgentChannel(client, request = {}) {
+  return connectToTransferChannel(client, request);
+}
+
+export async function connectToTransferChannel(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  let normalizedPacketId = cleanText(request.work_transfer_packet_id) || cleanText(request.workTransferPacketId) || cleanText(request.packet_id) || cleanText(request.packetId);
+  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 {
+    workflowRunId,
+    workflow_run_id,
+    participantRole,
+    participant_role,
+    expectedPeerRole,
+    expected_peer_role,
+    expectedMessageKind,
+    expected_message_kind,
+    proposalId,
+    proposal_id,
+    collaborationProposalId,
+    collaboration_proposal_id,
+    mode = 'communication_participant',
+    participantLabel,
+    participant_label,
+    participantRoleKey,
+    participant_role_key,
+    agentSessionId,
+    agent_session_id,
+    actorSessionId,
+    actor_session_id,
+    phase,
+    currentPhase,
+    current_phase,
+    currentTaskSummary,
+    current_task_summary,
+    expectedPayload = {},
+    expected_payload = {},
+    lastSeenMessageId,
+    last_seen_message_id,
+    lastCheckedAt,
+    last_checked_at,
+    staleAfterSeconds = 60,
+    stale_after_seconds,
+    operatorNudge,
+    operator_nudge,
+    observedAt,
+    observed_at,
+    metadata = {},
+  } = request;
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/connect`, {
+    method: 'POST',
+    body: {
+      work_transfer_packet_id: normalizedPacketId,
+      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),
+      expected_message_kind: cleanText(expected_message_kind) || cleanText(expectedMessageKind),
+      proposal_id: cleanText(proposal_id) || cleanText(proposalId) || cleanText(collaboration_proposal_id) || cleanText(collaborationProposalId),
+      mode: cleanText(mode) || 'communication_participant',
+      participant_label: cleanText(participant_label) || cleanText(participantLabel) || cleanText(participant_role_key) || cleanText(participantRoleKey),
+      agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+      actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
+      phase: cleanText(current_phase) || cleanText(currentPhase) || cleanText(phase),
+      current_task_summary: cleanText(current_task_summary) || cleanText(currentTaskSummary),
+      expected_payload: isPlainObject(expected_payload) ? expected_payload : isPlainObject(expectedPayload) ? expectedPayload : {},
+      last_seen_message_id: cleanText(last_seen_message_id) || cleanText(lastSeenMessageId),
+      last_checked_at: last_checked_at || lastCheckedAt,
+      stale_after_seconds: stale_after_seconds || staleAfterSeconds,
+      operator_nudge: cleanText(operator_nudge) || cleanText(operatorNudge),
+      observed_at: observed_at || observedAt,
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function startAgentConnection(client, request = {}) {
+  const normalizedFirstMessage = isPlainObject(request.firstMessage) ? request.firstMessage : isPlainObject(request.first_message) ? request.first_message : {};
+  const normalizedTransferKind = normalizeTransferKind(cleanText(request.mode) || 'handoff');
+  let normalizedWorkflowRunId = cleanText(request.workflow_run_id) || cleanText(request.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(request.upstream_agent) || cleanText(request.upstreamAgent) || cleanText(request.upstream_agent_session_id) || cleanText(request.upstreamAgentSessionId) || cleanText(request.upstream_agent_id) || cleanText(request.upstreamAgentId);
+  const normalizedRecipientMode = cleanText(request.recipient_mode) || cleanText(request.recipientMode) || (normalizedUpstreamAgent ? 'agent_session' : 'role');
+  const normalizedParticipantRole = cleanText(request.participant_role) || cleanText(request.participantRole) || 'downstream';
+  const normalizedParticipantLabel = cleanText(request.participant_label) || cleanText(request.participantLabel) || normalizedParticipantRole;
+  const normalizedSenderAgentSessionId = cleanText(request.sender_agent_session_id) || cleanText(request.senderAgentSessionId) || client.agentSessionId;
+  const normalizedSenderActorSessionId = cleanText(request.sender_actor_session_id) || cleanText(request.senderActorSessionId);
+  const normalizedFirstMessageKind = normalizeConnectionFirstMessageKind(
+    cleanText(normalizedFirstMessage.kind) || cleanText(normalizedFirstMessage.message_kind) || cleanText(normalizedFirstMessage.messageKind),
+    normalizedTransferKind,
+  );
+  const normalizedExpectedMessageKind = cleanText(request.expected_message_kind) || cleanText(request.expectedMessageKind) || 'connection_accepted';
+  const normalizedObjective = cleanText(request.objective) || cleanText(request.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(request.purpose) || normalizedObjective,
+    target: {
+      intent: normalizedTransferKind,
+      recipient_mode: normalizedRecipientMode,
+      preferred_agent_session_id: normalizedUpstreamAgent,
+      preferred_role_key: cleanText(request.upstream_role) || cleanText(request.upstreamRole),
+    },
+    artifacts: [],
+    issues: [],
+    expectedEvidence: [],
+    preferredModes: ['inline_payload', 'bundle', 'artifact_refs'],
+    capabilities: {},
+    senderAgentSessionId: normalizedSenderAgentSessionId,
+    senderActorSessionId: normalizedSenderActorSessionId,
+    subject: cleanText(request.purpose) || normalizedObjective,
+    bodyMarkdown:
+      cleanText(normalizedFirstMessage.body_markdown)
+      || cleanText(normalizedFirstMessage.bodyMarkdown)
+      || cleanText(normalizedFirstMessage.body)
+      || `Connection request: ${normalizedObjective}`,
+    cleanupPolicy: cleanText(request.cleanup_policy) || cleanText(request.cleanupPolicy),
+    messageKind: normalizedFirstMessageKind,
+    message_kind: normalizedFirstMessageKind,
+    metadata: isPlainObject(request.metadata) ? request.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(request.upstream_role) || cleanText(request.upstreamRole) || 'upstream',
+    expectedMessageKind: normalizedExpectedMessageKind,
+    proposalId: transferResult.transfer_negotiation?.proposal_id,
+    mode: 'communication_participant',
+    participantLabel: normalizedParticipantLabel,
+    senderAgentSessionId: normalizedSenderAgentSessionId,
+    senderActorSessionId: normalizedSenderActorSessionId,
+    currentPhase: 'channel_ready',
+    currentTaskSummary: cleanText(request.purpose) || normalizedObjective,
+    expectedPayload: {
+      purpose: cleanText(request.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: request.stale_after_seconds ?? request.staleAfterSeconds ?? 300,
+    operatorNudge:
+      cleanText(request.operator_nudge)
+      || cleanText(request.operatorNudge)
+      || `upstream, please send ${normalizedExpectedMessageKind}.`,
+    observedAt: transferResult.communication_message?.created_at || transferResult.transfer_receipt?.created_at,
+    metadata: {
+      ...(isPlainObject(request.metadata) ? request.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 postAgentHeartbeat(client, {
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  workTransferPacketId,
+  work_transfer_packet_id,
+  packetId,
+  packet_id,
+  workflowRunId,
+  workflow_run_id,
+  participantRole,
+  participant_role,
+  role,
+  activityState,
+  activity_state,
+  agentSessionId,
+  agent_session_id,
+  actorSessionId,
+  actor_session_id,
+  currentPhase,
+  current_phase,
+  phase,
+  currentTaskSummary,
+  current_task_summary,
+  isActive,
+  is_active,
+  observedAt,
+  observed_at,
+  metadata = {},
+} = {}) {
+  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) || cleanText(packet_id) || cleanText(packetId);
+  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.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/heartbeats`, {
+    method: 'POST',
+    body: {
+      work_transfer_packet_id: normalizedPacketId,
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      participant_role: cleanText(participant_role) || cleanText(participantRole) || cleanText(role),
+      activity_state: cleanText(activity_state) || cleanText(activityState) || 'active',
+      agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+      actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
+      current_phase: cleanText(current_phase) || cleanText(currentPhase) || cleanText(phase),
+      current_task_summary: cleanText(current_task_summary) || cleanText(currentTaskSummary),
+      is_active: is_active ?? isActive ?? true,
+      observed_at: observed_at || observedAt,
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function closeAgentChannel(client, {
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  closureStatus,
+  closure_status,
+  closureReason,
+  closure_reason,
+  failureReason,
+  failure_reason,
+  evidence = {},
+  evidenceManifestSha256,
+  evidence_manifest_sha256,
+  closedByAgentSessionId,
+  closed_by_agent_session_id,
+  closedByActorSessionId,
+  closed_by_actor_session_id,
+  closedByClaimId,
+  closed_by_claim_id,
+  metadata = {},
+} = {}) {
+  const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/close`, {
+    method: 'POST',
+    body: {
+      closure_status: cleanText(closure_status) || cleanText(closureStatus) || 'closed',
+      closure_reason: cleanText(closure_reason) || cleanText(closureReason),
+      failure_reason: cleanText(failure_reason) || cleanText(failureReason),
+      evidence: isPlainObject(evidence) ? evidence : {},
+      evidence_manifest_sha256: cleanText(evidence_manifest_sha256) || cleanText(evidenceManifestSha256),
+      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),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}