@bpmsoftwaresolutions/ai-engine-client 1.1.22 → 1.1.24

package/README.md

@@ -56,6 +56,15 @@ const startup = await client.startSessionGovernance({
   allowed_mutation_surfaces: ['src/', 'scripts/'],
 });
 
+const claimed = await client.startClaimedWork({
+  claimName: 'spring-boot-gateway-charter-commit',
+  actorId: 'operator:sid',
+  intentId: 'code_mutation',
+  declaredScopeFiles: ['scripts/run_charter.py'],
+  allowedMutationSurfaces: ['project_roadmap_task'],
+  executionPurpose: 'Commit the Spring Boot charter work through a governed claim.',
+});
+
 const persistedTurn = await client.persistAssistantTurn({
   project_id: charter.project_id,
   session_key: startup.session_key,
@@ -90,6 +99,30 @@ That means this package wraps both operator/governed routes and selected externa
 
 If your deployment enforces bearer auth on operator routes, API-key-only construction will not work for those methods.
 
+### Governed Claim Startup
+
+Use `startClaimedWork()` when you want the engine to open the oriented context session, create the session-governance state, declare scope, and return the active claim envelope through one promoted surface.
+
+```js
+const claimed = await client.startClaimedWork({
+  claimName: 'spring-boot-gateway-charter-commit',
+  actorId: 'operator:sid',
+  intentId: 'code_mutation',
+  declaredScopeFiles: [
+    'scripts/run_charter.py',
+    'src/contracts/charters/spring-boot-governed-execution-gateway.charter.json',
+  ],
+  allowedMutationSurfaces: ['project_roadmap_task'],
+  runtimeSessionId: 'codex:main:charter-work',
+  executionPurpose: 'Persist the charter-runner fix and Spring Boot charter packet.',
+  successCriteria: 'Claim is active and scoped to the intended mutation surface.',
+});
+
+console.log(claimed.claim_id, claimed.context_session_id);
+```
+
+This complements the lower-level flow exposed by `openContextSession()`, `acknowledgeReminder()`, `completeOrientation()`, `lockContextSessionClaim()`, `claimWorkItem()`, and `signoffClaim()`.
+
 ### Text and Binary Downloads
 
 Some methods do not return plain JSON:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.22",
+  "version": "1.1.24",
   "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.20';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.24';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -530,6 +530,128 @@ export class AIEngineClient {
     });
   }
 
+  /**
+   * Bootstrap/admin surface for creating a governed workflow-tool-binding
+   * approval lane request. This call cannot approve or execute bindings.
+   *
+   * @param {object} params
+   * @param {string} params.operatorActorType
+   * @param {string} params.requesterActor
+   * @param {string[]} params.requestedToolKeys
+   * @param {string} params.blockedReason
+   * @param {string} params.rollbackPlan
+   * @param {string} [params.requesterActorType]
+   * @param {string} [params.operatorActorId]
+   * @param {string} [params.targetWorkflowId]
+   * @param {string} [params.targetWorkflowRunId]
+   * @param {string[]} [params.relatedGapRecordIds]
+   * @param {string} [params.requestedBindingScope]
+   * @param {string} [params.riskClassification]
+   * @param {object} [params.metadata]
+   * @returns {Promise<object>}
+   */
+  async createWorkflowToolBindingApprovalLane({
+    operatorActorType,
+    requesterActor,
+    requestedToolKeys,
+    blockedReason,
+    rollbackPlan,
+    requesterActorType,
+    operatorActorId,
+    targetWorkflowId,
+    targetWorkflowRunId,
+    relatedGapRecordIds,
+    requestedBindingScope,
+    riskClassification,
+    metadata,
+    ...rest
+  } = {}) {
+    if (!operatorActorType) throw new Error('operatorActorType is required.');
+    if (!requesterActor) throw new Error('requesterActor is required.');
+    if (!Array.isArray(requestedToolKeys) || requestedToolKeys.length === 0) {
+      throw new Error('requestedToolKeys must be a non-empty array.');
+    }
+    if (!blockedReason) throw new Error('blockedReason is required.');
+    if (!rollbackPlan) throw new Error('rollbackPlan is required.');
+    return this._request('/api/governance/bootstrap/workflow-tool-binding-approval/create', {
+      method: 'POST',
+      body: {
+        ...rest,
+        operator_actor_type: operatorActorType,
+        requester_actor: requesterActor,
+        requested_tool_keys: requestedToolKeys,
+        blocked_reason: blockedReason,
+        rollback_plan: rollbackPlan,
+        requester_actor_type: requesterActorType,
+        operator_actor_id: operatorActorId,
+        target_workflow_id: targetWorkflowId,
+        target_workflow_run_id: targetWorkflowRunId,
+        related_gap_record_ids: relatedGapRecordIds,
+        requested_binding_scope: requestedBindingScope,
+        risk_classification: riskClassification,
+        metadata,
+      },
+    });
+  }
+
+  async recordWorkflowToolBindingApprovalDecision(approvalRequestId, {
+    operatorActorType,
+    decision,
+    operatorActorId,
+    decisionNotes,
+    decisionConditions,
+    ...rest
+  } = {}) {
+    if (!approvalRequestId) throw new Error('approvalRequestId is required.');
+    if (!operatorActorType) throw new Error('operatorActorType is required.');
+    if (!decision) throw new Error('decision is required.');
+    return this._request(`/api/governance/bootstrap/workflow-tool-binding-approval/${encodeURIComponent(approvalRequestId)}/approval-decision`, {
+      method: 'POST',
+      body: {
+        ...rest,
+        operator_actor_type: operatorActorType,
+        operator_actor_id: operatorActorId,
+        decision,
+        decision_notes: decisionNotes,
+        decision_conditions: decisionConditions,
+      },
+    });
+  }
+
+  async executeWorkflowToolBindingApprovalBinding(approvalRequestId, {
+    operatorActorType,
+    operatorActorId,
+    ...rest
+  } = {}) {
+    if (!approvalRequestId) throw new Error('approvalRequestId is required.');
+    if (!operatorActorType) throw new Error('operatorActorType is required.');
+    return this._request(`/api/governance/bootstrap/workflow-tool-binding-approval/${encodeURIComponent(approvalRequestId)}/binding-execution`, {
+      method: 'POST',
+      body: {
+        ...rest,
+        operator_actor_type: operatorActorType,
+        operator_actor_id: operatorActorId,
+      },
+    });
+  }
+
+  async revalidateWorkflowToolBindingStartup(approvalRequestId, {
+    operatorActorType,
+    operatorActorId,
+    ...rest
+  } = {}) {
+    if (!approvalRequestId) throw new Error('approvalRequestId is required.');
+    if (!operatorActorType) throw new Error('operatorActorType is required.');
+    return this._request(`/api/governance/bootstrap/workflow-tool-binding-approval/${encodeURIComponent(approvalRequestId)}/startup-revalidation`, {
+      method: 'POST',
+      body: {
+        ...rest,
+        operator_actor_type: operatorActorType,
+        operator_actor_id: operatorActorId,
+      },
+    });
+  }
+
   async completeTurn(body = {}) {
     return this._request('/api/turns/complete', { method: 'POST', body });
   }