@aifabrix/builder 2.50.0 → 2.51.1

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

@@ -0,0 +1,500 @@
+/**
+ * Role assistant case runtime runner using dataplane work APIs.
+ *
+ * @fileoverview Execute role-assistant test case input/answers/approvals over work.start/status/respond/continue
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { VERDICT } = require('../lifecycle/product-model');
+const {
+  startWorkIntent,
+  getWorkExecutionStatus,
+  respondWorkExecution,
+  continueWorkExecution,
+  getWorkExecutionResult
+} = require('../api/work.api');
+const { wantsWorkHubPath, runWorkHubCaseLifecycle } = require('./test-runner-workhub');
+const TERMINAL_STATUSES = new Set(['completed', 'stopped']);
+const WAITING_STATUS = 'waiting';
+
+function delayMs(ms) {
+  const wait = Number(ms);
+  if (!Number.isFinite(wait) || wait <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => setTimeout(resolve, wait));
+}
+
+function normalizeToken(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '');
+}
+
+function buildRuntimeId(prefix) {
+  if (typeof crypto.randomUUID === 'function') {
+    return `${prefix}-${crypto.randomUUID()}`;
+  }
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function applyOptionalStringField(payload, value, key) {
+  if (typeof value === 'string' && value.trim()) {
+    payload[key] = value.trim();
+  }
+}
+
+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') {
+    return true;
+  }
+  if (resolveInputMessage(testCase)) {
+    return true;
+  }
+  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,
+    startResponse?.processExecutionId,
+    startResponse?.status?.processExecutionId
+  ];
+  for (const row of candidates) {
+    if (typeof row === 'string' && row.trim()) {
+      return row.trim();
+    }
+  }
+  return '';
+}
+
+function isTerminalStatus(statusValue) {
+  return TERMINAL_STATUSES.has(normalizeToken(statusValue));
+}
+
+function getWaitDescriptor(statusRow) {
+  return statusRow && typeof statusRow.wait === 'object' && statusRow.wait ? statusRow.wait : {};
+}
+
+function collectWaitMatchTokens(wait) {
+  const out = [];
+  const add = (value) => {
+    if (typeof value === 'string' && value.trim()) {
+      out.push(value.trim());
+    }
+  };
+  add(wait.answerType);
+  add(wait.waitReason);
+  add(wait.interactionKind);
+  add(wait.questionKey);
+  add(wait.requestKey);
+  if (wait.objectRef && typeof wait.objectRef === 'object') {
+    add(wait.objectRef.key);
+    add(wait.objectRef.name);
+    add(wait.objectRef.type);
+    add(wait.objectRef.id);
+  }
+  if (wait.safeProjection && typeof wait.safeProjection === 'object') {
+    add(wait.safeProjection.capabilityKey);
+    add(wait.safeProjection.capability);
+    add(wait.safeProjection.key);
+  }
+  return out.map((row) => normalizeToken(row)).filter(Boolean);
+}
+
+function matchesWhenSpec(wait, when = {}) {
+  if (!when || typeof when !== 'object' || Array.isArray(when)) {
+    return true;
+  }
+  const tokens = collectWaitMatchTokens(wait);
+  const includesToken = (value) => {
+    const normalized = normalizeToken(value);
+    if (!normalized) {
+      return true;
+    }
+    return tokens.includes(normalized);
+  };
+  if (!includesToken(when.type)) {
+    return false;
+  }
+  if (!includesToken(when.key)) {
+    return false;
+  }
+  if (!includesToken(when.questionKey)) {
+    return false;
+  }
+  if (!includesToken(when.requestKey)) {
+    return false;
+  }
+  if (!includesToken(when.capability)) {
+    return false;
+  }
+  if (!includesToken(when.interactionKind)) {
+    return false;
+  }
+  return includesToken(when.waitReason);
+}
+
+function findMatchingEntry(entries, usedIndexes, wait) {
+  for (let index = 0; index < entries.length; index += 1) {
+    if (usedIndexes.has(index)) {
+      continue;
+    }
+    const candidate = entries[index];
+    const when = candidate && typeof candidate === 'object' ? candidate.when : null;
+    if (matchesWhenSpec(wait, when)) {
+      return { index, entry: candidate || {} };
+    }
+  }
+  return null;
+}
+
+function normalizeApprovalDecision(value) {
+  const token = normalizeToken(value);
+  if (token === 'approve' || token === 'approved' || token === 'accept') {
+    return 'approved';
+  }
+  if (token === 'reject' || token === 'rejected' || token === 'decline' || token === 'declined') {
+    return 'rejected';
+  }
+  return '';
+}
+
+function resolveAskRespondValue(respond) {
+  if (typeof respond.value !== 'undefined') {
+    return respond.value;
+  }
+  if (typeof respond.message !== 'undefined') {
+    return respond.message;
+  }
+  if (typeof respond.text !== 'undefined') {
+    return respond.text;
+  }
+  return respond;
+}
+
+function applyWaitVersioningFields(payload, wait) {
+  applyOptionalStringField(payload, wait.requestVersion, 'requestVersion');
+  applyOptionalStringField(payload, wait.stateVersionRef, 'stateVersionRef');
+  applyOptionalStringField(payload, wait.requestFingerprint, 'requestFingerprint');
+}
+
+function buildAskRespondPayload(answerEntry, wait) {
+  const respond = answerEntry && typeof answerEntry.respond === 'object' && answerEntry.respond
+    ? answerEntry.respond
+    : {};
+  const payload = {
+    respondIdempotencyKey: buildRuntimeId('ra-answer'),
+    answerType: 'ask',
+    value: resolveAskRespondValue(respond)
+  };
+  applyOptionalStringField(payload, respond.selectedOptionId, 'selectedOptionId');
+  applyOptionalStringField(payload, respond.evidenceRef, 'evidenceRef');
+  if (respond.declined === true) {
+    payload.declined = true;
+  }
+  applyWaitVersioningFields(payload, wait);
+  return payload;
+}
+
+function buildApprovalRespondPayload(approvalEntry, wait) {
+  const decision = normalizeApprovalDecision(
+    approvalEntry?.decision || approvalEntry?.respond?.decision || approvalEntry?.respond?.approvalDecision
+  );
+  if (!decision) {
+    throw new Error('Approval entry in case requires decision "approve" or "reject".');
+  }
+  const payload = {
+    respondIdempotencyKey: buildRuntimeId('ra-approval'),
+    answerType: 'approval',
+    approvalDecision: decision
+  };
+  applyWaitVersioningFields(payload, wait);
+  return payload;
+}
+
+function buildStatusSnapshot(statusRow) {
+  return {
+    processExecutionId: statusRow?.processExecutionId || null,
+    status: statusRow?.status || null,
+    message: statusRow?.message || null,
+    wait: statusRow?.wait || null,
+    correlationId: statusRow?.correlationId || null
+  };
+}
+
+function buildRunnerOptions(options = {}) {
+  const maxStatusPolls = Number(options.maxStatusPolls);
+  const statusPollIntervalMs = Number(options.statusPollIntervalMs);
+  return {
+    maxStatusPolls: Number.isFinite(maxStatusPolls) && maxStatusPolls > 0 ? maxStatusPolls : 20,
+    statusPollIntervalMs:
+      Number.isFinite(statusPollIntervalMs) && statusPollIntervalMs >= 0 ? statusPollIntervalMs : 750
+  };
+}
+
+async function fetchWorkResultSafe(dataplaneUrl, authConfig, processExecutionId, testCase) {
+  const input = resolveInputObject(testCase);
+  const requestedDepth = input.requestedDepth || 'details';
+  const format = input.format || 'json';
+  return getWorkExecutionResult(dataplaneUrl, authConfig, processExecutionId, {
+    requestedDepth,
+    format
+  });
+}
+
+function finalizeWaitingAdvanceStatus(respondResult, continueResult) {
+  const afterRespondStatus = respondResult && typeof respondResult.status === 'object'
+    ? respondResult.status
+    : null;
+  return continueResult && typeof continueResult === 'object'
+    ? continueResult
+    : afterRespondStatus;
+}
+
+async function advanceApprovalWaitingExecution(context, approvals, wait) {
+  const { dataplaneUrl, authConfig, processExecutionId, usedApprovalIndexes } = context;
+  const match = findMatchingEntry(approvals, usedApprovalIndexes, wait);
+  if (!match) {
+    return { status: null, matched: false, interactionType: 'approval' };
+  }
+  usedApprovalIndexes.add(match.index);
+  const payload = buildApprovalRespondPayload(match.entry, wait);
+  const respondResult = await respondWorkExecution(dataplaneUrl, authConfig, processExecutionId, payload);
+  const continueResult = await continueWorkExecution(dataplaneUrl, authConfig, processExecutionId, {});
+  return {
+    status: finalizeWaitingAdvanceStatus(respondResult, continueResult),
+    matched: true,
+    interactionType: 'approval',
+    respondPayload: payload
+  };
+}
+
+async function advanceAskWaitingExecution(context, answers, wait) {
+  const { dataplaneUrl, authConfig, processExecutionId, usedAnswerIndexes } = context;
+  const match = findMatchingEntry(answers, usedAnswerIndexes, wait);
+  if (!match) {
+    return { status: null, matched: false, interactionType: 'ask' };
+  }
+  usedAnswerIndexes.add(match.index);
+  const payload = buildAskRespondPayload(match.entry, wait);
+  const respondResult = await respondWorkExecution(dataplaneUrl, authConfig, processExecutionId, payload);
+  const continueResult = await continueWorkExecution(dataplaneUrl, authConfig, processExecutionId, {});
+  return {
+    status: finalizeWaitingAdvanceStatus(respondResult, continueResult),
+    matched: true,
+    interactionType: 'ask',
+    respondPayload: payload
+  };
+}
+
+async function advanceWaitingExecution(context) {
+  const { wait, testCase } = context;
+  const waitReason = normalizeToken(wait.waitReason || wait.answerType || wait.interactionKind);
+  const approvals = Array.isArray(testCase.approvals) ? testCase.approvals : [];
+  const answers = Array.isArray(testCase.answers) ? testCase.answers : [];
+  if (waitReason === 'approval') {
+    return advanceApprovalWaitingExecution(context, approvals, wait);
+  }
+  return advanceAskWaitingExecution(context, answers, wait);
+}
+
+async function pollCaseExecutionStatus(dataplaneUrl, authConfig, processExecutionId, testCase, options) {
+  const usedAnswerIndexes = new Set();
+  const usedApprovalIndexes = new Set();
+  const timeline = [];
+  const interactions = [];
+  let statusRow = await getWorkExecutionStatus(dataplaneUrl, authConfig, processExecutionId);
+  for (let pollIndex = 0; pollIndex < options.maxStatusPolls; pollIndex += 1) {
+    timeline.push(buildStatusSnapshot(statusRow));
+    if (isTerminalStatus(statusRow?.status)) {
+      break;
+    }
+    if (normalizeToken(statusRow?.status) === WAITING_STATUS) {
+      const wait = getWaitDescriptor(statusRow);
+      const advanced = await advanceWaitingExecution({
+        dataplaneUrl,
+        authConfig,
+        processExecutionId,
+        wait,
+        testCase,
+        usedAnswerIndexes,
+        usedApprovalIndexes
+      });
+      interactions.push({
+        pollIndex,
+        type: advanced.interactionType,
+        waitReason: wait.waitReason || wait.answerType || wait.interactionKind || null,
+        matched: advanced.matched === true,
+        questionKey: wait.questionKey || wait.requestKey || null
+      });
+      if (!advanced.matched || !advanced.status) {
+        break;
+      }
+      statusRow = advanced.status;
+      continue;
+    }
+    await delayMs(options.statusPollIntervalMs);
+    statusRow = await getWorkExecutionStatus(dataplaneUrl, authConfig, processExecutionId);
+  }
+  return { finalStatus: statusRow, timeline, interactions };
+}
+
+async function safeLoadWorkResult(dataplaneUrl, authConfig, processExecutionId, testCase) {
+  try {
+    const workResult = await fetchWorkResultSafe(dataplaneUrl, authConfig, processExecutionId, testCase);
+    return { workResult, workResultError: null };
+  } catch (error) {
+    return { workResult: null, workResultError: error.message || String(error) };
+  }
+}
+
+async function runRoleAssistantCaseLifecycle(roleKey, testCase, runtimeContext, options = {}) {
+  const dataplaneUrl = runtimeContext?.dataplaneUrl;
+  const authConfig = runtimeContext?.authConfig;
+  if (!dataplaneUrl || !authConfig) {
+    throw new Error('Role assistant case runtime requires dataplane auth context.');
+  }
+  const runnerOptions = buildRunnerOptions(options);
+  if (wantsWorkHubPath(testCase)) {
+    return runWorkHubCaseLifecycle(roleKey, testCase, runtimeContext, runnerOptions);
+  }
+  const startPayload = buildStartIntentPayload(roleKey, testCase);
+  const startResponse = await startWorkIntent(dataplaneUrl, authConfig, startPayload);
+  const processExecutionId = extractProcessExecutionId(startResponse);
+  if (!processExecutionId) {
+    throw new Error(
+      'work.start missing processExecutionId; use input.executionPath: workHub for free-text RA cases.'
+    );
+  }
+  const pollState = await pollCaseExecutionStatus(
+    dataplaneUrl,
+    authConfig,
+    processExecutionId,
+    testCase,
+    runnerOptions
+  );
+  const { workResult, workResultError } = await safeLoadWorkResult(
+    dataplaneUrl,
+    authConfig,
+    processExecutionId,
+    testCase
+  );
+  return {
+    roleKey,
+    caseId: testCase.caseId,
+    processExecutionId,
+    startResponse,
+    finalStatus: pollState.finalStatus,
+    timeline: pollState.timeline,
+    interactions: pollState.interactions,
+    workResult,
+    workResultError
+  };
+}
+
+function mergeCaseExecutionIntoLifecycleResult(lifecycleResult, executionResult) {
+  const base = lifecycleResult && typeof lifecycleResult === 'object' ? lifecycleResult : {};
+  return {
+    ...base,
+    status: executionResult?.finalStatus?.status || base.status,
+    wait: executionResult?.finalStatus?.wait || base.wait,
+    processExecutionId: executionResult?.processExecutionId || base.processExecutionId,
+    workResult: executionResult?.workResult || null,
+    task: executionResult?.workResult?.task || null,
+    steps: Array.isArray(executionResult?.workResult?.steps) ? executionResult.workResult.steps : [],
+    workTimeline: executionResult?.timeline || [],
+    workInteractions: executionResult?.interactions || []
+  };
+}
+
+function lifecycleVerdictFromCaseExecution(executionResult, fallbackVerdict) {
+  const statusToken = normalizeToken(executionResult?.finalStatus?.status);
+  if (statusToken === 'completed') {
+    return VERDICT.VERIFIED;
+  }
+  if (statusToken === 'stopped' || statusToken === 'waiting' || statusToken === 'running') {
+    return VERDICT.NOT_VERIFIED;
+  }
+  return fallbackVerdict || VERDICT.FAILED;
+}
+
+module.exports = {
+  isExecutableRoleAssistantCase,
+  buildStartIntentPayload,
+  runRoleAssistantCaseLifecycle,
+  mergeCaseExecutionIntoLifecycleResult,
+  lifecycleVerdictFromCaseExecution
+};

package/lib/schema/application-schema.json

@@ -7,12 +7,12 @@
     "key": "application-schema",
     "name": "Application Configuration Schema",
     "description": "JSON schema for validating AI Fabrix application configuration files",
-    "version": "1.4.0",
+    "version": "1.6.0",
     "type": "schema",
     "category": "infrastructure",
     "author": "AI Fabrix Team",
     "createdAt": "2024-01-01T00:00:00Z",
-    "updatedAt": "2026-04-06T00:00:00Z",
+    "updatedAt": "2026-07-28T00:00:00Z",
     "compatibility": {
       "minVersion": "1.0.0",
       "maxVersion": "2.0.0",
@@ -30,6 +30,22 @@
       "external-datasource.schema.json"
     ],
     "changelog": [
+      {
+        "version": "1.6.0",
+        "date": "2026-07-28T00:00:00Z",
+        "changes": [
+          "Added optional build.deployJob (string): one-shot command run once before any long-running role start (api/worker/beat). Language-agnostic (python, node, pnpm, etc.). Not an array; no phase/once/id fields."
+        ],
+        "breaking": false
+      },
+      {
+        "version": "1.5.0",
+        "date": "2026-07-21T00:00:00Z",
+        "changes": [
+          "Added optional configuration[].category (and conditionalConfiguration item category) for portal UI grouping labels in Miso Configuration tab."
+        ],
+        "breaking": false
+      },
       {
         "version": "1.4.0",
         "date": "2026-04-06T00:00:00Z",
@@ -203,6 +219,12 @@
             "type": "boolean",
             "description": "Whether this configuration is required"
           },
+          "category": {
+            "type": "string",
+            "description": "Optional UI grouping label for portal/deployment wizard Configuration tab",
+            "minLength": 1,
+            "maxLength": 100
+          },
           "portalInput": {
             "type": "object",
             "description": "Portal input configuration for user-provided values",
@@ -315,6 +337,12 @@
                   "type": "boolean",
                   "description": "Whether this configuration is required"
                 },
+                "category": {
+                  "type": "string",
+                  "description": "Optional UI grouping label for portal/deployment wizard Configuration tab",
+                  "minLength": 1,
+                  "maxLength": 100
+                },
                 "portalInput": {
                   "type": "object",
                   "description": "Portal input configuration for user-provided values",
@@ -817,6 +845,12 @@
           "type": "string",
           "description": "Compose/Azure startup command for the beat sidecar (<appKey>-beat) when build.worker is true. Omit or set to empty string to skip the beat role."
         },
+        "deployJob": {
+          "type": "string",
+          "description": "Optional one-shot command run once before any long-running role (imageRun / imageRunWorker / imageRunBeat). Local aifabrix run and remote Deployment execute it once per start/deploy (app-scoped, never once-per-sidecar). Language-agnostic command string (e.g. python -m app.db.migrate upgrade, node dist/migrate.js).",
+          "minLength": 1,
+          "maxLength": 500
+        },
         "scripts": {
           "type": "object",
           "description": "Override CLI script commands (aifabrix test, install, lint, test-e2e, test-integration). When a key is missing, language default is used (TypeScript: pnpm test/install/lint/test:e2e/test:integration, Python: make test/install/lint/test:e2e/test-integration).",

package/lib/schema/deployment-rules.yaml

@@ -124,6 +124,7 @@ externalDataSource:
       - capabilities
       - authority
       - foreignKeys
+      - dimensions
       - execution
       - config
       - openapi