@bpmsoftwaresolutions/ai-engine-client 1.1.61 → 1.1.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.61",
+  "version": "1.1.63",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -106,6 +106,31 @@ function normalizeMessageKind(value) {
   });
 }
 
+function normalizeConnectionFirstMessageKind(value, transferKind) {
+  const text = cleanText(value);
+  if (!text) {
+    return normalizeMessageKind(transferKind === 'handoff' ? 'handoff' : 'request');
+  }
+  const normalized = text.toLowerCase();
+  const aliases = {
+    connection_request: 'request',
+    connection_accepted: 'response',
+    connection_acceptance: 'response',
+    handoff_request: 'handoff',
+    handoff_acceptance: 'response',
+    handoff_response: 'response',
+    acceptance: 'response',
+    decline: 'response',
+  };
+  const candidate = aliases[normalized] || text;
+  try {
+    return normalizeMessageKind(candidate);
+  } catch (error) {
+    void error;
+    return normalizeMessageKind(transferKind === 'handoff' ? 'handoff' : 'request');
+  }
+}
+
 function normalizeTransferKind(value) {
   return normalizeEnum(value, AGENT_COMMUNICATION_TRANSFER_KINDS, 'upstream_remediation', 'transfer_kind', {
     remediation_request: 'upstream_remediation',
@@ -379,7 +404,7 @@ function buildEligibilityError(message, details = {}) {
 }
 
 export class AIEngineClient {
-  constructor({ baseUrl, accessToken, tokenProvider, apiKey, clientId, actorId, fetchImpl, timeoutMs } = {}) {
+  constructor({ baseUrl, accessToken, tokenProvider, apiKey, clientId, actorId, agentSessionId, fetchImpl, timeoutMs } = {}) {
     if (!baseUrl) throw new Error('baseUrl is required.');
     this.baseUrl = trimTrailingSlash(baseUrl);
     this.accessToken = accessToken || null;
@@ -387,6 +412,7 @@ export class AIEngineClient {
     this.apiKey = apiKey || null;
     this.clientId = clientId || null;
     this.actorId = actorId || 'sdk:npm-ai-engine-client';
+    this.agentSessionId = cleanText(agentSessionId) || null;
     this.fetchImpl = fetchImpl || globalThis.fetch;
     this.timeoutMs = timeoutMs || DEFAULT_TIMEOUT_MS;
     this.clientVersion = AI_ENGINE_CLIENT_VERSION;
@@ -452,6 +478,12 @@ export class AIEngineClient {
       acceptTransferPacket: (request) => this.acceptCommunicationTransferPacket(request),
       closeTransferPacket: (request) => this.closeCommunicationTransferPacket(request),
       getTransferHealth: (request) => this.getCommunicationTransferHealth(request),
+      openAgentChannel: (request) => this.openAgentChannel(request),
+      acceptAgentChannel: (request) => this.acceptAgentChannel(request),
+      postAgentHeartbeat: (request) => this.postAgentHeartbeat(request),
+      postAgentMessage: (request) => this.postAgentMessage(request),
+      acknowledgeAgentMessage: (request) => this.acknowledgeAgentMessage(request),
+      closeAgentChannel: (request) => this.closeAgentChannel(request),
       createBundle: (request) => this.createCommunicationBundle(request),
       getBundle: (bundleId) => this.getCommunicationBundle(bundleId),
       listBundles: (request) => this.listCommunicationBundles(request),
@@ -489,6 +521,7 @@ export class AIEngineClient {
       stopCoordinationPingPong: (request) => this.stopCoordinationPingPong(request),
       checkCoordinationPingPongPreflight: (request) => this.checkCoordinationPingPongPreflight(request),
       connectToTransferChannel: (request) => this.connectToTransferChannel(request),
+      startAgentConnection: (request) => this.startAgentConnection(request),
       respondToMessageWatch: (request) => this.respondToMessageWatch(request),
     };
     this.collaboration = {
@@ -499,6 +532,13 @@ export class AIEngineClient {
       raiseBlocker: (request) => this.raiseCollaborationBlocker(request),
       beginImplementation: (request) => this.beginCollaborationImplementation(request),
       requestClosure: (request) => this.requestCollaborationClosure(request),
+      openAgentChannel: (request) => this.openAgentChannel(request),
+      startAgentConnection: (request) => this.startAgentConnection(request),
+      acceptAgentChannel: (request) => this.acceptAgentChannel(request),
+      postAgentHeartbeat: (request) => this.postAgentHeartbeat(request),
+      postAgentMessage: (request) => this.postAgentMessage(request),
+      acknowledgeAgentMessage: (request) => this.acknowledgeAgentMessage(request),
+      closeAgentChannel: (request) => this.closeAgentChannel(request),
       whoIsOnline: (request) => this.whoIsOnline(request),
       findOnlineParticipant: (request) => this.findOnlineParticipant(request),
       listCommunicationChannels: (request) => this.listCommunicationChannels(request),
@@ -533,6 +573,9 @@ export class AIEngineClient {
       apiKey: options.apiKey || process.env.AI_ENGINE_API_KEY || null,
       clientId: options.clientId || process.env.AI_ENGINE_CLIENT_ID || null,
       actorId: options.actorId || process.env.AI_ENGINE_ACTOR_ID || 'sdk:npm-ai-engine-client',
+      agentSessionId: options.agentSessionId || process.env.GOVERNANCE_SESSION_ID || process.env.AI_ENGINE_SESSION_ID || null,
+      fetchImpl: options.fetchImpl || null,
+      timeoutMs: options.timeoutMs,
     });
   }
 
@@ -1022,7 +1065,7 @@ export class AIEngineClient {
         participant_role: cleanText(participant_role) || cleanText(participantRole),
         current_phase: cleanText(current_phase) || cleanText(currentPhase),
         current_task_summary: cleanText(current_task_summary) || cleanText(currentTaskSummary),
-        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId),
+        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || this.agentSessionId,
         actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
         observed_at: cleanText(observed_at) || cleanText(observedAt),
         metadata: isPlainObject(metadata) ? metadata : {},
@@ -1068,7 +1111,7 @@ export class AIEngineClient {
         participant_role: cleanText(participant_role) || cleanText(participantRole),
         current_phase: cleanText(current_phase) || cleanText(currentPhase),
         current_task_summary: cleanText(current_task_summary) || cleanText(currentTaskSummary),
-        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId),
+        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || this.agentSessionId,
         actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
         observed_at: cleanText(observed_at) || cleanText(observedAt),
         metadata: isPlainObject(metadata) ? metadata : {},
@@ -1179,10 +1222,20 @@ export class AIEngineClient {
   } = {}) {
     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 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.');
     return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/connect`, {
       method: 'POST',
       body: {
-        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId) || resolved.packet_id,
+        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),
@@ -1190,7 +1243,7 @@ export class AIEngineClient {
         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),
+        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || this.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),
@@ -1205,6 +1258,366 @@ export class AIEngineClient {
     });
   }
 
+  async openAgentChannel(request = {}) {
+    return this.connectToTransferChannel(request);
+  }
+
+  async startAgentConnection({
+    workflowRunId,
+    workflow_run_id,
+    upstreamAgent,
+    upstream_agent,
+    upstreamAgentSessionId,
+    upstream_agent_session_id,
+    upstreamAgentId,
+    upstream_agent_id,
+    upstreamRole,
+    upstream_role,
+    recipientMode,
+    recipient_mode,
+    purpose,
+    objective,
+    mode = 'handoff',
+    firstMessage = {},
+    first_message = {},
+    expectedMessageKind,
+    expected_message_kind,
+    participantRole,
+    participant_role,
+    participantLabel,
+    participant_label,
+    senderAgentSessionId,
+    sender_agent_session_id,
+    senderActorSessionId,
+    sender_actor_session_id,
+    cleanupPolicy,
+    cleanup_policy,
+    staleAfterSeconds = 300,
+    stale_after_seconds,
+    operatorNudge,
+    operator_nudge,
+    metadata = {},
+  } = {}) {
+    const normalizedFirstMessage = isPlainObject(firstMessage) ? firstMessage : isPlainObject(first_message) ? first_message : {};
+    const normalizedTransferKind = normalizeTransferKind(cleanText(mode) || 'handoff');
+    let normalizedWorkflowRunId = cleanText(workflow_run_id) || cleanText(workflowRunId);
+    if (!normalizedWorkflowRunId) {
+      try {
+        const status = await 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,
+    };
+  }
+
+  async _resolveMessageWatchId(request = {}) {
+    const directWatchId = cleanText(request.message_watch_id) || cleanText(request.messageWatchId) || cleanText(request.watch_id) || cleanText(request.watchId);
+    if (directWatchId) {
+      return directWatchId;
+    }
+    const normalizedTransferChannelId = cleanText(request.transfer_channel_id) || cleanText(request.transferChannelId) || cleanText(request.channel_id) || cleanText(request.channelId);
+    if (!normalizedTransferChannelId) return null;
+    try {
+      const watches = await this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/message-watches`);
+      const watchRows = Array.isArray(watches?.message_watches) ? watches.message_watches.filter((row) => row && typeof row === 'object') : [];
+      watchRows.sort((a, b) => String(b.updated_at || b.created_at || '').localeCompare(String(a.updated_at || a.created_at || '')));
+      const activeWatch = watchRows.find((watch) => ['watching', 'waiting', 'stale', 'blocked', 'active'].includes(String(watch.current_status || '').trim().toLowerCase()));
+      return cleanText((activeWatch || watchRows[0] || {}).message_watch_id);
+    } catch (error) {
+      void error;
+      return null;
+    }
+  }
+
+  async acceptAgentChannel({
+    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 this._resolveMessageWatchId({ transfer_channel_id, transferChannelId, channel_id, channelId });
+    if (!normalizedWatchId) throw new Error('message_watch_id is required.');
+    return this._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 : {},
+      },
+    });
+  }
+
+  async postAgentHeartbeat({
+    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 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.');
+    return this._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) || this.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 : {},
+      },
+    });
+  }
+
+  async postAgentMessage(request = {}) {
+    return this._sendAgentCommsMessage(request);
+  }
+
+  async acknowledgeAgentMessage({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    messageWatchId,
+    message_watch_id,
+    watchId,
+    watch_id,
+    messageId,
+    message_id,
+    messageKind,
+    message_kind,
+    observedMessageId,
+    observed_message_id,
+    observedMessageKind,
+    observed_message_kind,
+    operatorNudge,
+    operator_nudge,
+    metadata = {},
+  } = {}) {
+    const normalizedWatchId = cleanText(message_watch_id) || cleanText(messageWatchId) || cleanText(watch_id) || cleanText(watchId) || await this._resolveMessageWatchId({ transfer_channel_id, transferChannelId, channel_id, channelId });
+    if (!normalizedWatchId) throw new Error('message_watch_id is required.');
+    return this._request(`/api/agent-communications/message-watches/${encodeURIComponent(normalizedWatchId)}/acknowledge-message`, {
+      method: 'POST',
+      body: {
+        observed_message_id: cleanText(observed_message_id) || cleanText(observedMessageId) || cleanText(message_id) || cleanText(messageId),
+        observed_message_kind: cleanText(observed_message_kind) || cleanText(observedMessageKind) || cleanText(message_kind) || cleanText(messageKind),
+        operator_nudge: cleanText(operator_nudge) || cleanText(operatorNudge),
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
+  async closeAgentChannel({
+    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 this._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 : {},
+      },
+    });
+  }
+
   async respondToMessageWatch({
     transferChannelId,
     transfer_channel_id,
@@ -1241,7 +1654,7 @@ export class AIEngineClient {
         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),
+        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || this.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),
@@ -1417,7 +1830,7 @@ export class AIEngineClient {
     return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/collaboration/request-closure`, {
       method: 'POST',
       body: {
-        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId),
+        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || this.agentSessionId,
         sender_actor_session_id: cleanText(sender_actor_session_id) || cleanText(senderActorSessionId),
         closure_reason: cleanText(closure_reason) || cleanText(closureReason),
         evidence_refs: Array.isArray(evidence_refs) ? evidence_refs : evidenceRefs,
@@ -1612,6 +2025,8 @@ export class AIEngineClient {
     sender_agent_session_id,
     senderActorSessionId,
     sender_actor_session_id,
+    messageKind,
+    message_kind,
     subject,
     bodyMarkdown,
     body_markdown,
@@ -1654,8 +2069,9 @@ export class AIEngineClient {
         estimated_payload_kb: Number(estimated_payload_kb ?? estimatedPayloadKb ?? 0) || undefined,
         requires_receipts: Boolean(requires_receipts ?? requiresReceipts),
         supports_hash_validation: Boolean(supports_hash_validation ?? supportsHashValidation),
-        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId),
+        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || this.agentSessionId,
         sender_actor_session_id: cleanText(sender_actor_session_id) || cleanText(senderActorSessionId),
+        message_kind: cleanText(message_kind) || cleanText(messageKind),
         subject: cleanText(subject),
         body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
         parent_thread_id: cleanText(parent_thread_id) || cleanText(parentThreadId),
@@ -1826,7 +2242,7 @@ export class AIEngineClient {
         transfer_channel_id: normalizedTransferChannelId,
         workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
         body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
-        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId),
+        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || this.agentSessionId,
         sender_role: cleanText(sender_role) || cleanText(senderRole),
         recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
         recipient_role: cleanText(recipient_role) || cleanText(recipientRole) || cleanText(role),
@@ -1878,7 +2294,7 @@ export class AIEngineClient {
         transfer_channel_id: normalizedTransferChannelId,
         workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
         body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
-        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId),
+        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || this.agentSessionId,
         sender_role: cleanText(sender_role) || cleanText(senderRole),
         recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
         recipient_role: cleanText(recipient_role) || cleanText(recipientRole) || cleanText(role) || cleanText(participant_role) || cleanText(participantRole),
@@ -2305,7 +2721,7 @@ export class AIEngineClient {
       body: {
         communication_thread_id: cleanText(communication_thread_id) || cleanText(communicationThreadId) || cleanText(threadId),
         communication_bundle_id: cleanText(communication_bundle_id) || cleanText(communicationBundleId),
-        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId),
+        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId) || this.agentSessionId,
         recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
         recipient_role_key: cleanText(recipient_role_key) || cleanText(recipientRoleKey),
         message_kind: normalizeMessageKind(cleanText(message_kind) || cleanText(messageKind)),
@@ -2595,7 +3011,7 @@ export class AIEngineClient {
         receipt_type: normalizeTransferReceiptType(cleanText(receipt_type) || cleanText(receiptType) || 'delivery_receipt'),
         receipt_status: cleanText(receipt_status) || cleanText(receiptStatus) || 'recorded',
         actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
-        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId),
+        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || this.agentSessionId,
         claim_id: cleanText(claim_id) || cleanText(claimId),
         evidence_ref: cleanText(evidence_ref) || cleanText(evidenceRef),
         evidence_sha256: cleanText(evidence_sha256) || cleanText(evidenceSha256),
@@ -2777,7 +3193,7 @@ export class AIEngineClient {
       body: {
         workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
         title: cleanText(title),
-        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId),
+        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || this.agentSessionId,
         handoff_kind: cleanText(handoff_kind) || cleanText(handoffKind) || 'general',
         handoff_priority: cleanText(handoff_priority) || cleanText(handoffPriority) || 'normal',
         summary_text: cleanText(summary_text) || cleanText(summaryText),
@@ -5386,6 +5802,7 @@ export class AIEngineClient {
     const resolvedHeaders = {
       accept: accept || 'application/json',
       'x-actor-id': this.actorId,
+      ...(this.agentSessionId ? { 'x-agent-session-id': this.agentSessionId } : {}),
       'x-ai-engine-client-version': this.clientVersion,
       'x-ai-engine-client-capabilities': this.clientCapabilities.join(','),
       ...(isJsonBody(body) ? { 'content-type': 'application/json' } : {}),