@bpmsoftwaresolutions/ai-engine-client 1.1.83 → 1.1.86

package/src/domains/collaboration.js

@@ -0,0 +1,273 @@
+import { cleanText, isPlainObject } 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 createCollaborationDomain(client) {
+  return {
+    reviewCollaborationProposal: (request) => reviewCollaborationProposal(client, request),
+    reviseCollaborationProposal: (request) => reviseCollaborationProposal(client, request),
+    postCollaborationProposal: (request) => postCollaborationProposal(client, request),
+    acceptCollaborationProposal: (request) => acceptCollaborationProposal(client, request),
+    assignCollaborationOwnership: (request) => assignCollaborationOwnership(client, request),
+    raiseCollaborationBlocker: (request) => raiseCollaborationBlocker(client, request),
+    resolveCollaborationBlocker: (request) => resolveCollaborationBlocker(client, request),
+    postCollaborationHeartbeat: (request) => postCollaborationHeartbeat(client, request),
+    beginCollaborationImplementation: (request) => beginCollaborationImplementation(client, request),
+    requestCollaborationClosure: (request) => requestCollaborationClosure(client, request),
+  };
+}
+
+export async function reviewCollaborationProposal(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  const normalizedProposalId = cleanText(request.collaboration_proposal_id) || cleanText(request.collaborationProposalId) || cleanText(request.proposal_id) || cleanText(request.proposalId);
+  if (!normalizedProposalId) throw new Error('collaboration_proposal_id is required.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/collaboration/review-proposal`, {
+    method: 'POST',
+    body: {
+      collaboration_proposal_id: normalizedProposalId,
+      decision: cleanText(request.decision) || 'accept',
+      next_owner: cleanText(request.next_owner) || cleanText(request.nextOwner),
+      phase: cleanText(request.phase) || cleanText(request.current_phase) || cleanText(request.currentPhase),
+      decision_reason: cleanText(request.decision_reason) || cleanText(request.decisionReason),
+      evidence_refs: Array.isArray(request.evidence_refs) ? request.evidence_refs : (Array.isArray(request.evidenceRefs) ? request.evidenceRefs : []),
+      reviewer_role: cleanText(request.reviewer_role) || cleanText(request.reviewerRole) || cleanText(request.participant_role) || cleanText(request.participantRole),
+      reviewer_agent_session_id: cleanText(request.reviewer_agent_session_id) || cleanText(request.reviewerAgentSessionId) || cleanText(request.sender_agent_session_id) || cleanText(request.senderAgentSessionId),
+      reviewer_actor_session_id: cleanText(request.reviewer_actor_session_id) || cleanText(request.reviewerActorSessionId) || cleanText(request.sender_actor_session_id) || cleanText(request.senderActorSessionId),
+      reviewed_by_claim_id: cleanText(request.reviewed_by_claim_id) || cleanText(request.reviewedByClaimId) || cleanText(request.claim_id) || cleanText(request.claimId),
+      metadata: isPlainObject(request.metadata) ? request.metadata : {},
+    },
+  });
+}
+
+export async function reviseCollaborationProposal(client, request = {}) {
+  const normalizedProposalId = cleanText(request.revision_of_proposal_id) || cleanText(request.revisionOfProposalId) || cleanText(request.proposal_id) || cleanText(request.proposalId);
+  if (!normalizedProposalId) throw new Error('revision_of_proposal_id is required.');
+  return client._request(`/api/agent-communications/collaboration-proposals/${encodeURIComponent(normalizedProposalId)}/revise`, {
+    method: 'POST',
+    body: {
+      transfer_channel_id: cleanText(request.transfer_channel_id) || cleanText(request.transferChannelId),
+      work_transfer_packet_id: cleanText(request.work_transfer_packet_id) || cleanText(request.workTransferPacketId),
+      workflow_run_id: cleanText(request.workflow_run_id) || cleanText(request.workflowRunId),
+      proposal_kind: cleanText(request.proposal_kind) || cleanText(request.proposalKind) || 'implementation_update',
+      participant_role: cleanText(request.participant_role) || cleanText(request.participantRole) || 'downstream',
+      proposal_summary: cleanText(request.proposal_summary) || cleanText(request.proposalSummary),
+      revision_of_proposal_id: normalizedProposalId,
+      proposer_agent_session_id: cleanText(request.proposer_agent_session_id) || cleanText(request.proposerAgentSessionId) || cleanText(request.revised_by_agent_session_id) || cleanText(request.revisedByAgentSessionId),
+      proposer_actor_session_id: cleanText(request.proposer_actor_session_id) || cleanText(request.proposerActorSessionId) || cleanText(request.revised_by_actor_session_id) || cleanText(request.revisedByActorSessionId),
+      current_phase: cleanText(request.current_phase) || cleanText(request.currentPhase),
+      expected_next_update: cleanText(request.expected_next_update) || cleanText(request.expectedNextUpdate),
+      expected_next_update_at: cleanText(request.expected_next_update_at) || cleanText(request.expectedNextUpdateAt),
+      required_evidence: Array.isArray(request.required_evidence) ? request.required_evidence : (Array.isArray(request.requiredEvidence) ? request.requiredEvidence : []),
+      response_schema: isPlainObject(request.response_schema) ? request.response_schema : (isPlainObject(request.responseSchema) ? request.responseSchema : {}),
+      blocker_summary: cleanText(request.blocker_summary) || cleanText(request.blockerSummary),
+      revision_number: Number(request.revision_number ?? request.revisionNumber ?? 2) || 2,
+      metadata: isPlainObject(request.metadata) ? request.metadata : {},
+    },
+  });
+}
+
+export async function postCollaborationProposal(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  const {
+    workTransferPacketId,
+    work_transfer_packet_id,
+    workflowRunId,
+    workflow_run_id,
+    proposalKind,
+    proposal_kind,
+    proposalState,
+    proposal_state,
+    participantRole,
+    participant_role,
+    proposalSummary,
+    proposal_summary,
+    currentPhase,
+    current_phase,
+    expectedNextUpdate,
+    expected_next_update,
+    expectedNextUpdateAt,
+    expected_next_update_at,
+    requiredEvidence = [],
+    required_evidence = [],
+    responseSchema = {},
+    response_schema = {},
+    blockerSummary,
+    blocker_summary,
+    blockerReason,
+    blocker_reason,
+    revisionOfProposalId,
+    revision_of_proposal_id,
+    revisionNumber = 1,
+    revision_number,
+    proposerAgentSessionId,
+    proposer_agent_session_id,
+    proposerActorSessionId,
+    proposer_actor_session_id,
+    metadata = {},
+  } = request;
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/proposals`, {
+    method: 'POST',
+    body: {
+      work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId),
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      proposal_kind: cleanText(proposal_kind) || cleanText(proposalKind),
+      proposal_state: cleanText(proposal_state) || cleanText(proposalState) || 'proposed',
+      participant_role: cleanText(participant_role) || cleanText(participantRole),
+      proposal_summary: cleanText(proposal_summary) || cleanText(proposalSummary),
+      current_phase: cleanText(current_phase) || cleanText(currentPhase),
+      expected_next_update: cleanText(expected_next_update) || cleanText(expectedNextUpdate),
+      expected_next_update_at: expected_next_update_at || expectedNextUpdateAt,
+      required_evidence: Array.isArray(required_evidence) ? required_evidence : requiredEvidence,
+      response_schema: isPlainObject(response_schema) ? response_schema : responseSchema,
+      blocker_summary: cleanText(blocker_summary) || cleanText(blockerSummary) || cleanText(blocker_reason) || cleanText(blockerReason),
+      revision_of_proposal_id: cleanText(revision_of_proposal_id) || cleanText(revisionOfProposalId),
+      revision_number: Number(revision_number ?? revisionNumber ?? 1),
+      proposer_agent_session_id: cleanText(proposer_agent_session_id) || cleanText(proposerAgentSessionId) || client.agentSessionId,
+      proposer_actor_session_id: cleanText(proposer_actor_session_id) || cleanText(proposerActorSessionId),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function acceptCollaborationProposal(client, request = {}) {
+  const normalizedProposalId = cleanText(request.proposal_id) || cleanText(request.proposalId);
+  if (!normalizedProposalId) throw new Error('collaboration_proposal_id is required.');
+  return client._request(`/api/agent-communications/collaboration-proposals/${encodeURIComponent(normalizedProposalId)}/accept`, {
+    method: 'POST',
+    body: {
+      transfer_channel_id: cleanText(request.transfer_channel_id) || cleanText(request.transferChannelId),
+      work_transfer_packet_id: cleanText(request.work_transfer_packet_id) || cleanText(request.workTransferPacketId),
+      workflow_run_id: cleanText(request.workflow_run_id) || cleanText(request.workflowRunId),
+      collaboration_proposal_id: normalizedProposalId,
+      decision_role: cleanText(request.decision_role) || cleanText(request.decisionRole) || 'upstream',
+      decision_summary: cleanText(request.decision_summary) || cleanText(request.decisionSummary) || 'Proposal accepted.',
+      decision_reason: cleanText(request.decision_reason) || cleanText(request.decisionReason),
+      decision_agent_session_id: cleanText(request.decision_agent_session_id) || cleanText(request.decisionAgentSessionId) || client.agentSessionId,
+      decision_actor_session_id: cleanText(request.decision_actor_session_id) || cleanText(request.decisionActorSessionId),
+      evidence_refs: Array.isArray(request.evidence_refs) ? request.evidence_refs : (Array.isArray(request.evidenceRefs) ? request.evidenceRefs : []),
+      metadata: isPlainObject(request.metadata) ? request.metadata : {},
+    },
+  });
+}
+
+export async function assignCollaborationOwnership(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/ownership-assignments`, {
+    method: 'POST',
+    body: {
+      work_transfer_packet_id: cleanText(request.work_transfer_packet_id) || cleanText(request.workTransferPacketId),
+      workflow_run_id: cleanText(request.workflow_run_id) || cleanText(request.workflowRunId),
+      participant_role: cleanText(request.participant_role) || cleanText(request.participantRole),
+      owner_agent_session_id: cleanText(request.owner_agent_session_id) || cleanText(request.ownerAgentSessionId),
+      owner_actor_session_id: cleanText(request.owner_actor_session_id) || cleanText(request.ownerActorSessionId),
+      owner_label: cleanText(request.owner_label) || cleanText(request.ownerLabel),
+      assignment_state: cleanText(request.assignment_state) || cleanText(request.assignmentState) || 'assigned',
+      assignment_reason: cleanText(request.assignment_reason) || cleanText(request.assignmentReason),
+      current_phase: cleanText(request.current_phase) || cleanText(request.currentPhase),
+      assigned_by_agent_session_id: cleanText(request.assigned_by_agent_session_id) || cleanText(request.assignedByAgentSessionId) || client.agentSessionId,
+      assigned_by_actor_session_id: cleanText(request.assigned_by_actor_session_id) || cleanText(request.assignedByActorSessionId),
+      resolved_at: request.resolved_at || request.resolvedAt,
+      metadata: isPlainObject(request.metadata) ? request.metadata : {},
+    },
+  });
+}
+
+export async function raiseCollaborationBlocker(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/collaboration/raise-blocker`, {
+    method: 'POST',
+    body: {
+      blocker_kind: cleanText(request.blocker_kind) || cleanText(request.blockerKind),
+      blocker_summary: cleanText(request.blocker_summary) || cleanText(request.blockerSummary),
+      blocked_side: cleanText(request.blocked_side) || cleanText(request.blockedSide),
+      blocker_details: cleanText(request.blocker_details) || cleanText(request.blockerDetails),
+      expected_next_update: cleanText(request.expected_next_update) || cleanText(request.expectedNextUpdate),
+      participant_role: cleanText(request.participant_role) || cleanText(request.participantRole),
+      next_owner: cleanText(request.next_owner) || cleanText(request.nextOwner),
+      phase: cleanText(request.current_phase) || cleanText(request.currentPhase) || cleanText(request.phase),
+      reviewer_agent_session_id: cleanText(request.reviewer_agent_session_id) || cleanText(request.reviewerAgentSessionId),
+      reviewer_actor_session_id: cleanText(request.reviewer_actor_session_id) || cleanText(request.reviewerActorSessionId),
+      metadata: isPlainObject(request.metadata) ? request.metadata : {},
+    },
+  });
+}
+
+export async function resolveCollaborationBlocker(client, request = {}) {
+  const normalizedBlockerId = cleanText(request.blocker_id) || cleanText(request.blockerId);
+  if (!normalizedBlockerId) throw new Error('blocker_id is required.');
+  return client._request(`/api/agent-communications/collaboration-blockers/${encodeURIComponent(normalizedBlockerId)}/resolve`, {
+    method: 'POST',
+    body: {
+      blocker_state: cleanText(request.blocker_state) || cleanText(request.blockerState) || 'resolved',
+      resolution_summary: cleanText(request.resolution_summary) || cleanText(request.resolutionSummary),
+      resolved_by_agent_session_id: cleanText(request.resolved_by_agent_session_id) || cleanText(request.resolvedByAgentSessionId),
+      resolved_by_actor_session_id: cleanText(request.resolved_by_actor_session_id) || cleanText(request.resolvedByActorSessionId),
+      resolved_at: request.resolved_at || request.resolvedAt,
+      metadata: isPlainObject(request.metadata) ? request.metadata : {},
+    },
+  });
+}
+
+export async function postCollaborationHeartbeat(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/heartbeats`, {
+    method: 'POST',
+    body: {
+      work_transfer_packet_id: cleanText(request.work_transfer_packet_id) || cleanText(request.workTransferPacketId),
+      workflow_run_id: cleanText(request.workflow_run_id) || cleanText(request.workflowRunId),
+      participant_role: cleanText(request.participant_role) || cleanText(request.participantRole),
+      activity_state: cleanText(request.activity_state) || cleanText(request.activityState) || 'active',
+      current_phase: cleanText(request.current_phase) || cleanText(request.currentPhase),
+      current_task_summary: cleanText(request.current_task_summary) || cleanText(request.currentTaskSummary),
+      is_active: Boolean(request.is_active ?? request.isActive ?? true),
+      agent_session_id: cleanText(request.agent_session_id) || cleanText(request.agentSessionId) || client.agentSessionId,
+      actor_session_id: cleanText(request.actor_session_id) || cleanText(request.actorSessionId),
+      observed_at: request.observed_at || request.observedAt,
+      metadata: isPlainObject(request.metadata) ? request.metadata : {},
+    },
+  });
+}
+
+export async function beginCollaborationImplementation(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/collaboration/begin-implementation`, {
+    method: 'POST',
+    body: {
+      participant_role: cleanText(request.participant_role) || cleanText(request.participantRole) || cleanText(request.owner_role_key) || cleanText(request.ownerRoleKey),
+      owner_label: cleanText(request.owner_label) || cleanText(request.ownerLabel) || cleanText(request.owner_role_key) || cleanText(request.ownerRoleKey),
+      expected_update_cadence: cleanText(request.expected_update_cadence) || cleanText(request.expectedUpdateCadence),
+      phase: cleanText(request.current_phase) || cleanText(request.currentPhase) || cleanText(request.phase),
+      current_task_summary: cleanText(request.current_task_summary) || cleanText(request.currentTaskSummary),
+      owner_agent_session_id: cleanText(request.owner_agent_session_id) || cleanText(request.ownerAgentSessionId),
+      owner_actor_session_id: cleanText(request.owner_actor_session_id) || cleanText(request.ownerActorSessionId),
+      assigned_by_agent_session_id: cleanText(request.assigned_by_agent_session_id) || cleanText(request.assignedByAgentSessionId),
+      assigned_by_actor_session_id: cleanText(request.assigned_by_actor_session_id) || cleanText(request.assignedByActorSessionId),
+      metadata: isPlainObject(request.metadata) ? request.metadata : {},
+    },
+  });
+}
+
+export async function requestCollaborationClosure(client, request = {}) {
+  const normalizedTransferChannelId = normalizeTransferChannelId(request);
+  if (!normalizedTransferChannelId) throw new Error('transfer_channel_id is required.');
+  return client._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/collaboration/request-closure`, {
+    method: 'POST',
+    body: {
+      sender_agent_session_id: cleanText(request.sender_agent_session_id) || cleanText(request.senderAgentSessionId) || client.agentSessionId,
+      sender_actor_session_id: cleanText(request.sender_actor_session_id) || cleanText(request.senderActorSessionId),
+      closure_reason: cleanText(request.closure_reason) || cleanText(request.closureReason),
+      evidence_refs: Array.isArray(request.evidence_refs) ? request.evidence_refs : (Array.isArray(request.evidenceRefs) ? request.evidenceRefs : []),
+      failure_reason: cleanText(request.failure_reason) || cleanText(request.failureReason),
+      phase: cleanText(request.current_phase) || cleanText(request.currentPhase) || cleanText(request.phase),
+      metadata: isPlainObject(request.metadata) ? request.metadata : {},
+    },
+  });
+}

package/src/domains/message-watch.js

@@ -0,0 +1,270 @@
+import { cleanText, isPlainObject } from '../utils/communication.js';
+
+export function createMessageWatchDomain(client) {
+  return {
+    startMessageWatch: (request) => startMessageWatch(client, request),
+    acknowledgeExpectedMessage: (request) => acknowledgeExpectedMessage(client, request),
+    expireMessageWatch: (request) => expireMessageWatch(client, request),
+    respondToMessageWatch: (request) => respondToMessageWatch(client, request),
+    acceptAgentChannel: (request) => acceptAgentChannel(client, request),
+    resolveMessageWatchId: (request) => resolveMessageWatchId(client, request),
+  };
+}
+
+export async function resolveMessageWatchId(client, {
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  workTransferPacketId,
+  work_transfer_packet_id,
+  messageWatchId,
+  message_watch_id,
+  watchId,
+  watch_id,
+} = {}) {
+  let normalizedWatchId = cleanText(message_watch_id) || cleanText(messageWatchId) || cleanText(watch_id) || cleanText(watchId);
+  if (!normalizedWatchId) {
+    normalizedWatchId = await client._resolveMessageWatchId({
+      transfer_channel_id,
+      transferChannelId,
+      channel_id,
+      channelId,
+      work_transfer_packet_id,
+      workTransferPacketId,
+    });
+  }
+  return normalizedWatchId;
+}
+
+export async function startMessageWatch(client, {
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  workTransferPacketId,
+  work_transfer_packet_id,
+  workflowRunId,
+  workflow_run_id,
+  watchingAgentRole,
+  watching_agent_role,
+  expectedFromRole,
+  expected_from_role,
+  expectedMessageKind,
+  expected_message_kind,
+  watchType,
+  watch_type,
+  watchingAgentSessionId,
+  watching_agent_session_id,
+  watchingActorSessionId,
+  watching_actor_session_id,
+  expectedPayload,
+  expected_payload,
+  lastSeenMessageId,
+  last_seen_message_id,
+  lastCheckedAt,
+  last_checked_at,
+  staleAfterSeconds,
+  stale_after_seconds,
+  currentStatus,
+  current_status,
+  operatorNudge,
+  operator_nudge,
+  blockedReason,
+  blocked_reason,
+  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);
+  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)}/message-watches`, {
+    method: 'POST',
+    body: {
+      work_transfer_packet_id: normalizedPacketId,
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      watching_agent_role: cleanText(watching_agent_role) || cleanText(watchingAgentRole),
+      expected_from_role: cleanText(expected_from_role) || cleanText(expectedFromRole),
+      expected_message_kind: cleanText(expected_message_kind) || cleanText(expectedMessageKind),
+      watch_type: cleanText(watch_type) || cleanText(watchType) || 'expected_peer_message',
+      watching_agent_session_id: cleanText(watching_agent_session_id) || cleanText(watchingAgentSessionId) || client.agentSessionId,
+      watching_actor_session_id: cleanText(watching_actor_session_id) || cleanText(watchingActorSessionId),
+      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,
+      current_status: cleanText(current_status) || cleanText(currentStatus),
+      operator_nudge: cleanText(operator_nudge) || cleanText(operatorNudge),
+      blocked_reason: cleanText(blocked_reason) || cleanText(blockedReason),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function acknowledgeExpectedMessage(client, {
+  messageWatchId,
+  message_watch_id,
+  watchId,
+  watch_id,
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  observedMessageId,
+  observed_message_id,
+  observedMessageKind,
+  observed_message_kind,
+  lastCheckedAt,
+  last_checked_at,
+  operatorNudge,
+  operator_nudge,
+  metadata = {},
+} = {}) {
+  const normalizedWatchId = await resolveMessageWatchId(client, {
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    messageWatchId,
+    message_watch_id,
+    watchId,
+    watch_id,
+  });
+  if (!normalizedWatchId) throw new Error('message_watch_id is required.');
+  return client._request(`/api/agent-communications/message-watches/${encodeURIComponent(normalizedWatchId)}/acknowledge-message`, {
+    method: 'POST',
+    body: {
+      observed_message_id: cleanText(observed_message_id) || cleanText(observedMessageId),
+      observed_message_kind: cleanText(observed_message_kind) || cleanText(observedMessageKind),
+      last_checked_at: last_checked_at || lastCheckedAt,
+      operator_nudge: cleanText(operator_nudge) || cleanText(operatorNudge),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function expireMessageWatch(client, {
+  messageWatchId,
+  message_watch_id,
+  watchId,
+  watch_id,
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  blockedReason,
+  blocked_reason,
+  lastCheckedAt,
+  last_checked_at,
+  metadata = {},
+} = {}) {
+  const normalizedWatchId = await resolveMessageWatchId(client, {
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    messageWatchId,
+    message_watch_id,
+    watchId,
+    watch_id,
+  });
+  if (!normalizedWatchId) throw new Error('message_watch_id is required.');
+  return client._request(`/api/agent-communications/message-watches/${encodeURIComponent(normalizedWatchId)}/expire`, {
+    method: 'POST',
+    body: {
+      blocked_reason: cleanText(blocked_reason) || cleanText(blockedReason),
+      last_checked_at: last_checked_at || lastCheckedAt,
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function respondToMessageWatch(client, {
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  messageWatchId,
+  message_watch_id,
+  watchId,
+  watch_id,
+  expectedMessageKind,
+  expected_message_kind,
+  senderRole,
+  sender_role,
+  participantRole,
+  participant_role,
+  senderAgentSessionId,
+  sender_agent_session_id,
+  senderActorSessionId,
+  sender_actor_session_id,
+  messageKind,
+  message_kind,
+  bodyMarkdown,
+  body_markdown,
+  evidenceRefs,
+  evidence_refs,
+  payload = {},
+  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)}/message-watches/respond`, {
+    method: 'POST',
+    body: {
+      message_watch_id: cleanText(message_watch_id) || cleanText(messageWatchId) || cleanText(watch_id) || cleanText(watchId),
+      expected_message_kind: cleanText(expected_message_kind) || cleanText(expectedMessageKind),
+      sender_role: cleanText(sender_role) || cleanText(senderRole) || cleanText(participant_role) || cleanText(participantRole),
+      sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || client.agentSessionId,
+      sender_actor_session_id: cleanText(sender_actor_session_id) || cleanText(senderActorSessionId),
+      message_kind: cleanText(message_kind) || cleanText(messageKind),
+      body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+      evidence_refs: Array.isArray(evidence_refs) ? evidence_refs : Array.isArray(evidenceRefs) ? evidenceRefs : [],
+      payload: isPlainObject(payload) ? payload : {},
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function acceptAgentChannel(client, {
+  messageWatchId,
+  message_watch_id,
+  watchId,
+  watch_id,
+  observedMessageId,
+  observed_message_id,
+  observedMessageKind,
+  observed_message_kind,
+  expectedMessageKind,
+  expected_message_kind,
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  lastCheckedAt,
+  last_checked_at,
+  operatorNudge,
+  operator_nudge,
+  metadata = {},
+} = {}) {
+  const normalizedWatchId = cleanText(message_watch_id) || cleanText(messageWatchId) || cleanText(watch_id) || cleanText(watchId) || await resolveMessageWatchId(client, { transfer_channel_id, transferChannelId, channel_id, channelId });
+  if (!normalizedWatchId) throw new Error('message_watch_id is required.');
+  return client._request(`/api/agent-communications/message-watches/${encodeURIComponent(normalizedWatchId)}/acknowledge`, {
+    method: 'POST',
+    body: {
+      observed_message_id: cleanText(observed_message_id) || cleanText(observedMessageId),
+      observed_message_kind: cleanText(observed_message_kind) || cleanText(observedMessageKind) || cleanText(expected_message_kind) || cleanText(expectedMessageKind),
+      last_checked_at: last_checked_at || lastCheckedAt,
+      operator_nudge: cleanText(operator_nudge) || cleanText(operatorNudge),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}