@bpmsoftwaresolutions/ai-engine-client 1.1.16 → 1.1.18

package/package.json

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

package/src/index.js

@@ -1,4 +1,18 @@
 const DEFAULT_TIMEOUT_MS = 30000;
+export const AI_ENGINE_CLIENT_VERSION = '1.1.18';
+export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
+  'executeVerifiedMutation',
+  'post_mutation_verification',
+  'acceptance_check_read',
+  'artifact_manifest_read',
+  'decision_packet_read',
+  'claim_signoff',
+];
+export const AI_ENGINE_CLIENT_CAPABILITIES = [
+  ...GOVERNED_MUTATION_REQUIRED_CAPABILITIES,
+  'execution_eligibility_read',
+  'workflow_resume_context_read',
+];
 
 export const LOGA_CONTRACT = 'ai-engine-ui/v1';
 export const LOGA_INTERACTION_CONTRACT = 'loga-choreography/v1';
@@ -124,6 +138,13 @@ function buildVerificationError(message, details = {}) {
   return error;
 }
 
+function buildEligibilityError(message, details = {}) {
+  const error = new Error(message);
+  error.code = 'EXECUTION_ELIGIBILITY_FAILED';
+  error.details = details;
+  return error;
+}
+
 export class AIEngineClient {
   constructor({ baseUrl, accessToken, tokenProvider, apiKey, clientId, actorId, fetchImpl, timeoutMs } = {}) {
     if (!baseUrl) throw new Error('baseUrl is required.');
@@ -135,6 +156,8 @@ export class AIEngineClient {
     this.actorId = actorId || 'sdk:npm-ai-engine-client';
     this.fetchImpl = fetchImpl || globalThis.fetch;
     this.timeoutMs = timeoutMs || DEFAULT_TIMEOUT_MS;
+    this.clientVersion = AI_ENGINE_CLIENT_VERSION;
+    this.clientCapabilities = [...AI_ENGINE_CLIENT_CAPABILITIES];
     if (typeof this.fetchImpl !== 'function') {
       throw new Error('A fetch implementation is required. Use Node 18+ or supply fetchImpl.');
     }
@@ -399,6 +422,17 @@ export class AIEngineClient {
     return this._request('/api/governance/claims/claim-work-item', { method: 'POST', body });
   }
 
+  async getExecutionEligibility(body = {}) {
+    return this._request('/api/governance/execution-eligibility', {
+      method: 'POST',
+      body: {
+        required_capabilities: GOVERNED_MUTATION_REQUIRED_CAPABILITIES,
+        verification_required: true,
+        ...body,
+      },
+    });
+  }
+
   async signoffClaim(claimId, body = {}) {
     if (!claimId) throw new Error('claimId is required.');
     return this._request(`/api/governance/claims/${encodeURIComponent(claimId)}/signoff`, {
@@ -1164,6 +1198,12 @@ export class AIEngineClient {
   }
 
   async updateImplementationItemStatus(implementationItemId, body) {
+    await this._assertExecutionEligibility({
+      ...(body || {}),
+      claimed_item_id: body?.claimed_item_id || implementationItemId,
+      requested_mutation_surface: body?.requested_mutation_surface || 'implementation_packet_item',
+      verification_required: true,
+    });
     const result = await this._request(`/api/governed-implementation/items/${implementationItemId}/status`, {
       method: 'PATCH', body,
     });
@@ -1217,6 +1257,12 @@ export class AIEngineClient {
   }
 
   async updateAcceptanceCheckStatus(implementationItemId, acceptanceCheckId, body) {
+    await this._assertExecutionEligibility({
+      ...(body || {}),
+      claimed_item_id: body?.claimed_item_id || implementationItemId,
+      requested_mutation_surface: body?.requested_mutation_surface || 'implementation_acceptance_check',
+      verification_required: true,
+    });
     return this._request(
       `/api/governed-implementation/items/${implementationItemId}/acceptance-checks/${acceptanceCheckId}/status`,
       { method: 'PATCH', body }
@@ -2035,6 +2081,8 @@ export class AIEngineClient {
     const resolvedHeaders = {
       accept: accept || 'application/json',
       'x-actor-id': this.actorId,
+      'x-ai-engine-client-version': this.clientVersion,
+      'x-ai-engine-client-capabilities': this.clientCapabilities.join(','),
       ...(isJsonBody(body) ? { 'content-type': 'application/json' } : {}),
       ...(token ? { authorization: `Bearer ${token}` } : {}),
       ...(!token && this.clientId ? { 'x-client-id': this.clientId } : {}),
@@ -2047,6 +2095,26 @@ export class AIEngineClient {
     return resolvedHeaders;
   }
 
+  async _assertExecutionEligibility(body = {}) {
+    const eligibility = await this.getExecutionEligibility(body);
+    if (eligibility?.execution_eligible && eligibility?.mutation_allowed) {
+      return eligibility;
+    }
+    const remediation = cleanText(eligibility?.remediation_command);
+    const verification = cleanText(eligibility?.verification_command);
+    throw buildEligibilityError(
+      [
+        `Execution eligibility gate blocked mutation${cleanText(body?.requested_mutation_surface) ? ` on ${cleanText(body.requested_mutation_surface)}` : ''}.`,
+        remediation ? `Fix: ${remediation}` : null,
+        verification ? `Then verify: ${verification}` : null,
+      ].filter(Boolean).join(' '),
+      {
+        required_gate: eligibility?.required_gate || 'execution_eligibility.required_gate',
+        execution_eligibility: eligibility ?? null,
+      },
+    );
+  }
+
   async _request(path, { method = 'GET', query, headers, body } = {}) {
     const url = appendQuery(`${this.baseUrl}${path}`, query);
     const controller = new AbortController();