@bpmsoftwaresolutions/ai-engine-client 1.1.98 → 1.1.101

package/src/domains/refactoring-transfers.js

@@ -0,0 +1,405 @@
+import { cleanText, isPlainObject } from '../utils/communication.js';
+
+export function createRefactoringTransfersDomain(client) {
+  return {
+    transferRefactoringBundle: (request) => transferRefactoringBundle(client, request),
+  };
+}
+
+export async function transferRefactoringBundle(client, {
+  projectIdentifier,
+  projectId,
+  startWorkBody = {},
+  startWorkRequest = {},
+  resumeProjectWorkOptions = {},
+  transferChannelId,
+  transfer_channel_id,
+  channelId,
+  channel_id,
+  workTransferPacketId,
+  work_transfer_packet_id,
+  workflowRunId,
+  workflow_run_id,
+  sourceAgent,
+  source_agent,
+  sourceAgentSessionId,
+  source_agent_session_id,
+  targetAgent,
+  target_agent,
+  targetAgentSessionId,
+  target_agent_session_id,
+  targetAgentLabel,
+  target_agent_label,
+  sourceRef,
+  source_ref,
+  problemStatement,
+  problem_statement,
+  affectedFilesOrSymbols,
+  affected_files_or_symbols,
+  recommendedAction,
+  recommended_action,
+  acceptanceCriteria,
+  acceptance_criteria,
+  evidenceRefs = [],
+  evidence_refs = [],
+  riskLevel,
+  risk_level,
+  handoffNotes,
+  handoff_notes,
+  ownershipAssignment = {},
+  ownership_assignment = {},
+  proposal = {},
+  refactoringBundle = {},
+  refactoring_bundle = {},
+  participantRole,
+  participant_role,
+  includeTransferChannelProjection = true,
+  includeOperatorProjectionMetadata = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const normalizedBundle = isPlainObject(refactoring_bundle)
+    ? refactoring_bundle
+    : (isPlainObject(refactoringBundle) ? refactoringBundle : {});
+  const normalizedOwnershipAssignment = isPlainObject(ownership_assignment)
+    ? ownership_assignment
+    : (isPlainObject(ownershipAssignment) ? ownershipAssignment : {});
+  const normalizedProposal = isPlainObject(proposal) ? proposal : {};
+  const normalizedProjectReference = cleanText(projectIdentifier) || cleanText(projectId);
+  const normalizedSourceAgent = cleanText(source_agent) || cleanText(sourceAgent) || client.agentSessionId || client.actorId;
+  const normalizedTargetAgent = cleanText(target_agent) || cleanText(targetAgent) || cleanText(target_agent_session_id) || cleanText(targetAgentSessionId);
+  const normalizedTargetLabel = cleanText(target_agent_label) || cleanText(targetAgentLabel) || normalizedTargetAgent;
+  const normalizedParticipantRole = cleanText(participant_role) || cleanText(participantRole) || 'requester';
+  const normalizedSourceRef = cleanText(source_ref) || cleanText(sourceRef) || cleanText(normalizedBundle.source_ref);
+  const normalizedProblemStatement = cleanText(problem_statement) || cleanText(problemStatement) || cleanText(normalizedBundle.problem_statement);
+  const normalizedAffectedFiles = Array.isArray(affected_files_or_symbols)
+    ? affected_files_or_symbols
+    : (Array.isArray(affectedFilesOrSymbols) ? affectedFilesOrSymbols : normalizedBundle.affected_files_or_symbols || []);
+  const normalizedRecommendedAction = cleanText(recommended_action) || cleanText(recommendedAction) || cleanText(normalizedBundle.recommended_action);
+  const normalizedAcceptanceCriteria = Array.isArray(acceptance_criteria)
+    ? acceptance_criteria
+    : (Array.isArray(acceptanceCriteria) ? acceptanceCriteria : normalizedBundle.acceptance_criteria || []);
+  const normalizedEvidenceRefs = Array.isArray(evidence_refs) ? evidence_refs : (Array.isArray(evidenceRefs) ? evidenceRefs : normalizedBundle.evidence_refs || []);
+  const normalizedRiskLevel = cleanText(risk_level) || cleanText(riskLevel) || cleanText(normalizedBundle.risk_level) || 'medium';
+  const normalizedHandoffNotes = cleanText(handoff_notes) || cleanText(handoffNotes) || cleanText(normalizedBundle.handoff_notes);
+  const shouldMoveOwnership = Boolean(normalizedTargetAgent || normalizedOwnershipAssignment.owner_agent_session_id);
+  if (!normalizedTargetAgent) {
+    throw new Error('target_agent is required.');
+  }
+
+  let continuation = null;
+  let startWorkResult = null;
+  if (normalizedProjectReference) {
+    if (typeof client.resumeProjectWork === 'function') {
+      continuation = await client.resumeProjectWork({
+        projectIdentifier: normalizedProjectReference,
+        projectId: normalizedProjectReference,
+        requireClaim: false,
+        ...resumeProjectWorkOptions,
+        ...normalizedMetadata.resume_project_work_options,
+      });
+    } else {
+      missingSurfaces.push('resumeProjectWork');
+    }
+  } else if (Object.keys(isPlainObject(startWorkRequest) ? startWorkRequest : {}).length > 0 || Object.keys(isPlainObject(startWorkBody) ? startWorkBody : {}).length > 0) {
+    if (typeof client.startWork === 'function') {
+      startWorkResult = await client.startWork({
+        ...(isPlainObject(startWorkBody) ? startWorkBody : {}),
+        ...(isPlainObject(startWorkRequest) ? startWorkRequest : {}),
+      });
+    } else {
+      missingSurfaces.push('startWork');
+    }
+  } 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) || normalizedProjectReference;
+  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) || cleanText(workflow_run_id) || cleanText(workflowRunId);
+  if (!resolvedProjectId || !resolvedWorkflowRunId) {
+    throw new Error('project/work identifiers are ambiguous.');
+  }
+
+  const transferSurface = typeof client.transferWorkPacket === 'function'
+    ? client.transferWorkPacket.bind(client)
+    : null;
+  if (!transferSurface) missingSurfaces.push('transferWorkPacket');
+  const transferResult = transferSurface
+    ? await transferSurface({
+        workflowRunId: resolvedWorkflowRunId,
+        transferKind: 'upstream_remediation',
+        objective: normalizedProblemStatement || normalizedRecommendedAction || 'Refactoring bundle transfer',
+        requestedOutcome: normalizedRecommendedAction || normalizedProblemStatement || 'Receive refactoring bundle acknowledgement.',
+        target: {
+          intent: 'upstream_remediation',
+          recipient_mode: 'agent_session',
+          preferred_agent_session_id: normalizedTargetAgent,
+          preferred_role_key: normalizedTargetLabel,
+        },
+        artifacts: normalizedAffectedFiles,
+        issues: [],
+        expectedEvidence: normalizedAcceptanceCriteria,
+        preferredModes: ['bundle', 'artifact_refs', 'inline_payload'],
+        capabilities: {},
+        senderAgentSessionId: normalizedSourceAgent,
+        senderActorSessionId: null,
+        subject: normalizedProblemStatement || normalizedRecommendedAction || 'Refactoring bundle transfer',
+        bodyMarkdown: normalizedHandoffNotes || normalizedRecommendedAction || normalizedProblemStatement,
+        messageKind: 'handoff',
+        metadata: {
+          ...normalizedMetadata,
+          source: 'transferRefactoringBundle',
+          source_ref: normalizedSourceRef,
+          risk_level: normalizedRiskLevel,
+        },
+      })
+    : null;
+  const transferPayload = isPlainObject(transferResult) ? transferResult : {};
+  let resolvedWorkTransferPacketId = cleanText(work_transfer_packet_id)
+    || cleanText(workTransferPacketId)
+    || cleanText(transferPayload.work_transfer_packet?.work_transfer_packet_id)
+    || cleanText(transferPayload.work_transfer_packet_id)
+    || cleanText(transferPayload.transfer_packet_id)
+    || cleanText(transferPayload.packet_id)
+    || null;
+  const transferChannel = isPlainObject(transferPayload.communication_transfer_channel) ? transferPayload.communication_transfer_channel : {};
+  let resolvedTransferChannelId = cleanText(transfer_channel_id)
+    || cleanText(transferChannelId)
+    || cleanText(channel_id)
+    || cleanText(channelId)
+    || cleanText(transferChannel.transfer_channel_id)
+    || cleanText(transferChannel.channel_id)
+    || null;
+
+  const shouldResumeChannel = Boolean(cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId));
+  const channelSurface = shouldResumeChannel
+    ? (typeof client.resumeTransferChannel === 'function'
+      ? client.resumeTransferChannel.bind(client)
+      : null)
+    : (typeof client.openTransferChannel === 'function'
+      ? client.openTransferChannel.bind(client)
+      : null);
+  if (!channelSurface) missingSurfaces.push(shouldResumeChannel ? 'resumeTransferChannel' : 'openTransferChannel');
+  const channelResult = channelSurface && resolvedWorkTransferPacketId
+    ? await channelSurface({
+        transferChannelId: resolvedTransferChannelId,
+        workTransferPacketId: resolvedWorkTransferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        channelKind: 'bidirectional',
+        downstreamAgentSessionId: normalizedTargetAgent,
+        downstreamActorSessionId: null,
+        upstreamAgentSessionId: normalizedSourceAgent,
+        upstreamActorSessionId: null,
+        evidenceRequiredForClosure: true,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'transferRefactoringBundle',
+        },
+      })
+    : null;
+  const channelPayload = isPlainObject(channelResult) ? channelResult : {};
+  resolvedTransferChannelId = cleanText(channelPayload.transfer_channel_id)
+    || cleanText(channelPayload.channel_id)
+    || cleanText(channelPayload.transfer_channel?.transfer_channel_id)
+    || cleanText(channelPayload.communication_transfer_channel?.transfer_channel_id)
+    || resolvedTransferChannelId;
+
+  const ownershipSurface = typeof client.assignCollaborationOwnership === 'function'
+    ? client.assignCollaborationOwnership.bind(client)
+    : null;
+  if (!ownershipSurface) missingSurfaces.push('assignCollaborationOwnership');
+  const ownershipResult = ownershipSurface && resolvedTransferChannelId && normalizedTargetAgent
+    ? await ownershipSurface({
+        transferChannelId: resolvedTransferChannelId,
+        workTransferPacketId: resolvedWorkTransferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: normalizedParticipantRole,
+        ownerAgentSessionId: normalizedTargetAgent,
+        ownerActorSessionId: null,
+        ownerLabel: normalizedTargetLabel,
+        assignmentState: 'assigned',
+        assignmentReason: normalizedProblemStatement || normalizedRecommendedAction,
+        currentPhase: 'refactoring_bundle_transfer',
+        assignedByAgentSessionId: normalizedSourceAgent,
+        assignedByActorSessionId: null,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'transferRefactoringBundle',
+          source_ref: normalizedSourceRef,
+        },
+      })
+    : null;
+  const ownershipPayload = isPlainObject(ownershipResult) ? ownershipResult : {};
+
+  const proposalSurface = typeof client.postCollaborationProposal === 'function'
+    ? client.postCollaborationProposal.bind(client)
+    : null;
+  if (!proposalSurface) missingSurfaces.push('postCollaborationProposal');
+  const proposalResult = proposalSurface && resolvedTransferChannelId && resolvedWorkTransferPacketId
+    ? await proposalSurface({
+        transferChannelId: resolvedTransferChannelId,
+        workTransferPacketId: resolvedWorkTransferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        proposalKind: 'refactoring_bundle',
+        proposalState: 'proposed',
+        participantRole: normalizedParticipantRole,
+        proposalSummary: normalizedProblemStatement || normalizedRecommendedAction || 'Refactoring bundle transfer',
+        currentPhase: 'refactoring_bundle_transfer',
+        expectedNextUpdate: normalizedAcceptanceCriteria.join('; ') || normalizedRecommendedAction,
+        requiredEvidence: normalizedAcceptanceCriteria,
+        responseSchema: {
+          source_ref: normalizedSourceRef,
+          risk_level: normalizedRiskLevel,
+          target_agent: normalizedTargetAgent,
+        },
+        blockerSummary: normalizedProblemStatement || normalizedRecommendedAction,
+        revisionNumber: 1,
+        proposerAgentSessionId: normalizedSourceAgent,
+        proposerActorSessionId: null,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'transferRefactoringBundle',
+          affected_files_or_symbols: normalizedAffectedFiles,
+        },
+      })
+    : null;
+  const proposalPayload = isPlainObject(proposalResult) ? proposalResult : {};
+
+  const watchSurface = typeof client.startMessageWatch === 'function'
+    ? client.startMessageWatch.bind(client)
+    : null;
+  if (!watchSurface) missingSurfaces.push('startMessageWatch');
+  const watchResult = watchSurface && resolvedTransferChannelId && resolvedWorkTransferPacketId
+    ? await watchSurface({
+        transferChannelId: resolvedTransferChannelId,
+        workTransferPacketId: resolvedWorkTransferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        watchingAgentRole: normalizedSourceAgent,
+        expectedFromRole: normalizedTargetAgent,
+        expectedMessageKind: 'response',
+        watchType: 'expected_peer_message',
+        watchingAgentSessionId: normalizedSourceAgent,
+        expectedPayload: {
+          source_ref: normalizedSourceRef,
+          expected_acknowledgement: 'refactoring bundle received',
+          target_agent: normalizedTargetAgent,
+        },
+        currentStatus: 'watching',
+        operatorNudge: normalizedHandoffNotes || normalizedRecommendedAction || normalizedProblemStatement,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'transferRefactoringBundle',
+        },
+      })
+    : null;
+  const watchPayload = isPlainObject(watchResult) ? watchResult : {};
+
+  const heartbeatSurface = typeof client.postCollaborationHeartbeat === 'function'
+    ? client.postCollaborationHeartbeat.bind(client)
+    : typeof client.postAgentHeartbeat === 'function'
+      ? client.postAgentHeartbeat.bind(client)
+      : null;
+  if (!heartbeatSurface) missingSurfaces.push('postCollaborationHeartbeat');
+  const heartbeatResult = heartbeatSurface && resolvedTransferChannelId && resolvedWorkTransferPacketId
+    ? await heartbeatSurface({
+        transferChannelId: resolvedTransferChannelId,
+        workTransferPacketId: resolvedWorkTransferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: normalizedParticipantRole,
+        activityState: 'active',
+        agentSessionId: normalizedSourceAgent,
+        currentPhase: 'refactoring_bundle_transfer',
+        currentTaskSummary: normalizedProblemStatement || normalizedRecommendedAction || 'Refactoring bundle transfer',
+        isActive: true,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'transferRefactoringBundle',
+        },
+      })
+    : null;
+  const heartbeatPayload = isPlainObject(heartbeatResult) ? heartbeatResult : {};
+
+  const transferChannelProjectionSurface = typeof client.getTransferChannelProjection === 'function'
+    ? client.getTransferChannelProjection.bind(client)
+    : typeof client.getLogaTransferChannelThreadProjection === 'function'
+      ? client.getLogaTransferChannelThreadProjection.bind(client)
+      : null;
+  if (!transferChannelProjectionSurface) missingSurfaces.push('getTransferChannelProjection');
+  const transferChannelProjection = includeTransferChannelProjection && transferChannelProjectionSurface && resolvedTransferChannelId
+    ? await transferChannelProjectionSurface(resolvedTransferChannelId).catch(() => null)
+    : null;
+
+  const transferPacketId = cleanText(transferPayload.work_transfer_packet?.work_transfer_packet_id)
+    || cleanText(transferPayload.work_transfer_packet_id)
+    || cleanText(transferPayload.transfer_packet_id)
+    || cleanText(transferPayload.packet_id)
+    || resolvedWorkTransferPacketId
+    || null;
+  const channelIdResolved = resolvedTransferChannelId || cleanText(channelPayload.transfer_channel_id) || cleanText(channelPayload.channel_id) || null;
+  const ownershipAssignmentId = cleanText(ownershipPayload.collaboration_ownership_assignment_id)
+    || cleanText(ownershipPayload.ownership_assignment_id)
+    || cleanText(ownershipPayload.collaboration_ownership_assignment?.collaboration_ownership_assignment_id)
+    || cleanText(ownershipPayload.collaboration_ownership_assignment?.ownership_assignment_id)
+    || null;
+  const proposalId = cleanText(proposalPayload.collaboration_proposal_id)
+    || cleanText(proposalPayload.proposal_id)
+    || cleanText(proposalPayload.collaboration_proposal?.collaboration_proposal_id)
+    || cleanText(proposalPayload.collaboration_proposal?.proposal_id)
+    || null;
+  const watchId = cleanText(watchPayload.message_watch_id)
+    || cleanText(watchPayload.watch_id)
+    || cleanText(watchPayload.message_watch?.message_watch_id)
+    || cleanText(watchPayload.message_watch?.watch_id)
+    || null;
+  const heartbeatStatus = cleanText(heartbeatPayload.collaboration_heartbeat?.activity_state)
+    || cleanText(heartbeatPayload.activity_state)
+    || cleanText(heartbeatPayload.status)
+    || cleanText(heartbeatPayload.collaboration_heartbeat?.status)
+    || 'active';
+  const expectedAcknowledgement = cleanText(watchPayload.expected_message_kind)
+    || cleanText(watchPayload.message_watch?.expected_message_kind)
+    || cleanText(watchPayload.message_watch?.expected_acknowledgement)
+    || 'response';
+  const operatorProjectionMetadata = includeOperatorProjectionMetadata
+    ? {
+        transfer_channel_projection: transferChannelProjection,
+        transfer: transferPayload,
+        channel: channelPayload,
+        ownership_assignment: ownershipPayload,
+        proposal: proposalPayload,
+        message_watch: watchPayload,
+        heartbeat: heartbeatPayload,
+      }
+    : null;
+
+  return {
+    status: missingSurfaces.length > 0 ? 'partial' : 'ready',
+    project_id: resolvedProjectId,
+    source_agent: normalizedSourceAgent,
+    target_agent: normalizedTargetAgent,
+    transfer_packet_id: transferPacketId,
+    channel_id: channelIdResolved,
+    ownership_assignment_id: ownershipAssignmentId,
+    proposal_id: proposalId,
+    watch_id: watchId,
+    expected_acknowledgement: expectedAcknowledgement,
+    heartbeat_status: heartbeatStatus,
+    operator_projection_metadata: operatorProjectionMetadata,
+    missing_surfaces: [...new Set(missingSurfaces)],
+    transfer: transferPayload,
+    channel: channelPayload,
+    ownership_assignment: ownershipPayload,
+    proposal: proposalPayload,
+    message_watch: watchPayload,
+    heartbeat: heartbeatPayload,
+  };
+}

package/src/index.js

@@ -1,5 +1,5 @@
 export { AIEngineClient, createAIEngineClient } from './client.js';
-export const AI_ENGINE_CLIENT_VERSION = '1.1.98';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.101';
 export { GOVERNED_MUTATION_REQUIRED_CAPABILITIES, AI_ENGINE_CLIENT_CAPABILITIES, TASK_BOUND_SUBSTRATE_EXECUTION_POLICY } from './constants/governance.js';
 export { LOGA_CONTRACT, LOGA_INTERACTION_CONTRACT, LOGA_NAVIGATION_CONTRACT, LOGA_PROJECTION_WORKFLOW } from './constants/loga.js';
 export {

package/src/transport/index.js

@@ -1,4 +1,5 @@
-import { appendQuery, extractLogaProjectionMetadata, isJsonBody, parseContentDispositionFilename, readJson } from '../utils/http.js';
+import { appendQuery, isJsonBody, parseContentDispositionFilename, readJson } from '../utils/request.js';
+import { extractLogaProjectionMetadata } from '../utils/loga.js';
 
 export async function resolveAccessToken(client) {
   if (typeof client.tokenProvider === 'function') {

package/src/utils/communication.js

@@ -16,7 +16,7 @@ function normalizeEnum(value, allowedValues, fallback, label, aliases = {}) {
   const lower = normalized.toLowerCase();
   const match = allowedValues.find((item) => item.toLowerCase() === lower);
   if (match) return match;
-  throw new Error(`Invalid ${label || 'value'}: ${value}`);
+  throw new Error(`${label || 'value'} must be one of ${allowedValues.join(', ')}.`);
 }
 
 export function cleanText(value) {

package/src/utils/loga.js

@@ -0,0 +1 @@
+export { extractLogaProjectionMetadata } from './http.js';

package/src/utils/request.js

@@ -0,0 +1,10 @@
+export {
+  appendQuery,
+  extractLogaProjectionMetadata,
+  isBinaryBody,
+  isFormDataBody,
+  isJsonBody,
+  parseContentDispositionFilename,
+  readJson,
+  readResponseHeader,
+} from './http.js';

package/src/utils/version.js

@@ -0,0 +1,12 @@
+export function compareSemanticVersions(left, right) {
+  const leftParts = String(left || '').split('.').map((part) => Number.parseInt(part, 10) || 0);
+  const rightParts = String(right || '').split('.').map((part) => Number.parseInt(part, 10) || 0);
+  const width = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < width; index += 1) {
+    const a = leftParts[index] || 0;
+    const b = rightParts[index] || 0;
+    if (a > b) return 1;
+    if (a < b) return -1;
+  }
+  return 0;
+}