@bpmsoftwaresolutions/ai-engine-client 1.1.60 → 1.1.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.60",
+  "version": "1.1.62",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",
@@ -11,6 +11,7 @@
     ".": "./src/index.js"
   },
   "files": [
+    "package.json",
     "src",
     "README.md",
     "examples"

package/src/index.js

@@ -1,5 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 const DEFAULT_TIMEOUT_MS = 30000;
-export const AI_ENGINE_CLIENT_VERSION = '1.1.60';
+const PACKAGE_JSON_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+
+function readPackageVersion() {
+  const packageJson = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, 'utf8'));
+  const version = String(packageJson.version || '').trim();
+  if (!version) {
+    throw new Error(`Missing package version in ${PACKAGE_JSON_PATH}.`);
+  }
+  return version;
+}
+
+export const AI_ENGINE_CLIENT_VERSION = readPackageVersion();
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -437,6 +452,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),
@@ -484,6 +505,12 @@ export class AIEngineClient {
       raiseBlocker: (request) => this.raiseCollaborationBlocker(request),
       beginImplementation: (request) => this.beginCollaborationImplementation(request),
       requestClosure: (request) => this.requestCollaborationClosure(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),
       whoIsOnline: (request) => this.whoIsOnline(request),
       findOnlineParticipant: (request) => this.findOnlineParticipant(request),
       listCommunicationChannels: (request) => this.listCommunicationChannels(request),
@@ -1164,10 +1191,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,6 +1227,203 @@ export class AIEngineClient {
     });
   }
 
+  async openAgentChannel(request = {}) {
+    return this.connectToTransferChannel(request);
+  }
+
+  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),
+        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,