@bpmsoftwaresolutions/ai-engine-client 1.1.41 → 1.1.43

package/package.json

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

package/src/index.js

@@ -1,5 +1,5 @@
 const DEFAULT_TIMEOUT_MS = 30000;
-export const AI_ENGINE_CLIENT_VERSION = '1.1.41';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.43';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -305,6 +305,17 @@ export class AIEngineClient {
     this.actions = {
       submit: (request) => this.submitActionIntent(request),
     };
+    this.agentComms = {
+      openThread: (request) => this.openCommunicationThread(request),
+      getThread: (threadId) => this.getCommunicationThread(threadId),
+      listInbox: (request) => this.listCommunicationInbox(request),
+      sendMessage: (request) => this.sendCommunicationMessage(request),
+      acceptMessage: (messageId) => this.acceptCommunicationMessage(messageId),
+      respondWithEvidence: (request) => this.respondToCommunicationMessage(request),
+      attachEvidence: (request) => this.attachCommunicationMessageEvidence(request),
+      createHandoff: (request) => this.createCommunicationHandoff(request),
+      acceptHandoff: (request) => this.acceptCommunicationHandoff(request),
+    };
   }
 
   static fromEnv(options = {}) {
@@ -482,6 +493,205 @@ export class AIEngineClient {
     });
   }
 
+  async openCommunicationThread({
+    workflowRunId,
+    workflow_run_id,
+    threadType,
+    thread_type,
+    subject,
+    objective,
+    parentThreadId,
+    parent_thread_id,
+    createdByAgentSessionId,
+    created_by_agent_session_id,
+    createdByActorSessionId,
+    created_by_actor_session_id,
+    metadata,
+  } = {}) {
+    return this._request('/api/agent-communications/threads', {
+      method: 'POST',
+      body: {
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        parent_thread_id: cleanText(parent_thread_id) || cleanText(parentThreadId),
+        thread_type: cleanText(thread_type) || cleanText(threadType),
+        subject: cleanText(subject),
+        objective: cleanText(objective),
+        created_by_agent_session_id: cleanText(created_by_agent_session_id) || cleanText(createdByAgentSessionId),
+        created_by_actor_session_id: cleanText(created_by_actor_session_id) || cleanText(createdByActorSessionId),
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
+  async getCommunicationThread(threadId) {
+    return this._request(`/api/agent-communications/threads/${encodeURIComponent(threadId)}`);
+  }
+
+  async listCommunicationInbox({
+    recipientAgentSessionId,
+    recipient_agent_session_id,
+    recipientRoleKey,
+    recipient_role_key,
+  } = {}) {
+    return this._request('/api/agent-communications/inbox', {
+      query: {
+        recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+        recipient_role_key: cleanText(recipient_role_key) || cleanText(recipientRoleKey),
+      },
+    });
+  }
+
+  async sendCommunicationMessage({
+    communicationThreadId,
+    communication_thread_id,
+    threadId,
+    senderAgentSessionId,
+    sender_agent_session_id,
+    recipientAgentSessionId,
+    recipient_agent_session_id,
+    recipientRoleKey,
+    recipient_role_key,
+    messageKind,
+    message_kind,
+    bodyMarkdown,
+    body_markdown,
+    messageStatus,
+    message_status,
+    payload = {},
+    scope = {},
+    requiredResponseSchema = {},
+    required_response_schema = {},
+    metadata = {},
+  } = {}) {
+    return this._request('/api/agent-communications/messages', {
+      method: 'POST',
+      body: {
+        communication_thread_id: cleanText(communication_thread_id) || cleanText(communicationThreadId) || cleanText(threadId),
+        sender_agent_session_id: cleanText(sender_agent_session_id) || cleanText(senderAgentSessionId),
+        recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+        recipient_role_key: cleanText(recipient_role_key) || cleanText(recipientRoleKey),
+        message_kind: cleanText(message_kind) || cleanText(messageKind),
+        message_status: cleanText(message_status) || cleanText(messageStatus) || 'sent',
+        body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+        payload: isPlainObject(payload) ? payload : {},
+        scope: isPlainObject(scope) ? scope : {},
+        required_response_schema: isPlainObject(requiredResponseSchema)
+          ? requiredResponseSchema
+          : (isPlainObject(required_response_schema) ? required_response_schema : {}),
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
+  async acceptCommunicationMessage(messageId) {
+    return this._request(`/api/agent-communications/messages/${encodeURIComponent(messageId)}/accept`, {
+      method: 'POST',
+      body: {},
+    });
+  }
+
+  async respondToCommunicationMessage({
+    agentMessageId,
+    agent_message_id,
+    messageId,
+    status,
+    bodyMarkdown,
+    body_markdown,
+    payload = {},
+    metadata = {},
+    evidenceRefs,
+    evidence_refs,
+  } = {}) {
+    const normalizedMessageId = cleanText(agent_message_id) || cleanText(agentMessageId) || cleanText(messageId);
+    if (!normalizedMessageId) {
+      throw new Error('agent_message_id is required.');
+    }
+    return this._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/respond`, {
+      method: 'POST',
+      body: {
+        status: cleanText(status) || 'answered',
+        body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+        payload: isPlainObject(payload) ? payload : {},
+        metadata: isPlainObject(metadata) ? metadata : {},
+        evidence_refs: Array.isArray(evidence_refs) ? evidence_refs : (Array.isArray(evidenceRefs) ? evidenceRefs : []),
+      },
+    });
+  }
+
+  async attachCommunicationMessageEvidence({
+    agentMessageId,
+    agent_message_id,
+    messageId,
+    evidenceType,
+    evidence_type,
+    evidenceRef,
+    evidence_ref,
+    sourceTruth,
+    source_truth,
+    trustLevel,
+    trust_level,
+    metadata = {},
+  } = {}) {
+    const normalizedMessageId = cleanText(agent_message_id) || cleanText(agentMessageId) || cleanText(messageId);
+    if (!normalizedMessageId) {
+      throw new Error('agent_message_id is required.');
+    }
+    return this._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/attach-evidence`, {
+      method: 'POST',
+      body: {
+        evidence_type: cleanText(evidence_type) || cleanText(evidenceType),
+        evidence_ref: cleanText(evidence_ref) || cleanText(evidenceRef),
+        source_truth: cleanText(source_truth) || cleanText(sourceTruth),
+        trust_level: cleanText(trust_level) || cleanText(trustLevel) || 'candidate',
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
+  async createCommunicationHandoff({
+    workflowRunId,
+    workflow_run_id,
+    title,
+    agentSessionId,
+    agent_session_id,
+    handoffKind,
+    handoff_kind,
+    handoffPriority,
+    handoff_priority,
+    summaryText,
+    summary_text,
+    handoffPayload = {},
+    handoff_payload = {},
+    createdBy,
+    created_by,
+    supersedesHandoffId,
+    supersedes_handoff_id,
+  } = {}) {
+    return this._request('/api/agent-communications/handoffs', {
+      method: 'POST',
+      body: {
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        title: cleanText(title),
+        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId),
+        handoff_kind: cleanText(handoff_kind) || cleanText(handoffKind) || 'general',
+        handoff_priority: cleanText(handoff_priority) || cleanText(handoffPriority) || 'normal',
+        summary_text: cleanText(summary_text) || cleanText(summaryText),
+        handoff_payload: isPlainObject(handoffPayload)
+          ? handoffPayload
+          : (isPlainObject(handoff_payload) ? handoff_payload : {}),
+        created_by: cleanText(created_by) || cleanText(createdBy),
+        supersedes_handoff_id: cleanText(supersedes_handoff_id) || cleanText(supersedesHandoffId),
+      },
+    });
+  }
+
+  async acceptCommunicationHandoff(handoffId) {
+    return this._request(`/api/agent-communications/handoffs/${encodeURIComponent(handoffId)}/accept`, {
+      method: 'POST',
+      body: {},
+    });
+  }
+
   async currentProjectStatus({ projectId } = {}) {
     return this._request('/api/operator/current-project-status', {
       query: { project_id: projectId },
@@ -1587,23 +1797,26 @@ export class AIEngineClient {
       }
     }
 
-    if (!resolvedWorkflowId) {
+    if (resolvedRuns.length > 0 && !resolvedWorkflowId) {
       throw new Error('workflowId could not be resolved for project cleanup.');
     }
-    if (resolvedRuns.length === 0) {
-      throw new Error('workflowRunIds could not be resolved for project cleanup.');
+
+    const cleanupPayload = {
+      project_id: normalizedProjectId,
+      reason: normalizedReason,
+      operator_identity: normalizedOperatorIdentity,
+      run_terminal_status: cleanText(runTerminalStatus) || 'failed',
+    };
+    if (resolvedWorkflowId) {
+      cleanupPayload.workflow_id = resolvedWorkflowId;
+    }
+    if (resolvedRuns.length > 0) {
+      cleanupPayload.workflow_run_ids = resolvedRuns;
     }
 
     return this._request('/api/operator/cleanup', {
       method: 'POST',
-      body: {
-        project_id: normalizedProjectId,
-        workflow_id: resolvedWorkflowId,
-        workflow_run_ids: resolvedRuns,
-        reason: normalizedReason,
-        operator_identity: normalizedOperatorIdentity,
-        run_terminal_status: cleanText(runTerminalStatus) || 'failed',
-      },
+      body: cleanupPayload,
     });
   }