@bpmsoftwaresolutions/ai-engine-client 1.1.95 → 1.1.98

package/src/client.js

@@ -56,6 +56,7 @@ import { createWorkflowTurnsDomain } from './domains/workflow-turns.js';
 import { createChartersDomain } from './domains/charters.js';
 import { createWorkStartDomain } from './domains/work-start.js';
 import { createCollaborationDomain } from './domains/collaboration.js';
+import { createAgentCommunicationsDomain } from './domains/agent-communications.js';
 import { createMessageWatchDomain } from './domains/message-watch.js';
 import { createPingPongDomain } from './domains/ping-pong.js';
 import { createPresenceDomain } from './domains/presence.js';
@@ -324,6 +325,7 @@ export class AIEngineClient {
     this.messageWatch = createMessageWatchDomain(this);
     this.presence = createPresenceDomain(this);
     this.pingPong = createPingPongDomain(this);
+    this.agentCommunications = createAgentCommunicationsDomain(this);
     this.collaborationDomain = createCollaborationDomain(this);
     this.agentComms = createAgentCommunicationsFacade(this);
     this.collaboration = createCollaborationFacade(this);
@@ -381,131 +383,7 @@ export class AIEngineClient {
     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 this.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) || this.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 this.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 this.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,
-    };
+    return this.agentCommunications.startAgentConnection(arguments[0]);
   }
 
   async establishAgentCommunicationChannel({
@@ -563,300 +441,7 @@ export class AIEngineClient {
     includeOperatorProjectionMetadata = true,
     metadata = {},
   } = {}) {
-    const missingSurfaces = [];
-    const explicitProjectReference = cleanText(projectIdentifier) || cleanText(projectId);
-    const actorIdentity = cleanText(actorId) || this.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 this.resumeProjectWork !== 'function') {
-        missingSurfaces.push('resumeProjectWork');
-      } else {
-        continuation = await this.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 this.startWork !== 'function') {
-        missingSurfaces.push('startWork');
-      } else {
-        startWorkResult = await this.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 this.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) || this.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 this.openTransferChannel === 'function'
-      ? this.openTransferChannel.bind(this)
-      : typeof this.openAgentChannel === 'function'
-        ? this.openAgentChannel.bind(this)
-        : typeof this.connectToTransferChannel === 'function'
-          ? this.connectToTransferChannel.bind(this)
-          : 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) || this.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 this[joinSurfaceName] === 'function'
-      ? this[joinSurfaceName].bind(this)
-      : typeof this.joinTransferChannel === 'function'
-        ? this.joinTransferChannel.bind(this)
-        : typeof this.resumeTransferChannel === 'function'
-          ? this.resumeTransferChannel.bind(this)
-          : 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) || this.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 this.postCollaborationHeartbeat === 'function'
-      ? this.postCollaborationHeartbeat.bind(this)
-      : typeof this.postAgentHeartbeat === 'function'
-        ? this.postAgentHeartbeat.bind(this)
-        : 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) || this.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 this.getCommunicationChannelStatus({ transferChannelId: openedChannelId }).catch(() => null);
-    const participants = await this.getCommunicationChannelParticipants({ transferChannelId: openedChannelId }).catch(() => null);
-    const transferChannelProjectionSurface = typeof this.getTransferChannelProjection === 'function'
-      ? this.getTransferChannelProjection.bind(this)
-      : typeof this.getLogaTransferChannelThreadProjection === 'function'
-        ? this.getLogaTransferChannelThreadProjection.bind(this)
-        : null;
-    if (!transferChannelProjectionSurface) missingSurfaces.push('getTransferChannelProjection');
-    const transferChannelProjection = includeTransferChannelProjection && transferChannelProjectionSurface
-      ? await transferChannelProjectionSurface(openedChannelId).catch(() => null)
-      : null;
-    const channelPresence = includeChannelPresenceProjection
-      ? await this.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,
-    };
+    return this.agentCommunications.establishAgentCommunicationChannel(arguments[0]);
   }
 
   async runInterAgentMessagingLoop({
@@ -920,301 +505,7 @@ export class AIEngineClient {
     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 this.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 this.resumeTransferChannel === 'function'
-      ? this.resumeTransferChannel.bind(this)
-      : 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: this.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 this.replyToTransferChannel === 'function'
-      ? this.replyToTransferChannel.bind(this)
-      : 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) || this.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 this.startMessageWatch === 'function'
-      ? this.startMessageWatch.bind(this)
-      : 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) || this.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 this.acknowledgeExpectedMessage === 'function'
-      ? this.acknowledgeExpectedMessage.bind(this)
-      : 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 this.postCollaborationHeartbeat === 'function'
-      ? this.postCollaborationHeartbeat.bind(this)
-      : typeof this.postAgentHeartbeat === 'function'
-        ? this.postAgentHeartbeat.bind(this)
-        : 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: this.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 this.getTransferChannelProjection === 'function'
-      ? this.getTransferChannelProjection.bind(this)
-      : typeof this.getLogaTransferChannelThreadProjection === 'function'
-        ? this.getLogaTransferChannelThreadProjection.bind(this)
-        : null;
-    if (!transferChannelProjectionSurface) missingSurfaces.push('getTransferChannelProjection');
-    const transferChannelProjection = includeTransferChannelProjection && transferChannelProjectionSurface
-      ? await transferChannelProjectionSurface(normalizedTransferChannelId).catch(() => null)
-      : null;
-
-    const closureRequested = Boolean(shouldClose && acknowledged);
-    const closeSurface = typeof this.closeTransferChannel === 'function'
-      ? this.closeTransferChannel.bind(this)
-      : 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: this.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,
-    };
+    return this.agentCommunications.runInterAgentMessagingLoop(arguments[0]);
   }
 
   async createCrossAgentRemediationTicket({
@@ -2700,67 +1991,27 @@ export class AIEngineClient {
   }
 
   async describeDatabaseCatalog({ includeSystemSchemas, limit } = {}) {
-    return this._request('/api/operator/database/schema', {
-      query: {
-        view: 'overview',
-        include_system_schemas: includeSystemSchemas,
-        limit,
-      },
-    });
+    return this.database.schema.getOverview({ includeSystemSchemas, limit });
   }
 
   async listDatabaseSchemas({ includeSystemSchemas, limit } = {}) {
-    return this._request('/api/operator/database/schema', {
-      query: {
-        view: 'schemas',
-        include_system_schemas: includeSystemSchemas,
-        limit,
-      },
-    });
+    return this.database.schema.listSchemas({ includeSystemSchemas, limit });
   }
 
   async listDatabaseTables({ schemaName, includeSystemSchemas, limit } = {}) {
-    return this._request('/api/operator/database/schema', {
-      query: {
-        view: 'tables',
-        schema_name: schemaName,
-        include_system_schemas: includeSystemSchemas,
-        limit,
-      },
-    });
+    return this.database.schema.listTables({ schemaName, includeSystemSchemas, limit });
   }
 
   async listDatabaseColumns({ schemaName, tableName } = {}) {
-    return this._request('/api/operator/database/schema', {
-      query: {
-        view: 'columns',
-        schema_name: schemaName,
-        table_name: tableName,
-      },
-    });
+    return this.database.schema.listColumns({ schemaName, tableName });
   }
 
   async listDatabaseIndexes({ schemaName, tableName, includeSystemSchemas, limit } = {}) {
-    return this._request('/api/operator/database/schema', {
-      query: {
-        view: 'indexes',
-        schema_name: schemaName,
-        table_name: tableName,
-        include_system_schemas: includeSystemSchemas,
-        limit,
-      },
-    });
+    return this.database.schema.listIndexes({ schemaName, tableName, includeSystemSchemas, limit });
   }
 
   async describeDatabaseTable({ schemaName, tableName, includeSystemSchemas } = {}) {
-    return this._request('/api/operator/database/schema', {
-      query: {
-        view: 'table',
-        schema_name: schemaName,
-        table_name: tableName,
-        include_system_schemas: includeSystemSchemas,
-      },
-    });
+    return this.database.schema.describeTable({ schemaName, tableName, includeSystemSchemas });
   }
 
   async createDatabaseBackup({ databaseName, outputName, noWait } = {}) {