@bpmsoftwaresolutions/ai-engine-client 1.1.29 → 1.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.29",
+  "version": "1.1.30",
   "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.29';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.30';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -113,10 +113,60 @@ function cleanText(value) {
   return text || null;
 }
 
+function cleanList(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => cleanText(item)).filter(Boolean);
+}
+
 function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function isActiveBinding(binding) {
+  return isPlainObject(binding) && (
+    binding.is_active === true ||
+    binding.is_active === 1 ||
+    binding.is_active === 'true' ||
+    binding.is_active === 'True'
+  );
+}
+
+function activeToolKeysFromRegistry(registry) {
+  const bindings = Array.isArray(registry?.bindings) ? registry.bindings : [];
+  const seen = new Set();
+  const keys = [];
+  for (const binding of bindings) {
+    if (!isActiveBinding(binding)) continue;
+    const key = cleanText(binding.tool_key);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    keys.push(key);
+  }
+  return keys;
+}
+
+function reminderTokens(reminders) {
+  const tokens = [];
+  for (const reminder of Array.isArray(reminders) ? reminders : []) {
+    if (!isPlainObject(reminder)) continue;
+    for (const value of [reminder.reminder_key, reminder.reminder_id]) {
+      const token = cleanText(value);
+      if (token && !tokens.includes(token)) tokens.push(token);
+    }
+  }
+  return tokens;
+}
+
+function contextSessionIdFromInput(input) {
+  if (isPlainObject(input)) {
+    return cleanText(input.contextSessionId)
+      || cleanText(input.context_session_id)
+      || cleanText(input.context_session?.context_session_id)
+      || cleanText(input.claim?.context_session_id);
+  }
+  return cleanText(input);
+}
+
 function matchesExpectedState(actual, expected) {
   if (typeof expected === 'function') {
     throw new Error('matchesExpectedState does not support function expectations.');
@@ -456,6 +506,115 @@ export class AIEngineClient {
     return this._request('/api/governance/claims/claim-work-item', { method: 'POST', body });
   }
 
+  async bindClaimedWorkItem({
+    claimId,
+    contextSessionId,
+    workflowRunId,
+    agentSessionId,
+    claimedItemId,
+    claimedItemKey,
+    claimName,
+    actorId,
+    workflowId,
+    workflowSlug,
+    requiredToolKeys,
+    declaredScopeFiles,
+    allowedMutationSurfaces,
+    successCriteria,
+    acknowledgedReminders,
+    intentConfirmation,
+    actorSignature,
+    autoSignoff = true,
+    metadata,
+  } = {}) {
+    const normalizedContextSessionId = contextSessionIdFromInput({
+      contextSessionId,
+      context_session_id: contextSessionId,
+      claim: { context_session_id: contextSessionId },
+    });
+    const normalizedClaimId = cleanText(claimId);
+    const normalizedWorkflowRunId = cleanText(workflowRunId);
+    const normalizedAgentSessionId = cleanText(agentSessionId);
+    const normalizedClaimedItemId = cleanText(claimedItemId);
+    const normalizedClaimedItemKey = cleanText(claimedItemKey);
+    const normalizedClaimedItemRef = normalizedClaimedItemId || normalizedClaimedItemKey;
+    if (!normalizedContextSessionId) throw new Error('contextSessionId is required.');
+    if (!normalizedWorkflowRunId) throw new Error('workflowRunId is required.');
+    if (!normalizedAgentSessionId) throw new Error('agentSessionId is required.');
+    if (!normalizedClaimedItemRef) throw new Error('claimedItemId or claimedItemKey is required.');
+
+    const normalizedWorkflowId = cleanText(workflowId);
+    const normalizedWorkflowSlug = cleanText(workflowSlug);
+    let normalizedRequiredToolKeys = cleanList(requiredToolKeys);
+    let workflowRegistry = null;
+    if (normalizedRequiredToolKeys.length === 0 && (normalizedWorkflowId || normalizedWorkflowSlug)) {
+      workflowRegistry = await this.getWorkflowToolRegistry({
+        workflowId: normalizedWorkflowId,
+        workflowSlug: normalizedWorkflowSlug,
+      });
+      normalizedRequiredToolKeys = activeToolKeysFromRegistry(workflowRegistry);
+    }
+
+    const lockClaimResult = await this.lockContextSessionClaim(normalizedContextSessionId);
+    const lockedContextSession = lockClaimResult?.context_session || lockClaimResult;
+    const lockedContextSessionId = contextSessionIdFromInput(lockedContextSession) || normalizedContextSessionId;
+
+    const claimWorkItemResult = await this.claimWorkItem({
+      context_session_id: lockedContextSessionId,
+      workflow_run_id: normalizedWorkflowRunId,
+      agent_session_id: normalizedAgentSessionId,
+      claimed_item_id: normalizedClaimedItemId,
+      claimed_item_key: normalizedClaimedItemKey,
+      claim_name: claimName,
+      actor_id: actorId,
+      workflow_id: normalizedWorkflowId,
+      workflow_slug: normalizedWorkflowSlug,
+      required_tool_keys: normalizedRequiredToolKeys,
+      declared_scope_files: cleanList(declaredScopeFiles).length > 0
+        ? cleanList(declaredScopeFiles)
+        : [normalizedClaimedItemRef],
+      allowed_mutation_surfaces: cleanList(allowedMutationSurfaces).length > 0
+        ? cleanList(allowedMutationSurfaces)
+        : ['project_roadmap_task'],
+      success_criteria: successCriteria,
+      metadata,
+    });
+
+    let signedClaim = null;
+    const resolvedClaimId = cleanText(claimWorkItemResult?.claim_id) || normalizedClaimId;
+    if (autoSignoff && resolvedClaimId) {
+      const claimEnvelope = isPlainObject(claimWorkItemResult?.claim) ? claimWorkItemResult.claim : claimWorkItemResult;
+      const reminders = cleanList(acknowledgedReminders).length > 0
+        ? cleanList(acknowledgedReminders)
+        : reminderTokens(claimEnvelope?.required_reminders);
+      if (reminders.length > 0) {
+        signedClaim = await this.signoffClaim(resolvedClaimId, {
+          acknowledged_reminders: reminders,
+          intent_confirmation: cleanText(intentConfirmation) || 'I confirm this governed execution intent and scope.',
+          actor_signature: cleanText(actorSignature) || cleanText(actorId) || this.actorId,
+        });
+      }
+    }
+
+    return {
+      claim_id: resolvedClaimId,
+      context_session_id: lockedContextSessionId,
+      workflow_run_id: normalizedWorkflowRunId,
+      agent_session_id: normalizedAgentSessionId,
+      required_tool_keys: normalizedRequiredToolKeys,
+      workflow_registry: workflowRegistry,
+      lock_claim_result: lockClaimResult,
+      claim_work_item_result: claimWorkItemResult,
+      signed_claim: signedClaim,
+      approved_tool_keys: cleanList(
+        signedClaim?.approved_tool_keys ||
+        signedClaim?.claim?.approved_tool_keys ||
+        claimWorkItemResult?.approved_tool_keys ||
+        claimWorkItemResult?.claim?.approved_tool_keys
+      ),
+    };
+  }
+
   async getClaim(claimId) {
     if (!claimId) throw new Error('claimId is required.');
     return this._request(`/api/governance/claims/${encodeURIComponent(claimId)}`);
@@ -2348,7 +2507,9 @@ export class AIEngineClient {
     });
   }
 
-  async lockContextSessionClaim(contextSessionId) {
+  async lockContextSessionClaim(input) {
+    const contextSessionId = contextSessionIdFromInput(input);
+    if (!contextSessionId) throw new Error('contextSessionId is required.');
     return this._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/lock-claim`, {
       method: 'POST',
     });