@bpmsoftwaresolutions/ai-engine-client 1.1.45 → 1.1.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.45",
+  "version": "1.1.47",
   "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.45';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.47';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -20,6 +20,99 @@ export const LOGA_INTERACTION_CONTRACT = 'loga-choreography/v1';
 export const LOGA_NAVIGATION_CONTRACT = 'loga-navigation/v1';
 export const LOGA_PROJECTION_WORKFLOW = 'loga-document-projection';
 export const TASK_BOUND_SUBSTRATE_EXECUTION_POLICY = 'task_bound_substrate_execution/v1';
+export const AGENT_COMMUNICATION_CONTRACT_VERSION = 'v1';
+export const AGENT_COMMUNICATION_THREAD_TYPES = ['request', 'review', 'handoff', 'coordination', 'task', 'escalation'];
+export const AGENT_COMMUNICATION_MESSAGE_KINDS = [
+  'request',
+  'response',
+  'review',
+  'handoff',
+  'blocker',
+  'evidence',
+  'decision_request',
+  'task_request',
+  'review_request',
+  'evidence_response',
+];
+export const AGENT_COMMUNICATION_TRANSFER_KINDS = [
+  'upstream_remediation',
+  'review_request',
+  'handoff',
+  'coordination',
+  'evidence_delivery',
+];
+export const AGENT_COMMUNICATION_TRANSFER_MODES = ['bundle', 'artifact_refs', 'inline_payload'];
+export const AGENT_COMMUNICATION_TRANSFER_LIFECYCLE_STATES = [
+  'created',
+  'delivered',
+  'accepted',
+  'in_progress',
+  'responded',
+  'closed',
+  'failed',
+  'superseded',
+];
+export const AGENT_COMMUNICATION_TRANSFER_RECEIPT_TYPES = [
+  'delivery_receipt',
+  'acceptance_receipt',
+  'evidence_receipt',
+  'closure_receipt',
+  'failure_receipt',
+];
+export const AGENT_COMMUNICATION_RECIPIENT_MODES = ['role', 'agent_session'];
+
+function normalizeEnum(value, allowed, defaultValue, fieldName, aliases = {}) {
+  const text = cleanText(value);
+  if (!text) return defaultValue;
+  let normalized = text.toLowerCase();
+  if (Object.prototype.hasOwnProperty.call(aliases, normalized)) {
+    normalized = aliases[normalized];
+  }
+  if (!allowed.includes(normalized)) {
+    throw new Error(`${fieldName} must be one of ${allowed.join(', ')}.`);
+  }
+  return normalized;
+}
+
+function normalizeThreadType(value) {
+  return normalizeEnum(value, AGENT_COMMUNICATION_THREAD_TYPES, 'coordination', 'thread_type', {
+    task_request: 'request',
+    task: 'request',
+    review_request: 'review',
+    handoff_request: 'handoff',
+  });
+}
+
+function normalizeMessageKind(value) {
+  return normalizeEnum(value, AGENT_COMMUNICATION_MESSAGE_KINDS, 'request', 'message_kind', {
+    task: 'request',
+    note: 'request',
+    update: 'response',
+  });
+}
+
+function normalizeTransferKind(value) {
+  return normalizeEnum(value, AGENT_COMMUNICATION_TRANSFER_KINDS, 'upstream_remediation', 'transfer_kind', {
+    remediation_request: 'upstream_remediation',
+    review: 'review_request',
+  });
+}
+
+function normalizeTransferMode(value) {
+  return normalizeEnum(value, AGENT_COMMUNICATION_TRANSFER_MODES, 'inline_payload', 'transfer_mode');
+}
+
+function normalizeTransferLifecycleStatus(value) {
+  return normalizeEnum(value, AGENT_COMMUNICATION_TRANSFER_LIFECYCLE_STATES, 'created', 'lifecycle_status');
+}
+
+function normalizeTransferReceiptType(value) {
+  return normalizeEnum(value, AGENT_COMMUNICATION_TRANSFER_RECEIPT_TYPES, 'delivery_receipt', 'receipt_type');
+}
+
+function normalizeRecipientMode(value) {
+  return normalizeEnum(value, AGENT_COMMUNICATION_RECIPIENT_MODES, 'role', 'recipient_mode');
+}
 
 function trimTrailingSlash(value) {
   return String(value || '').replace(/\/+$/, '');
@@ -310,6 +403,19 @@ export class AIEngineClient {
       getThread: (threadId) => this.getCommunicationThread(threadId),
       listInbox: (request) => this.listCommunicationInbox(request),
       sendMessage: (request) => this.sendCommunicationMessage(request),
+      getCommunicationCapabilities: (request) => this.getCommunicationCapabilities(request),
+      getDeploymentCapabilities: (request) => this.getDeploymentCapabilities(request),
+      bootstrap: (request) => this.bootstrapCommunication(request),
+      negotiateTransfer: (request) => this.negotiateCommunicationTransfer(request),
+      resolveCommunicationTarget: (request) => this.resolveCommunicationTarget(request),
+      createEvidencePacket: (request) => this.createCommunicationEvidencePacket(request),
+      transferWorkPacket: (request) => this.transferWorkPacket(request),
+      listFrictionTaxonomy: (request) => this.listCommunicationFrictionTaxonomy(request),
+      recordFrictionEvent: (request) => this.recordCommunicationFrictionEvent(request),
+      createTransferReceipt: (request) => this.recordCommunicationTransferReceipt(request),
+      acceptTransferPacket: (request) => this.acceptCommunicationTransferPacket(request),
+      closeTransferPacket: (request) => this.closeCommunicationTransferPacket(request),
+      getTransferHealth: (request) => this.getCommunicationTransferHealth(request),
       createBundle: (request) => this.createCommunicationBundle(request),
       getBundle: (bundleId) => this.getCommunicationBundle(bundleId),
       listBundles: (request) => this.listCommunicationBundles(request),
@@ -502,6 +608,250 @@ export class AIEngineClient {
     });
   }
 
+  async getCommunicationCapabilities() {
+    return this._request('/api/agent-communications/capabilities');
+  }
+
+  async getDeploymentCapabilities() {
+    return this._request('/api/agent-communications/deployment-capabilities');
+  }
+
+  async bootstrapCommunication() {
+    return this._request('/api/agent-communications/bootstrap');
+  }
+
+  async negotiateCommunicationTransfer({
+    preferredModes,
+    preferred_modes,
+    preferred,
+    capabilities = {},
+    estimatedPayloadKb,
+    estimated_payload_kb,
+    requiresReceipts = true,
+    requires_receipts = true,
+    supportsHashValidation = true,
+    supports_hash_validation = true,
+    transferKind,
+    transfer_kind,
+    workflowRunId,
+    workflow_run_id,
+  } = {}) {
+    const normalizedPreferredModes = Array.isArray(preferred_modes)
+      ? preferred_modes
+      : (Array.isArray(preferredModes) ? preferredModes : (Array.isArray(preferred) ? preferred : ['bundle', 'artifact_refs', 'inline_payload']));
+    return this._request('/api/agent-communications/transfers/negotiate', {
+      method: 'POST',
+      body: {
+        preferred_modes: normalizedPreferredModes.map((mode) => normalizeTransferMode(mode)),
+        capabilities: isPlainObject(capabilities) ? capabilities : {},
+        estimated_payload_kb: Number(estimated_payload_kb ?? estimatedPayloadKb ?? 0) || undefined,
+        requires_receipts: Boolean(requires_receipts ?? requiresReceipts),
+        supports_hash_validation: Boolean(supports_hash_validation ?? supportsHashValidation),
+        transfer_kind: normalizeTransferKind(transfer_kind ?? transferKind ?? 'upstream_remediation'),
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      },
+    });
+  }
+
+  async resolveCommunicationTarget({
+    intent,
+    transferKind,
+    transfer_kind,
+    recipientMode,
+    recipient_mode,
+    preferredRoleKey,
+    preferred_role_key,
+    preferredAgentSessionId,
+    preferred_agent_session_id,
+    workflowRunId,
+    workflow_run_id,
+  } = {}) {
+    return this._request('/api/agent-communications/targets/resolve', {
+      method: 'POST',
+      body: {
+        intent: cleanText(intent) || cleanText(transfer_kind) || cleanText(transferKind),
+        recipient_mode: normalizeRecipientMode(recipient_mode ?? recipientMode ?? 'role'),
+        preferred_role_key: cleanText(preferred_role_key) || cleanText(preferredRoleKey),
+        preferred_agent_session_id: cleanText(preferred_agent_session_id) || cleanText(preferredAgentSessionId),
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      },
+    });
+  }
+
+  async createCommunicationEvidencePacket({
+    workflowRunId,
+    workflow_run_id,
+    transferKind,
+    transfer_kind,
+    objective,
+    requestedOutcome,
+    requested_outcome,
+    artifacts = [],
+    artifactRefs,
+    artifact_refs,
+    issues = [],
+    issueRefs,
+    issue_refs,
+    expectedEvidence = [],
+    expected_evidence,
+    metadata = {},
+  } = {}) {
+    return this._request('/api/agent-communications/evidence-packets', {
+      method: 'POST',
+      body: {
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        transfer_kind: normalizeTransferKind(transfer_kind ?? transferKind ?? 'upstream_remediation'),
+        objective: cleanText(objective),
+        requested_outcome: cleanText(requested_outcome) || cleanText(requestedOutcome),
+        artifacts: Array.isArray(artifacts) ? artifacts : (Array.isArray(artifact_refs) ? artifact_refs : (Array.isArray(artifactRefs) ? artifactRefs : [])),
+        issues: Array.isArray(issues) ? issues : (Array.isArray(issue_refs) ? issue_refs : (Array.isArray(issueRefs) ? issueRefs : [])),
+        expected_evidence: Array.isArray(expected_evidence) ? expected_evidence : (Array.isArray(expectedEvidence) ? expectedEvidence : []),
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
+  async listCommunicationFrictionTaxonomy({
+    categoryGroup,
+    category_group,
+    isActive,
+    is_active,
+  } = {}) {
+    return this._request('/api/agent-communications/friction-taxonomy', {
+      query: {
+        category_group: cleanText(category_group) || cleanText(categoryGroup),
+        is_active: is_active !== undefined ? String(Boolean(is_active)) : (isActive !== undefined ? String(Boolean(isActive)) : undefined),
+      },
+    });
+  }
+
+  async recordCommunicationFrictionEvent({
+    workflowRunId,
+    workflow_run_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    communicationThreadId,
+    communication_thread_id,
+    communicationMessageId,
+    communication_message_id,
+    taxonomyKey,
+    taxonomy_key,
+    frictionType,
+    friction_type,
+    severity,
+    observedBehavior,
+    observed_behavior,
+    attemptedAction,
+    attempted_action,
+    resolutionPath,
+    resolution_path,
+    missingSurfaceKey,
+    missing_surface_key,
+    promotionCandidate,
+    promotion_candidate,
+    repeatedCount,
+    repeated_count,
+    metadata = {},
+  } = {}) {
+    return this._request('/api/agent-communications/friction-events', {
+      method: 'POST',
+      body: {
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId),
+        communication_thread_id: cleanText(communication_thread_id) || cleanText(communicationThreadId),
+        communication_message_id: cleanText(communication_message_id) || cleanText(communicationMessageId),
+        taxonomy_key: cleanText(taxonomy_key) || cleanText(taxonomyKey) || 'enum_drift',
+        friction_type: cleanText(friction_type) || cleanText(frictionType) || 'discovery',
+        severity: cleanText(severity) || 'warning',
+        observed_behavior: cleanText(observed_behavior) || cleanText(observedBehavior),
+        attempted_action: cleanText(attempted_action) || cleanText(attemptedAction),
+        resolution_path: cleanText(resolution_path) || cleanText(resolutionPath),
+        missing_surface_key: cleanText(missing_surface_key) || cleanText(missingSurfaceKey),
+        promotion_candidate: Boolean(promotion_candidate ?? promotionCandidate),
+        repeated_count: Number(repeated_count ?? repeatedCount ?? 1) || 1,
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
+  async transferWorkPacket({
+    workflowRunId,
+    workflow_run_id,
+    transferKind,
+    transfer_kind,
+    objective,
+    requestedOutcome,
+    requested_outcome,
+    target = {},
+    artifacts = [],
+    issues = [],
+    expectedEvidence = [],
+    preferredModes,
+    preferred_modes,
+    preferred,
+    capabilities = {},
+    estimatedPayloadKb,
+    estimated_payload_kb,
+    requiresReceipts = true,
+    requires_receipts = true,
+    supportsHashValidation = true,
+    supports_hash_validation = true,
+    senderAgentSessionId,
+    sender_agent_session_id,
+    senderActorSessionId,
+    sender_actor_session_id,
+    subject,
+    bodyMarkdown,
+    body_markdown,
+    parentThreadId,
+    parent_thread_id,
+    recipientMode,
+    recipient_mode,
+    recipientRoleKey,
+    recipient_role_key,
+    recipientAgentSessionId,
+    recipient_agent_session_id,
+    cleanupPolicy,
+    cleanup_policy,
+  } = {}) {
+    const normalizedTarget = isPlainObject(target) ? target : {};
+    const normalizedWorkflowRunId = cleanText(workflow_run_id) || cleanText(workflowRunId);
+    const normalizedTransferKind = normalizeTransferKind(transfer_kind ?? transferKind ?? 'upstream_remediation');
+    const normalizedPreferredModes = Array.isArray(preferred_modes)
+      ? preferred_modes
+      : (Array.isArray(preferredModes) ? preferredModes : (Array.isArray(preferred) ? preferred : ['bundle', 'artifact_refs', 'inline_payload']));
+    const normalizedTargetMode = cleanText(normalizedTarget.recipient_mode) || cleanText(normalizedTarget.recipientMode) || cleanText(recipient_mode) || cleanText(recipientMode) || 'role';
+    return this._request('/api/agent-communications/work-transfers', {
+      method: 'POST',
+      body: {
+        workflow_run_id: normalizedWorkflowRunId,
+        transfer_kind: normalizedTransferKind,
+        objective: cleanText(objective),
+        requested_outcome: cleanText(requested_outcome) || cleanText(requestedOutcome),
+        target: {
+          intent: cleanText(normalizedTarget.intent) || normalizedTransferKind,
+          recipient_mode: normalizeRecipientMode(normalizedTargetMode),
+          preferred_role_key: cleanText(normalizedTarget.preferred_role_key) || cleanText(normalizedTarget.preferredRoleKey) || cleanText(recipient_role_key) || cleanText(recipientRoleKey),
+          preferred_agent_session_id: cleanText(normalizedTarget.preferred_agent_session_id) || cleanText(normalizedTarget.preferredAgentSessionId) || cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+        },
+        artifacts: Array.isArray(artifacts) ? artifacts : [],
+        issues: Array.isArray(issues) ? issues : [],
+        expected_evidence: Array.isArray(expectedEvidence) ? expectedEvidence : [],
+        preferred_modes: normalizedPreferredModes.map((mode) => normalizeTransferMode(mode)),
+        capabilities: isPlainObject(capabilities) ? capabilities : {},
+        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_actor_session_id: cleanText(sender_actor_session_id) || cleanText(senderActorSessionId),
+        subject: cleanText(subject),
+        body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
+        parent_thread_id: cleanText(parent_thread_id) || cleanText(parentThreadId),
+        cleanup_policy: cleanText(cleanup_policy) || cleanText(cleanupPolicy),
+      },
+    });
+  }
+
   async openCommunicationThread({
     workflowRunId,
     workflow_run_id,
@@ -522,7 +872,7 @@ export class AIEngineClient {
       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),
+        thread_type: normalizeThreadType(cleanText(thread_type) || cleanText(threadType)),
         subject: cleanText(subject),
         objective: cleanText(objective),
         created_by_agent_session_id: cleanText(created_by_agent_session_id) || cleanText(createdByAgentSessionId),
@@ -585,7 +935,7 @@ export class AIEngineClient {
         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_kind: normalizeMessageKind(cleanText(message_kind) || cleanText(messageKind)),
         message_status: cleanText(message_status) || cleanText(messageStatus) || 'sent',
         body_markdown: cleanText(body_markdown) || cleanText(bodyMarkdown),
         payload: isPlainObject(payload) ? payload : {},
@@ -836,6 +1186,135 @@ export class AIEngineClient {
     });
   }
 
+  async recordCommunicationTransferReceipt({
+    workTransferPacketId,
+    work_transfer_packet_id,
+    receiptType,
+    receipt_type,
+    receiptStatus,
+    receipt_status,
+    actorSessionId,
+    actor_session_id,
+    agentSessionId,
+    agent_session_id,
+    claimId,
+    claim_id,
+    evidenceRef,
+    evidence_ref,
+    evidenceSha256,
+    evidence_sha256,
+    evidence = {},
+    manifestSha256,
+    manifest_sha256,
+    closureReason,
+    closure_reason,
+    failureReason,
+    failure_reason,
+    lifecycleStatus,
+    lifecycle_status,
+    metadata = {},
+  } = {}) {
+    const normalizedPacketId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId);
+    if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+    return this._request(`/api/agent-communications/transfers/${encodeURIComponent(normalizedPacketId)}/receipts`, {
+      method: 'POST',
+      body: {
+        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),
+        claim_id: cleanText(claim_id) || cleanText(claimId),
+        evidence_ref: cleanText(evidence_ref) || cleanText(evidenceRef),
+        evidence_sha256: cleanText(evidence_sha256) || cleanText(evidenceSha256),
+        evidence: isPlainObject(evidence) ? evidence : {},
+        manifest_sha256: cleanText(manifest_sha256) || cleanText(manifestSha256),
+        closure_reason: cleanText(closure_reason) || cleanText(closureReason),
+        failure_reason: cleanText(failure_reason) || cleanText(failureReason),
+        lifecycle_status: cleanText(lifecycle_status) || cleanText(lifecycleStatus),
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
+  async acceptCommunicationTransferPacket({
+    workTransferPacketId,
+    work_transfer_packet_id,
+    acceptedByAgentSessionId,
+    accepted_by_agent_session_id,
+    acceptedByActorSessionId,
+    accepted_by_actor_session_id,
+    acceptedByClaimId,
+    accepted_by_claim_id,
+    advanceToInProgress,
+    advance_to_in_progress,
+    metadata = {},
+  } = {}) {
+    const normalizedPacketId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId);
+    if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+    return this._request(`/api/agent-communications/transfers/${encodeURIComponent(normalizedPacketId)}/accept`, {
+      method: 'POST',
+      body: {
+        accepted_by_agent_session_id: cleanText(accepted_by_agent_session_id) || cleanText(acceptedByAgentSessionId),
+        accepted_by_actor_session_id: cleanText(accepted_by_actor_session_id) || cleanText(acceptedByActorSessionId),
+        accepted_by_claim_id: cleanText(accepted_by_claim_id) || cleanText(acceptedByClaimId),
+        advance_to_in_progress: Boolean(advance_to_in_progress ?? advanceToInProgress),
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
+  async closeCommunicationTransferPacket({
+    workTransferPacketId,
+    work_transfer_packet_id,
+    closureStatus,
+    closure_status,
+    closureReason,
+    closure_reason,
+    failureReason,
+    failure_reason,
+    closedByAgentSessionId,
+    closed_by_agent_session_id,
+    closedByActorSessionId,
+    closed_by_actor_session_id,
+    closedByClaimId,
+    closed_by_claim_id,
+    evidence = {},
+    evidenceManifestSha256,
+    evidence_manifest_sha256,
+    metadata = {},
+  } = {}) {
+    const normalizedPacketId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId);
+    if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+    return this._request(`/api/agent-communications/transfers/${encodeURIComponent(normalizedPacketId)}/close`, {
+      method: 'POST',
+      body: {
+        closure_status: normalizeTransferLifecycleStatus(cleanText(closure_status) || cleanText(closureStatus) || 'closed'),
+        closure_reason: cleanText(closure_reason) || cleanText(closureReason),
+        failure_reason: cleanText(failure_reason) || cleanText(failureReason),
+        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),
+        evidence: isPlainObject(evidence) ? evidence : {},
+        evidence_manifest_sha256: cleanText(evidence_manifest_sha256) || cleanText(evidenceManifestSha256),
+        metadata: isPlainObject(metadata) ? metadata : {},
+      },
+    });
+  }
+
+  async getCommunicationTransferHealth({
+    workflowRunId,
+    workflow_run_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+  } = {}) {
+    return this._request('/api/agent-communications/transfers/health', {
+      query: {
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId),
+      },
+    });
+  }
+
   async acceptCommunicationMessage(messageId) {
     return this._request(`/api/agent-communications/messages/${encodeURIComponent(messageId)}/accept`, {
       method: 'POST',