@bpmsoftwaresolutions/ai-engine-client 1.1.71 → 1.1.74

package/README.md

@@ -122,6 +122,113 @@ The helper:
 
 The backend still does not expose a project-scoped `getActiveClaim(projectId)` helper. This client records that gap and uses `claimIsValid(claimId)` plus claim creation when it needs a governed fallback path.
 
+### Agent Communication Channels
+
+Use `establishAgentCommunicationChannel(...)` when you want the client to compose the governed transfer-channel handshake end to end for a project or work packet.
+
+```js
+const channel = await client.establishAgentCommunicationChannel({
+  projectIdentifier: charter.project_id,
+});
+```
+
+The helper composes:
+
+- `resumeProjectWork(...)` or `startWork(...)`
+- `transferWorkPacket(...)`
+- `openTransferChannel(...)`
+- `joinTransferChannel(...)` or `resumeTransferChannel(...)`
+- `postCollaborationHeartbeat(...)`
+- `getTransferChannelProjection(...)` when available
+
+The returned result includes `missing_surfaces[]` so the client can record any absent transfer-channel projection or lifecycle surface while still returning a safe partial view tied to governed work.
+
+### Inter-Agent Messaging Loop
+
+Use `runInterAgentMessagingLoop(...)` when a governed transfer channel already exists and the agent needs to send a reply, start an expected-message watch, acknowledge the observed message, heartbeat the channel, and close it only when closure criteria are explicit.
+
+```js
+const loop = await client.runInterAgentMessagingLoop({
+  channelId: channel.channel_id,
+  workTransferPacketId: channel.transfer_packet_id,
+  replyBodyMarkdown: 'Confirmed. Proceeding with the next step.',
+  closeWhenAcknowledged: true,
+});
+```
+
+The helper composes:
+
+- `resumeTransferChannel(...)`
+- `replyToTransferChannel(...)`
+- `startMessageWatch(...)`
+- `acknowledgeExpectedMessage(...)`
+- `postCollaborationHeartbeat(...)`
+- `closeTransferChannel(...)` when the closure criteria are explicit and satisfied
+- `getTransferChannelProjection(...)` when available
+
+`missing_surfaces[]` records any absent reply/watch/ack/close/projection surface so the helper can return a safe partial result rather than inventing a free-floating message flow.
+
+### Cross-Agent Remediation Tickets
+
+Use `createCrossAgentRemediationTicket(...)` when one agent needs to file a governed remediation ticket for another agent from an existing channel, finding, blocker, failed check, or workflow gap.
+
+```js
+const ticket = await client.createCrossAgentRemediationTicket({
+  channelId: channel.channel_id,
+  workTransferPacketId: channel.transfer_packet_id,
+  assignedTo: 'agent-upstream',
+  requestedBy: 'agent-downstream',
+  sourceRef: 'finding-42',
+  blockerSummary: 'Remediation ownership needs to move upstream.',
+  expectedResponse: 'Assignee acknowledgement',
+});
+```
+
+The helper composes:
+
+- `resumeTransferChannel(...)` when a channel is supplied
+- `transferWorkPacket(...)` when ownership must move
+- `raiseCollaborationBlocker(...)`
+- `reviewCollaborationProposal(...)` when a proposal id is supplied
+- `startMessageWatch(...)`
+- `postCollaborationHeartbeat(...)`
+- `getTransferChannelProjection(...)` when available
+
+The helper returns `remediation_ticket_id` or `blocker_id`, plus `missing_surfaces[]` so callers can see any absent governed surface without pretending the ticket was fully established.
+
+### Refactoring Bundle Transfer
+
+Use `transferRefactoringBundle(...)` when one agent needs to package a governed refactoring/remediation bundle and hand it to another agent through the transfer substrate.
+
+```js
+const bundle = await client.transferRefactoringBundle({
+  projectIdentifier: 'project-1',
+  sourceAgent: 'agent-downstream',
+  targetAgent: 'agent-upstream',
+  sourceRef: 'refactor-42',
+  problemStatement: 'Extract the transport orchestration into a shared helper.',
+  affectedFilesOrSymbols: ['src/index.js', 'transferRefactoringBundle'],
+  recommendedAction: 'Create a shared transfer orchestration helper.',
+  acceptanceCriteria: ['bundle received', 'ownership assigned', 'acknowledgement posted'],
+  evidenceRefs: ['commit:abc123'],
+  riskLevel: 'medium',
+  handoffNotes: 'Please review and wire the new helper into the bundle flow.',
+});
+```
+
+The helper composes:
+
+- `resumeProjectWork(...)` or `startWork(...)`
+- `transferWorkPacket(...)`
+- `openTransferChannel(...)` or `resumeTransferChannel(...)`
+- `assignCollaborationOwnership(...)`
+- `postCollaborationProposal(...)`
+- `startMessageWatch(...)`
+- `postCollaborationHeartbeat(...)`
+- `getTransferChannelProjection(...)` when available
+
+The helper returns `missing_surfaces[]` for any absent transfer, ownership, proposal, watch, heartbeat, or projection surface, and it fails closed if no explicit target agent is supplied.
+
 ## Integration Notes
 
 ### Auth Modes
@@ -765,6 +872,17 @@ Engine returns the required gate and next action.
 | `getPortfolioBundle()` | Portfolio bundle. |
 | `getPortfolioClosureReadiness({ projectLimit, includeInactive, includeLogaPortfolioProjection, includeLogaRoadmapProjections })` | Read-only portfolio readiness view that composes bundle, project list, roadmap summaries, active items, and open task counts into a conservative closure-ready flag. |
 
+### Warehouse
+| Method | Description |
+|---|---|
+| `registerModernizationAsset({ projectIdentifier, assetName, assetType, sourceRef, originSystem, businessContext, suspectedValue, knownRisks, relatedProjectId, evidenceRefs, handoffNotes, assignedClassifier, classificationRequired })` | Register a modernization asset intake record when the backend surface exists, attach governed intake evidence or observations when available, and optionally hand off classification to another agent through the transfer substrate. Missing asset-intake or observation surfaces are recorded in `missing_surfaces[]`, and generated markdown projections are treated only as display metadata. |
+| `classifyModernizationAsset({ projectIdentifier, assetId, intakeRecordId, assetType, sourceRef, classificationCategory, domainArea, reusePotential, modernizationNeed, knownRisks, evidenceRefs, recommendedNextStep, classificationConfidence, reviewRequired, assignedReviewer, handoffNotes })` | Classify a registered modernization asset into reusable warehouse categories using caller-supplied evidence only. The helper looks up the registered asset or intake record when that backend surface exists, records missing classification surfaces in `missing_surfaces[]`, and can hand the review to another agent through the transfer substrate without treating generated projections as authority. |
+| `discoverSalvageCandidates({ projectIdentifier, assetId, intakeRecordId, classificationId, sourceRef, classificationCategory, domainArea, reusePotential, modernizationNeed, knownRisks, evidenceRefs, recommendedNextStep, reviewRequired, assignedReviewer, relatedSymbols, relatedQualifiedNames, relatedFilePaths, candidateSearchIntent, candidateSearchQuery, maxCandidates })` | Identify salvage candidates from a classified modernization asset using governed inventory and retrieval surfaces only. The helper records missing code-discovery surfaces in `missing_surfaces[]`, composes symbol and related-code lookup when available, and can hand the candidate review to another agent without inspecting local files or generated projections as authority. |
+| `createModernizationWorkPacket({ projectIdentifier, assetId, intakeRecordId, classificationId, selectedCandidates, candidateIds, sourceRef, packetTitle, problemStatement, recommendedModernization, affectedFilesOrSymbols, acceptanceCriteria, riskLevel, evidenceRefs, wrapperExecutionRequired, handoffNotes, targetAgent, assignedOwner, collaborationRequired, channelId, transferChannelId })` | Convert selected salvage candidates into a governed modernization work packet. The helper prefers governed packet and candidate records when available, falls back to `transferWorkPacket(...)` when the dedicated packet surface is missing, and records any absent packet, candidate, proposal, channel, watch, or heartbeat surfaces in `missing_surfaces[]`. Generated projections remain display metadata only. |
+| `requestModernizationWrapperExecution({ projectIdentifier, modernizationPacketId, wrapperName, wrapperContractRef, sourceRef, executionScope, allowedBlastRadius, requiredEvidence, acceptanceCriteria, riskLevel, targetAgent, handoffNotes, collaborationRequired, channelId, transferChannelId, wrapperExecutionRequired })` | Turn a modernization work packet into a governed wrapper execution request. The helper prefers a dedicated wrapper-request surface when available, falls back to `transferWorkPacket(...)` as the safe governed handoff when that surface is missing, and records missing packet, wrapper-request, channel, ownership, watch, or heartbeat surfaces in `missing_surfaces[]`. Generated projections remain display metadata only. |
+| `getModernizationWrapperEvidence({ projectIdentifier, modernizationPacketId, wrapperExecutionRequestId, wrapperExecutionId, sourceRef, includeOperations, includeFileManifest, includeVerificationSummary, includeProjection })` | Read back wrapper evidence for a modernization packet or wrapper execution request without inventing evidence or treating projections as authority. The helper prefers a governed wrapper-evidence bundle when available, falls back to component reads only when those surfaces exist, and records missing packet, request, evidence, operation-log, manifest, verification, or projection surfaces in `missing_surfaces[]`. |
+| `decideModernizationGate({ projectIdentifier, modernizationPacketId, wrapperExecutionRequestId, wrapperExecutionId, sourceRef, requiredEvidence, acceptanceCriteria, decisionMode, decisionBand, reviewer, reviewRequired, riskLevel, rationale, recordDecision, reviewChannelId, implementationItemId, submittedBy })` | Turn wrapper evidence into a conservative modernization gate recommendation or recorded gate decision. The helper requires complete wrapper evidence before it can recommend a pass, records missing packet, evidence, acceptance-criteria, gate-decision, evidence-link, watch, heartbeat, or projection surfaces in `missing_surfaces[]`, and treats generated projections as display metadata only. |
+
 ### Self-Learning
 | Method | Description |
 |---|---|

package/package.json

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