@bpmsoftwaresolutions/ai-engine-client 1.1.87 → 1.1.89

package/src/domains/work-start.js

@@ -0,0 +1,192 @@
+import { cleanList, cleanText, isPlainObject } from '../utils/text.js';
+import { normalizeMetadataTaskBinding, normalizeTaskBindingPolicy } from '../utils/task-binding.js';
+import { contextSessionIdFromInput } from './context-sessions.js';
+
+function isActiveBinding(binding) {
+  return binding !== null && typeof binding === 'object' && !Array.isArray(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 (reminder === null || typeof reminder !== 'object' || Array.isArray(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;
+}
+
+export function createWorkStartDomain(client) {
+  return {
+    startWork: (body = {}) => client._request('/api/work/start', { method: 'POST', body }),
+    startClaimedWork: ({
+      claimName,
+      actorId,
+      intentId,
+      declaredScopeFiles,
+      allowedMutationSurfaces,
+      runtimeSessionId,
+      executionPurpose,
+      successCriteria,
+      mutationAllowed,
+      metadata,
+      ...rest
+    } = {}) => client._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: normalizeMetadataTaskBinding(metadata),
+      },
+    }),
+    claimWorkItem: (body = {}) => {
+      const normalizedBody = body !== null && typeof body === 'object' && !Array.isArray(body)
+        ? {
+            ...body,
+            ...(body.task_binding !== null && typeof body.task_binding === 'object' && !Array.isArray(body.task_binding)
+              ? { task_binding: normalizeTaskBindingPolicy(body.task_binding) }
+              : {}),
+            metadata: normalizeMetadataTaskBinding(body.metadata),
+          }
+        : body;
+      return client._request('/api/governance/claims/claim-work-item', { method: 'POST', body: normalizedBody });
+    },
+    bindClaimedWorkItem: async ({
+      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 client.getWorkflowToolRegistry({
+          workflowId: normalizedWorkflowId,
+          workflowSlug: normalizedWorkflowSlug,
+        });
+        normalizedRequiredToolKeys = activeToolKeysFromRegistry(workflowRegistry);
+      }
+
+      const lockClaimResult = await client.contextSessions.lockContextSessionClaim(normalizedContextSessionId);
+      const lockedContextSession = lockClaimResult?.context_session || lockClaimResult;
+      const lockedContextSessionId = contextSessionIdFromInput(lockedContextSession) || normalizedContextSessionId;
+
+      const claimWorkItemResult = await client.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 client.signoffClaim(resolvedClaimId, {
+            acknowledged_reminders: reminders,
+            intent_confirmation: cleanText(intentConfirmation) || 'I confirm this governed execution intent and scope.',
+            actor_signature: cleanText(actorSignature) || cleanText(actorId) || client.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
+        ),
+      };
+    },
+  };
+}