@aifabrix/builder 2.52.0 → 2.53.0

package/lib/role-assistant/test-runner-workhub-helpers.js

@@ -0,0 +1,100 @@
+/**
+ * Shared Work Hub test-runner helpers (ids, delays, path detection).
+ * @fileoverview Pure helpers for role-assistant Work Hub harness
+ */
+
+'use strict';
+
+const TERMINAL_TASK = new Set(['completed', 'failed', 'cancelled', 'canceled']);
+const PLAN_LOST_RE =
+  /work plan not found|plan not found|404|ephemeral|reload|timed out|timeout|network error|econnreset|socket|fetch failed/i;
+const APPROVAL_NOT_PENDING_RE = /approval state is not pending|not pending/i;
+
+function delayMs(ms) {
+  const wait = Number(ms);
+  if (!Number.isFinite(wait) || wait <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => setTimeout(resolve, wait));
+}
+
+function resolveInput(testCase) {
+  const input = testCase && typeof testCase.input === 'object' && testCase.input ? testCase.input : {};
+  return Array.isArray(input) ? {} : input;
+}
+
+function resolveObjective(testCase) {
+  const input = resolveInput(testCase);
+  const candidates = [input.message, input.text, input.prompt, input.objective];
+  for (const row of candidates) {
+    if (typeof row === 'string' && row.trim()) {
+      return row.trim();
+    }
+  }
+  return '';
+}
+
+function wantsWorkHubPath(testCase) {
+  const input = resolveInput(testCase);
+  const pathToken = String(input.executionPath || input.mode || '').trim().toLowerCase();
+  if (pathToken === 'workhub' || pathToken === 'work-hub' || pathToken === 'plan') {
+    return true;
+  }
+  if (pathToken === 'work.start' || pathToken === 'start' || pathToken === 'intent') {
+    return false;
+  }
+  return Boolean(resolveObjective(testCase));
+}
+
+function unwrapId(value) {
+  if (typeof value === 'string' && value.trim()) {
+    return value.trim();
+  }
+  if (value && typeof value === 'object') {
+    const nested = value.id || value.value || value.ref;
+    if (typeof nested === 'string' && nested.trim()) {
+      return nested.trim();
+    }
+  }
+  return '';
+}
+
+function extractPeFromTask(task) {
+  const candidates = [task?.processExecutionId, task?.processExecutionRef];
+  for (const row of candidates) {
+    const id = unwrapId(row);
+    if (id) {
+      return id;
+    }
+  }
+  return '';
+}
+
+function planAlreadyActivated(plan) {
+  const assistant = plan?.recommendedAssistant;
+  if (!assistant || typeof assistant !== 'object' || assistant.isActivated !== true) {
+    return false;
+  }
+  return Boolean(unwrapId(assistant.activationId));
+}
+
+function isPlanLostError(error) {
+  return PLAN_LOST_RE.test(String((error && error.message) || error || ''));
+}
+
+function isApprovalNotPendingError(error) {
+  return APPROVAL_NOT_PENDING_RE.test(String((error && error.message) || error || ''));
+}
+
+module.exports = {
+  TERMINAL_TASK,
+  delayMs,
+  resolveInput,
+  resolveObjective,
+  wantsWorkHubPath,
+  unwrapId,
+  extractPeFromTask,
+  planAlreadyActivated,
+  isPlanLostError,
+  isApprovalNotPendingError
+};

package/lib/role-assistant/test-runner-workhub-soft.js

@@ -0,0 +1,86 @@
+/**
+ * Soft Work Hub outcomes for insufficient-info / clarify-first Intent.
+ * Soft cases may stop before accept when Intent is not Act-ready — that is a
+ * governed fail-closed outcome, not a harness failure.
+ */
+
+'use strict';
+
+function isIntentNotActReadyError(error) {
+  const msg = String((error && error.message) || error || '');
+  return /not Act-ready|intentNotActReady/i.test(msg);
+}
+
+function attachPlanIdToError(error, planId) {
+  if (error && typeof error === 'object' && planId) {
+    error.planId = planId;
+  }
+  return error;
+}
+
+function buildSoftClarifyLifecycleResult(roleKey, testCase, planId, error) {
+  const message = String((error && error.message) || error || 'intentNotActReady');
+  return {
+    roleKey,
+    caseId: testCase.caseId,
+    processExecutionId: null,
+    startResponse: {
+      planId: planId || null,
+      path: 'workHub',
+      softClarifyStop: true
+    },
+    finalStatus: {
+      status: 'stopped',
+      wait: null,
+      reason: 'intentNotActReady'
+    },
+    timeline: [],
+    interactions: [{ type: 'softClarifyStop', message }],
+    workResult: null,
+    workResultError: null
+  };
+}
+
+/**
+ * @param {Function} createActivateAcceptPlan
+ * @param {Object} startArgs
+ * @param {string} startArgs.dataplaneUrl
+ * @param {Object} startArgs.authConfig
+ * @param {Object} startArgs.planBody
+ * @param {string} startArgs.assistantName
+ * @param {Object} [startArgs.options]
+ * @param {Object} softCtx
+ * @param {string} softCtx.roleKey
+ * @param {Object} softCtx.testCase
+ */
+async function startWorkHubOrSoftClarify(createActivateAcceptPlan, startArgs, softCtx) {
+  const { dataplaneUrl, authConfig, planBody, assistantName, options } = startArgs;
+  const { roleKey, testCase } = softCtx;
+  try {
+    return {
+      soft: false,
+      started: await createActivateAcceptPlan(
+        dataplaneUrl,
+        authConfig,
+        planBody,
+        assistantName,
+        options
+      )
+    };
+  } catch (error) {
+    if (testCase?.expected?.soft === true && isIntentNotActReadyError(error)) {
+      return {
+        soft: true,
+        result: buildSoftClarifyLifecycleResult(roleKey, testCase, error.planId, error)
+      };
+    }
+    throw error;
+  }
+}
+
+module.exports = {
+  isIntentNotActReadyError,
+  attachPlanIdToError,
+  buildSoftClarifyLifecycleResult,
+  startWorkHubOrSoftClarify
+};

package/lib/role-assistant/test-runner-workhub.js

@@ -23,87 +23,25 @@ const {
   alreadyResponded,
   buildRespondPayload
 } = require('./test-runner-workhub-answers');
-
-const TERMINAL_TASK = new Set(['completed', 'failed', 'cancelled', 'canceled']);
-const PLAN_LOST_RE =
-  /work plan not found|plan not found|404|ephemeral|reload|timed out|timeout|network error|econnreset|socket|fetch failed/i;
-const APPROVAL_NOT_PENDING_RE = /approval state is not pending|not pending/i;
-
-function delayMs(ms) {
-  const wait = Number(ms);
-  if (!Number.isFinite(wait) || wait <= 0) {
-    return Promise.resolve();
-  }
-  return new Promise((resolve) => setTimeout(resolve, wait));
-}
-
-function resolveInput(testCase) {
-  const input = testCase && typeof testCase.input === 'object' && testCase.input ? testCase.input : {};
-  return Array.isArray(input) ? {} : input;
-}
-
-function resolveObjective(testCase) {
-  const input = resolveInput(testCase);
-  const candidates = [input.message, input.text, input.prompt, input.objective];
-  for (const row of candidates) {
-    if (typeof row === 'string' && row.trim()) {
-      return row.trim();
-    }
-  }
-  return '';
-}
-
-function wantsWorkHubPath(testCase) {
-  const input = resolveInput(testCase);
-  const pathToken = String(input.executionPath || input.mode || '').trim().toLowerCase();
-  if (pathToken === 'workhub' || pathToken === 'work-hub' || pathToken === 'plan') {
-    return true;
-  }
-  if (pathToken === 'work.start' || pathToken === 'start' || pathToken === 'intent') {
-    return false;
-  }
-  return Boolean(resolveObjective(testCase));
-}
-
-function unwrapId(value) {
-  if (typeof value === 'string' && value.trim()) {
-    return value.trim();
-  }
-  if (value && typeof value === 'object') {
-    const nested = value.id || value.value || value.ref;
-    if (typeof nested === 'string' && nested.trim()) {
-      return nested.trim();
-    }
-  }
-  return '';
-}
-
-function extractPeFromTask(task) {
-  const candidates = [task?.processExecutionId, task?.processExecutionRef];
-  for (const row of candidates) {
-    const id = unwrapId(row);
-    if (id) {
-      return id;
-    }
-  }
-  return '';
-}
-
-function planAlreadyActivated(plan) {
-  const assistant = plan?.recommendedAssistant;
-  if (!assistant || typeof assistant !== 'object' || assistant.isActivated !== true) {
-    return false;
-  }
-  return Boolean(unwrapId(assistant.activationId));
-}
-
-function isPlanLostError(error) {
-  return PLAN_LOST_RE.test(String((error && error.message) || error || ''));
-}
-
-function isApprovalNotPendingError(error) {
-  return APPROVAL_NOT_PENDING_RE.test(String((error && error.message) || error || ''));
-}
+const {
+  shouldApplyBidAfterWait,
+  shouldSoftHttpBidApply,
+  applyCaseBidViaBuilderApi,
+  persistCaseOpenApiViaBuilderApi
+} = require('./test-runner-bid-apply');
+const { resolveTargetSystemKey } = require('./test-runner-bid-document');
+const {
+  TERMINAL_TASK,
+  delayMs,
+  resolveInput,
+  resolveObjective,
+  wantsWorkHubPath,
+  unwrapId,
+  extractPeFromTask,
+  planAlreadyActivated,
+  isPlanLostError,
+  isApprovalNotPendingError
+} = require('./test-runner-workhub-helpers');
 
 async function waitDataplaneHealthy(dataplaneUrl, attempts = 12) {
   const base = String(dataplaneUrl || '')
@@ -149,11 +87,18 @@ async function acceptPlanForTask(dataplaneUrl, authConfig, planId) {
 }
 
 async function createActivateAcceptOnce(dataplaneUrl, authConfig, planBody, assistantName) {
+  const {
+    attachPlanIdToError
+  } = require('./test-runner-workhub-soft');
   await waitDataplaneHealthy(dataplaneUrl);
   const plan = await createWorkTaskPlan(dataplaneUrl, authConfig, planBody);
   const planId = await activateIfNeeded(dataplaneUrl, authConfig, plan, assistantName);
-  const taskId = await acceptPlanForTask(dataplaneUrl, authConfig, planId);
-  return { planId, taskId };
+  try {
+    const taskId = await acceptPlanForTask(dataplaneUrl, authConfig, planId);
+    return { planId, taskId };
+  } catch (error) {
+    throw attachPlanIdToError(error, planId);
+  }
 }
 
 async function createActivateAcceptPlan(dataplaneUrl, authConfig, planBody, assistantName, options) {
@@ -189,7 +134,16 @@ function _approveGateDecision(ctx) {
     return 'skip';
   }
   const approvalState = String(ctx.taskRow?.approvalState || '').trim().toLowerCase();
-  if (approvalState && approvalState !== 'pending') {
+  // Treat empty / pending* as still actionable. Stop only after a terminal decision.
+  const terminalDecision = new Set([
+    'approved',
+    'rejected',
+    'cancelled',
+    'canceled',
+    'notrequired',
+    'not_required'
+  ]);
+  if (approvalState && terminalDecision.has(approvalState)) {
     return 'stop';
   }
   if ((Number(ctx.approveAttempts) || 0) >= 8) {
@@ -225,46 +179,133 @@ async function maybeApproveTask(dataplaneUrl, authConfig, taskId, ctx) {
   await _attemptApproveTask(dataplaneUrl, authConfig, taskId, ctx);
 }
 
+function recordSkippedResponse(interactions, peId, fingerprint, wait) {
+  interactions.push({
+    type: 'respond-skipped',
+    processExecutionId: peId,
+    fingerprint,
+    questionKey: wait.questionKey || wait.requestKey || null,
+    objectRefKind: wait.objectRef?.kind || null,
+    reason: 'no-matching-answer-or-synthesis'
+  });
+}
+
+function recordBidEmit(testCase, interactions, peId) {
+  const { loadCaseBidDocument } = require('./test-runner-workhub-answers');
+  const emittedBid = loadCaseBidDocument(testCase);
+  if (!(emittedBid && emittedBid.meta && emittedBid.meta.suiteRunId)) {
+    return;
+  }
+  interactions.push({
+    type: 'bid-emit',
+    processExecutionId: peId,
+    suiteRunId: emittedBid.meta.suiteRunId,
+    definitionId: emittedBid.definitionId,
+    definitionHash: emittedBid.definitionHash
+  });
+}
+
+async function softHttpBidApplyAfterWait(authConfig, testCase, interactions, peId) {
+  try {
+    const applied = await applyCaseBidViaBuilderApi(authConfig, testCase);
+    interactions.push({
+      type: 'bid-apply',
+      processExecutionId: peId,
+      systemKey: applied && applied.systemKey,
+      definitionHash: applied && applied.definitionHash,
+      suiteRunId: applied && applied.suiteRunId,
+      status: applied && applied.status,
+      softHttp: true
+    });
+  } catch (applyErr) {
+    interactions.push({
+      type: 'bid-apply-error',
+      processExecutionId: peId,
+      error: applyErr.message || String(applyErr),
+      softHttp: true
+    });
+  }
+}
+
+async function respondToWaitingExecution(
+  dataplaneUrl,
+  authConfig,
+  peId,
+  testCase,
+  interactions,
+  statusRow
+) {
+  const wait = statusRow.wait && typeof statusRow.wait === 'object' ? statusRow.wait : {};
+  const fingerprint = waitRespondFingerprint(wait);
+  if (alreadyResponded(interactions, fingerprint)) {
+    return;
+  }
+  const payload = buildRespondPayload(
+    peId,
+    wait,
+    testCase,
+    statusRow,
+    interactions,
+    resolveObjective(testCase)
+  );
+  if (!payload) {
+    recordSkippedResponse(interactions, peId, fingerprint, wait);
+    return;
+  }
+  // Stage suite OpenAPI into workspace before CIP apply (517.2 layout).
+  // Product path: DE admits persistsuppliedopenapi; this is lab debt until then.
+  if (shouldApplyBidAfterWait(testCase, wait)) {
+    const systemKey = resolveTargetSystemKey(testCase);
+    if (systemKey) {
+      await persistCaseOpenApiViaBuilderApi(authConfig, testCase, systemKey);
+    }
+  }
+  await respondWorkExecution(dataplaneUrl, authConfig, peId, payload);
+  await continueWorkExecution(dataplaneUrl, authConfig, peId, {});
+  interactions.push({ type: 'respond', processExecutionId: peId, fingerprint });
+  if (shouldApplyBidAfterWait(testCase, wait)) {
+    recordBidEmit(testCase, interactions, peId);
+  }
+  // Soft HTTP apply is lab debt only. Hard cases (expected.soft !== true) rely on
+  // DE → capability.execute(template.applyintegrationdefinition) after continue.
+  if (shouldSoftHttpBidApply(testCase, wait)) {
+    await softHttpBidApplyAfterWait(authConfig, testCase, interactions, peId);
+  }
+}
+
 async function maybeRespondWaiting(dataplaneUrl, authConfig, taskRow, testCase, interactions) {
   const peId = extractPeFromTask(taskRow);
   if (!peId) {
     return;
   }
   try {
+    testCase._activeProcessExecutionId = peId;
     const statusRow = await getWorkExecutionStatus(dataplaneUrl, authConfig, peId);
     if (String(statusRow?.status || '').toLowerCase() !== 'waiting') {
       return;
     }
-    const wait = statusRow.wait && typeof statusRow.wait === 'object' ? statusRow.wait : {};
-    const fingerprint = waitRespondFingerprint(wait);
-    if (alreadyResponded(interactions, fingerprint)) {
-      return;
-    }
-    const payload = buildRespondPayload(
+    await respondToWaitingExecution(
+      dataplaneUrl,
+      authConfig,
       peId,
-      wait,
       testCase,
-      statusRow,
       interactions,
-      resolveObjective(testCase)
+      statusRow
     );
-    if (!payload) {
-      return;
-    }
-    await respondWorkExecution(dataplaneUrl, authConfig, peId, payload);
-    await continueWorkExecution(dataplaneUrl, authConfig, peId, {});
-    interactions.push({ type: 'respond', processExecutionId: peId, fingerprint });
   } catch (_err) {
     // Soft: continue polling task.
   }
 }
 
-function assertTerminalWorkHubTask(last, taskId, timeoutMs) {
+function assertTerminalWorkHubTask(last, taskId, timeoutMs, options = {}) {
   if (!last) {
     throw new Error(`Work Hub task ${taskId} produced no status rows.`);
   }
   const finalStatusToken = String(last?.status || last?.taskStatus || '').trim().toLowerCase();
   if (!TERMINAL_TASK.has(finalStatusToken)) {
+    if (options.soft === true) {
+      return last;
+    }
     throw new Error(
       `Work Hub task ${taskId} did not reach a terminal status within ${timeoutMs}ms (last=${finalStatusToken || 'unknown'}).`
     );
@@ -275,6 +316,7 @@ function assertTerminalWorkHubTask(last, taskId, timeoutMs) {
 async function pollWorkHubTask(dataplaneUrl, authConfig, taskId, testCase, options) {
   const timeoutMs = Number(options.pollTimeoutMs) || 180000;
   const intervalMs = Number(options.pollIntervalMs) || 3000;
+  const soft = testCase?.expected?.soft === true;
   const started = Date.now();
   let last = null;
   const timeline = [];
@@ -301,7 +343,7 @@ async function pollWorkHubTask(dataplaneUrl, authConfig, taskId, testCase, optio
   }
 
   return {
-    finalTask: assertTerminalWorkHubTask(last, taskId, timeoutMs),
+    finalTask: assertTerminalWorkHubTask(last, taskId, timeoutMs, { soft }),
     timeline,
     interactions: ctx.interactions
   };
@@ -347,6 +389,7 @@ function buildWorkHubLifecycleResult(roleKey, testCase, started, pollState, peBu
 }
 
 async function runWorkHubCaseLifecycle(roleKey, testCase, runtimeContext, options = {}) {
+  const { startWorkHubOrSoftClarify } = require('./test-runner-workhub-soft');
   const dataplaneUrl = runtimeContext?.dataplaneUrl;
   const authConfig = runtimeContext?.authConfig;
   const objective = resolveObjective(testCase);
@@ -363,13 +406,15 @@ async function runWorkHubCaseLifecycle(roleKey, testCase, runtimeContext, option
     objective,
     digitalWorkerKey: String(input.digitalWorkerKey || roleKey).trim()
   };
-  const started = await createActivateAcceptPlan(
-    dataplaneUrl,
-    authConfig,
-    planBody,
-    assistantName,
-    options
+  const gate = await startWorkHubOrSoftClarify(
+    createActivateAcceptPlan,
+    { dataplaneUrl, authConfig, planBody, assistantName, options },
+    { roleKey, testCase }
   );
+  if (gate.soft) {
+    return gate.result;
+  }
+  const started = gate.started;
   const pollState = await pollWorkHubTask(
     dataplaneUrl,
     authConfig,

package/lib/role-assistant/test-runner.js

@@ -18,6 +18,11 @@ const {
   getWorkExecutionResult
 } = require('../api/work.api');
 const { wantsWorkHubPath, runWorkHubCaseLifecycle } = require('./test-runner-workhub');
+const {
+  buildStartIntentPayload,
+  resolveInputObject,
+  resolveInputMessage
+} = require('./test-runner-start-payload');
 const TERMINAL_STATUSES = new Set(['completed', 'stopped']);
 const WAITING_STATUS = 'waiting';
 
@@ -52,22 +57,6 @@ function applyOptionalStringField(payload, value, key) {
   }
 }
 
-function resolveInputObject(testCase) {
-  const input = testCase && typeof testCase.input === 'object' && testCase.input ? testCase.input : {};
-  return Array.isArray(input) ? {} : input;
-}
-
-function resolveInputMessage(testCase) {
-  const input = resolveInputObject(testCase);
-  const candidates = [input.message, input.text, input.prompt];
-  for (const row of candidates) {
-    if (typeof row === 'string' && row.trim()) {
-      return row.trim();
-    }
-  }
-  return '';
-}
-
 function isExecutableRoleAssistantCase(testCase) {
   const input = resolveInputObject(testCase);
   if (typeof input.content !== 'undefined') {
@@ -79,53 +68,6 @@ function isExecutableRoleAssistantCase(testCase) {
   return false;
 }
 
-function buildStartPayloadSourceMetadata(roleKey, testCase, input) {
-  return {
-    roleKey,
-    caseId: testCase.caseId,
-    runner: 'aifabrix-role-assistant-test',
-    ...(input.sourceMetadata && typeof input.sourceMetadata === 'object' ? input.sourceMetadata : {})
-  };
-}
-
-function applyStartPayloadOptionalFields(payload, input) {
-  const mappedFields = [
-    ['activationId', 'activationId'],
-    ['workerTaskId', 'workerTaskId'],
-    ['principalRef', 'principalRef'],
-    ['businessRoleRef', 'businessRoleRef']
-  ];
-  for (const [inputKey, payloadKey] of mappedFields) {
-    applyOptionalStringField(payload, input[inputKey], payloadKey);
-  }
-}
-
-function buildStartIntentPayload(roleKey, testCase) {
-  const input = resolveInputObject(testCase);
-  const message = resolveInputMessage(testCase);
-  const hasContent = typeof input.content !== 'undefined';
-  if (!hasContent && !message) {
-    throw new Error(
-      `Role assistant test case "${testCase.caseId}" is missing input.message or input.content for runtime execution.`
-    );
-  }
-  const payload = {
-    submissionId: String(input.submissionId || buildRuntimeId(`ra-${roleKey}`)),
-    content: hasContent ? input.content : message,
-    comModelRef: String(input.comModelRef || 'aifabrix.com/intent/default'),
-    comModelVersion: String(input.comModelVersion || '1.0'),
-    comVocabulary: Array.isArray(input.comVocabulary) && input.comVocabulary.length > 0
-      ? input.comVocabulary.map((row) => String(row))
-      : ['objective', 'entity', 'action'],
-    sourceType: String(input.sourceType || 'api'),
-    sourceLanguage: String(input.sourceLanguage || 'en'),
-    responseLanguage: String(input.responseLanguage || input.sourceLanguage || 'en'),
-    sourceMetadata: buildStartPayloadSourceMetadata(roleKey, testCase, input)
-  };
-  applyStartPayloadOptionalFields(payload, input);
-  return payload;
-}
-
 function extractProcessExecutionId(startResponse) {
   const candidates = [
     startResponse?.intent?.processExecutionId,