@bpmsoftwaresolutions/ai-engine-client 1.1.21 → 1.1.23

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.21",
+  "version": "1.1.23",
   "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.21';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.20';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -420,6 +420,37 @@ export class AIEngineClient {
     return this._request('/api/work/start', { method: 'POST', body });
   }
 
+  async startClaimedWork({
+    claimName,
+    actorId,
+    intentId,
+    declaredScopeFiles,
+    allowedMutationSurfaces,
+    runtimeSessionId,
+    executionPurpose,
+    successCriteria,
+    mutationAllowed,
+    metadata,
+    ...rest
+  } = {}) {
+    return this._request('/api/governance/claims/start-claimed-work', {
+      method: 'POST',
+      body: {
+        ...rest,
+        claim_name: claimName,
+        actor_id: actorId,
+        intent_id: intentId,
+        declared_scope_files: declaredScopeFiles,
+        allowed_mutation_surfaces: allowedMutationSurfaces,
+        runtime_session_id: runtimeSessionId,
+        execution_purpose: executionPurpose,
+        success_criteria: successCriteria,
+        mutation_allowed: mutationAllowed,
+        metadata,
+      },
+    });
+  }
+
   async claimWorkItem(body = {}) {
     return this._request('/api/governance/claims/claim-work-item', { method: 'POST', body });
   }
@@ -443,6 +474,184 @@ export class AIEngineClient {
     });
   }
 
+  /**
+   * Promote a governance claim from `missing_promoted_surface` to
+   * `promoted_surface_bound` by binding required tool definitions to the
+   * workflow and recording a completed claim signoff.
+   *
+   * @param {object} params
+   * @param {string} params.claimId           - UUID of the claim to unblock.
+   * @param {string} params.workflowId        - UUID of the target workflow.
+   * @param {string} params.contextSessionId  - Oriented context session UUID.
+   * @param {string} params.actorId           - Caller identity for audit trail.
+   * @param {string[]} params.requiredToolKeys - Tool keys to bind.
+   * @param {string} [params.intentId]         - Default: 'code_mutation'.
+   * @param {string} [params.bindingScope]     - Default: 'required'.
+   * @param {string} [params.usageMode]        - Default: 'manual'.
+   * @param {string} [params.operatorScope]
+   * @param {object} [params.allowedArgumentPolicy]
+   * @returns {Promise<object>} Promotion result envelope.
+   */
+  async promoteClaimSurface({
+    claimId,
+    workflowId,
+    contextSessionId,
+    actorId,
+    requiredToolKeys,
+    intentId,
+    bindingScope,
+    usageMode,
+    operatorScope,
+    allowedArgumentPolicy,
+    ...rest
+  } = {}) {
+    if (!claimId) throw new Error('claimId is required.');
+    if (!workflowId) throw new Error('workflowId is required.');
+    if (!contextSessionId) throw new Error('contextSessionId is required.');
+    if (!actorId) throw new Error('actorId is required.');
+    if (!Array.isArray(requiredToolKeys) || requiredToolKeys.length === 0) {
+      throw new Error('requiredToolKeys must be a non-empty array.');
+    }
+    return this._request('/api/governance/claims/promote-surface', {
+      method: 'POST',
+      body: {
+        ...rest,
+        claim_id: claimId,
+        workflow_id: workflowId,
+        context_session_id: contextSessionId,
+        actor_id: actorId,
+        required_tool_keys: requiredToolKeys,
+        intent_id: intentId,
+        binding_scope: bindingScope,
+        usage_mode: usageMode,
+        operator_scope: operatorScope,
+        allowed_argument_policy: allowedArgumentPolicy,
+      },
+    });
+  }
+
+  /**
+   * 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 });
   }