@aifabrix/builder 2.54.1 → 2.55.2

package/lib/role-assistant/knowledge-sync-settings-push.js

@@ -0,0 +1,172 @@
+/**
+ * Push role-assistant.yaml knowledge/debug/runtime settings to Assistants.
+ *
+ * @fileoverview Map local Role Assistant settings onto dataplane Assistants PATCH
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { updateAssistantSettings } = require('../api/assistants.api');
+const {
+  readRoleAssistantSettings,
+  resolveDocumentStorageKeyFromRoleAssistantSettings,
+  resolveRoleAssistantEnvironmentSettings
+} = require('./settings');
+
+function resolveRoleAssistantSettingsEnvKey(environment) {
+  const token = String(environment || '').trim().toLowerCase();
+  return token === 'dev' || token === 'tst' || token === 'pro' ? token : 'dev';
+}
+
+/**
+ * Map role-assistant.yaml debug.* → Assistants settings PATCH fields.
+ * includePromptTrace → fullDebugEnabled (LLM prompt capture gate).
+ * enabled → debugEnabled (runtime debug traces).
+ * @param {Object|null|undefined} debugSection
+ * @returns {{ debugEnabled?: boolean, fullDebugEnabled?: boolean }}
+ */
+function mapRoleAssistantDebugToAssistantsSettings(debugSection) {
+  if (!debugSection || typeof debugSection !== 'object') {
+    return {};
+  }
+  const body = {};
+  if (typeof debugSection.enabled === 'boolean') {
+    body.debugEnabled = debugSection.enabled;
+  }
+  if (typeof debugSection.includePromptTrace === 'boolean') {
+    body.fullDebugEnabled = debugSection.includePromptTrace;
+  }
+  return body;
+}
+
+/**
+ * Map role-assistant.yaml runtime.* to the governed Assistants settings names.
+ * Provider selection remains platform-owned; the assistant may override only
+ * its workflow reasoning model and execution profile.
+ * @param {Object|null|undefined} runtimeSection
+ * @returns {{ workflowReasoningModel?: string, temperature?: number, maxLlmLoops?: number, maxToolLoops?: number }}
+ */
+function mapRoleAssistantRuntimeToAssistantsSettings(runtimeSection) {
+  if (!runtimeSection || typeof runtimeSection !== 'object') {
+    return {};
+  }
+  const body = {};
+  if (typeof runtimeSection.model === 'string' && runtimeSection.model.trim()) {
+    body.workflowReasoningModel = runtimeSection.model.trim();
+  }
+  if (typeof runtimeSection.temperature === 'number') {
+    body.temperature = runtimeSection.temperature;
+  }
+  if (Number.isInteger(runtimeSection.maxLoops)) {
+    body.maxLlmLoops = runtimeSection.maxLoops;
+    body.maxToolLoops = runtimeSection.maxLoops;
+  }
+  return body;
+}
+
+/**
+ * Push role-assistant.yaml knowledge + debug settings to dataplane Assistants.
+ * Called on upload/deploy so the operator UI and CLI stay aligned.
+ */
+function resolveAssistantSettingsPush(params) {
+  const {
+    systemKey,
+    environment = 'dev',
+    pathOptions = {}
+  } = params;
+  const settingsEnv = resolveRoleAssistantSettingsEnvKey(environment);
+  const settings = readRoleAssistantSettings(systemKey, { required: false, pathOptions });
+  if (!settings) {
+    return { result: { skipped: true, reason: 'missing-role-assistant-settings' } };
+  }
+  const section = resolveRoleAssistantEnvironmentSettings(settings, settingsEnv, {
+    required: false
+  });
+  if (!section) {
+    return { result: { skipped: true, reason: 'missing-env-settings' } };
+  }
+  const documentStorageKey =
+    resolveDocumentStorageKeyFromRoleAssistantSettings(settings, settingsEnv) || '';
+  const debugBody = mapRoleAssistantDebugToAssistantsSettings(section.debug);
+  const runtimeBody = mapRoleAssistantRuntimeToAssistantsSettings(section.runtime);
+  const settingsBody = { ...runtimeBody, ...debugBody };
+  if (!documentStorageKey && Object.keys(settingsBody).length === 0) {
+    return { result: { skipped: true, reason: 'no-document-storage-key', documentStorageKey: null } };
+  }
+  const patchBody = { ...settingsBody };
+  if (documentStorageKey) {
+    patchBody.documentStorageKey = documentStorageKey;
+  }
+  return { documentStorageKey, debugBody: settingsBody, patchBody };
+}
+
+async function applyAssistantSettingsPush(dataplaneUrl, systemKey, authConfig, settingsPush) {
+  const { documentStorageKey, debugBody, patchBody } = settingsPush;
+  const hasDocumentStorageKey = documentStorageKey !== '';
+  const hasDebugSettings = Object.keys(debugBody).length > 0;
+  const assistantKey = String(systemKey || '').trim();
+  let response = await updateAssistantSettings(
+    dataplaneUrl,
+    assistantKey,
+    authConfig,
+    patchBody
+  );
+  if (response && response.success === false && hasDocumentStorageKey && hasDebugSettings) {
+    response = await updateAssistantSettings(
+      dataplaneUrl,
+      assistantKey,
+      authConfig,
+      debugBody
+    );
+    if (response && response.success === false) {
+      throw new Error(
+        response.formattedError ||
+          response.error ||
+          'Failed to update Assistants debug settings'
+      );
+    }
+    return {
+      skipped: false,
+      documentStorageKey: null,
+      documentStoragePushFailed: true,
+      ...debugBody
+    };
+  }
+  if (response && response.success === false) {
+    throw new Error(
+      response.formattedError ||
+        response.error ||
+        'Failed to update Knowledge document storage settings'
+    );
+  }
+  return {
+    skipped: false,
+    documentStorageKey: documentStorageKey || null,
+    ...debugBody
+  };
+}
+
+async function pushRoleAssistantDocumentStorageSettings(params) {
+  const { systemKey, dataplaneUrl, authConfig, dryRun = false } = params;
+  const settingsPush = resolveAssistantSettingsPush(params);
+  if (settingsPush.result) {
+    return settingsPush.result;
+  }
+  const { documentStorageKey, debugBody } = settingsPush;
+  if (dryRun) {
+    return { skipped: false, dryRun: true, documentStorageKey: documentStorageKey || null, ...debugBody };
+  }
+  if (!dataplaneUrl || !authConfig) {
+    return { skipped: true, reason: 'missing-dataplane-auth' };
+  }
+  return applyAssistantSettingsPush(dataplaneUrl, systemKey, authConfig, settingsPush);
+}
+
+module.exports = {
+  resolveRoleAssistantSettingsEnvKey,
+  mapRoleAssistantDebugToAssistantsSettings,
+  mapRoleAssistantRuntimeToAssistantsSettings,
+  pushRoleAssistantDocumentStorageSettings
+};

package/lib/role-assistant/knowledge-sync.js

@@ -15,8 +15,7 @@ const yaml = require('js-yaml');
 const { listDocuments, validateDocuments, bulkDocuments } = require('../api/datasources-extended.api');
 const {
   extractDocumentStorageKeyFromAssistantDetails,
-  getAssistantDetails,
-  updateAssistantSettings
+  getAssistantDetails
 } = require('../api/assistants.api');
 const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { bareRoleKey } = require('../utils/role-assistant-paths');
@@ -24,9 +23,14 @@ const {
   SYSTEM_KIND_DIGITAL_WORKER,
   getRoleAssistantYamlPath,
   readRoleAssistantSettings,
-  resolveDocumentStorageKeyFromRoleAssistantSettings,
-  resolveRoleAssistantEnvironmentSettings
+  resolveDocumentStorageKeyFromRoleAssistantSettings
 } = require('./settings');
+const {
+  resolveRoleAssistantSettingsEnvKey,
+  mapRoleAssistantDebugToAssistantsSettings,
+  mapRoleAssistantRuntimeToAssistantsSettings,
+  pushRoleAssistantDocumentStorageSettings
+} = require('./knowledge-sync-settings-push');
 const {
   knowledgeSearchMetadataFromFrontmatter,
   splitMarkdownFrontmatter
@@ -87,123 +91,6 @@ async function resolveDocumentStorageKeyFromDataplane(dataplaneUrl, authConfig,
   }
 }
 
-/**
- * Map role-assistant.yaml debug.* → Assistants settings PATCH fields.
- * includePromptTrace → fullDebugEnabled (LLM prompt capture gate).
- * enabled → debugEnabled (runtime debug traces).
- * @param {Object|null|undefined} debugSection
- * @returns {{ debugEnabled?: boolean, fullDebugEnabled?: boolean }}
- */
-function mapRoleAssistantDebugToAssistantsSettings(debugSection) {
-  if (!debugSection || typeof debugSection !== 'object') {
-    return {};
-  }
-  const body = {};
-  if (typeof debugSection.enabled === 'boolean') {
-    body.debugEnabled = debugSection.enabled;
-  }
-  if (typeof debugSection.includePromptTrace === 'boolean') {
-    body.fullDebugEnabled = debugSection.includePromptTrace;
-  }
-  return body;
-}
-
-/**
- * Push role-assistant.yaml knowledge + debug settings to dataplane Assistants.
- * Called on upload/deploy so the operator UI and CLI stay aligned.
- */
-function resolveAssistantSettingsPush(params) {
-  const {
-    systemKey,
-    environment = 'dev',
-    pathOptions = {}
-  } = params;
-  const settingsEnv = resolveRoleAssistantSettingsEnvKey(environment);
-  const settings = readRoleAssistantSettings(systemKey, { required: false, pathOptions });
-  if (!settings) {
-    return { result: { skipped: true, reason: 'missing-role-assistant-settings' } };
-  }
-  const section = resolveRoleAssistantEnvironmentSettings(settings, settingsEnv, {
-    required: false
-  });
-  if (!section) {
-    return { result: { skipped: true, reason: 'missing-env-settings' } };
-  }
-  const documentStorageKey =
-    resolveDocumentStorageKeyFromRoleAssistantSettings(settings, settingsEnv) || '';
-  const debugBody = mapRoleAssistantDebugToAssistantsSettings(section.debug);
-  if (!documentStorageKey && Object.keys(debugBody).length === 0) {
-    return { result: { skipped: true, reason: 'no-document-storage-key', documentStorageKey: null } };
-  }
-  const patchBody = { ...debugBody };
-  if (documentStorageKey) {
-    patchBody.documentStorageKey = documentStorageKey;
-  }
-  return { documentStorageKey, debugBody, patchBody };
-}
-
-async function applyAssistantSettingsPush(dataplaneUrl, systemKey, authConfig, settingsPush) {
-  const { documentStorageKey, debugBody, patchBody } = settingsPush;
-  const hasDocumentStorageKey = documentStorageKey !== '';
-  const hasDebugSettings = Object.keys(debugBody).length > 0;
-  const assistantKey = String(systemKey || '').trim();
-  let response = await updateAssistantSettings(
-    dataplaneUrl,
-    assistantKey,
-    authConfig,
-    patchBody
-  );
-  if (response && response.success === false && hasDocumentStorageKey && hasDebugSettings) {
-    response = await updateAssistantSettings(
-      dataplaneUrl,
-      assistantKey,
-      authConfig,
-      debugBody
-    );
-    if (response && response.success === false) {
-      throw new Error(
-        response.formattedError ||
-          response.error ||
-          'Failed to update Assistants debug settings'
-      );
-    }
-    return {
-      skipped: false,
-      documentStorageKey: null,
-      documentStoragePushFailed: true,
-      ...debugBody
-    };
-  }
-  if (response && response.success === false) {
-    throw new Error(
-      response.formattedError ||
-        response.error ||
-        'Failed to update Knowledge document storage settings'
-    );
-  }
-  return {
-    skipped: false,
-    documentStorageKey: documentStorageKey || null,
-    ...debugBody
-  };
-}
-
-async function pushRoleAssistantDocumentStorageSettings(params) {
-  const { systemKey, dataplaneUrl, authConfig, dryRun = false } = params;
-  const settingsPush = resolveAssistantSettingsPush(params);
-  if (settingsPush.result) {
-    return settingsPush.result;
-  }
-  const { documentStorageKey, debugBody } = settingsPush;
-  if (dryRun) {
-    return { skipped: false, dryRun: true, documentStorageKey: documentStorageKey || null, ...debugBody };
-  }
-  if (!dataplaneUrl || !authConfig) {
-    return { skipped: true, reason: 'missing-dataplane-auth' };
-  }
-  return applyAssistantSettingsPush(dataplaneUrl, systemKey, authConfig, settingsPush);
-}
-
 /**
  * Resolve Knowledge document storage key.
  * Order: role-assistant.yaml → dataplane Assistants settings → package dataSources.
@@ -341,11 +228,6 @@ function resolveDocumentFileName(row, index) {
   return filePath.startsWith('/') ? filePath.slice(1) : filePath;
 }
 
-function resolveRoleAssistantSettingsEnvKey(environment) {
-  const token = String(environment || '').trim().toLowerCase();
-  return token === 'dev' || token === 'tst' || token === 'pro' ? token : 'dev';
-}
-
 function writeRoleAssistantSettingsFile(systemKey, docStorageKey, environment = 'dev', pathOptions = {}) {
   const roleAssistantPath = resolveExternalSystemPath(systemKey, pathOptions);
   const roleAssistantYamlPath = getRoleAssistantYamlPath(systemKey, { pathOptions });
@@ -477,6 +359,7 @@ module.exports = {
   resolveRoleAssistantSettingsEnvKey,
   resolveRoleAssistantDocumentStorageKey,
   mapRoleAssistantDebugToAssistantsSettings,
+  mapRoleAssistantRuntimeToAssistantsSettings,
   pushRoleAssistantDocumentStorageSettings,
   importRoleAssistantKnowledge,
   exportRoleAssistantKnowledge,

package/lib/role-assistant/package-validate.js

@@ -0,0 +1,175 @@
+/**
+ * Role Assistant package folder validation (settings, tests, evidence, knowledge).
+ * @fileoverview Walk ra-* governed files. Ignore leftover Connected System artifacts.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { validateExternalFile, parseJsonFileContent } = require('../validation/validate-external-file');
+const { listTestCaseFiles } = require('./test-cases');
+const { validateTestCaseFile } = require('./test-case-validate');
+
+const SETTINGS_TYPE = 'role-assistant-settings';
+const EMPTY_TESTS_SKIP = 'tests/: skipped (no test cases)';
+
+function fileRow(filePath, type, result) {
+  return {
+    file: path.basename(filePath),
+    type,
+    valid: result.valid,
+    path: filePath,
+    errors: result.errors || [],
+    warnings: result.warnings || []
+  };
+}
+
+function listFilesByExt(dirPath, ext, acc) {
+  if (!fs.existsSync(dirPath)) {
+    return acc;
+  }
+  for (const name of fs.readdirSync(dirPath)) {
+    if (String(name).startsWith('.')) {
+      continue;
+    }
+    const full = path.join(dirPath, name);
+    const st = fs.statSync(full);
+    if (st.isDirectory()) {
+      listFilesByExt(full, ext, acc);
+    } else if (String(name).toLowerCase().endsWith(ext)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+function evidenceRows(parsed) {
+  if (Array.isArray(parsed)) {
+    return parsed;
+  }
+  if (parsed && typeof parsed === 'object') {
+    return [parsed];
+  }
+  return null;
+}
+
+function validateEvidenceJsonFile(filePath) {
+  const parseResult = parseJsonFileContent(filePath);
+  if (parseResult.error) {
+    return { ...parseResult.error, file: filePath, type: 'evidence' };
+  }
+  const rows = evidenceRows(parseResult.parsed);
+  const errors = [];
+  if (!rows) {
+    errors.push(`${filePath}: Evidence JSON must be an object or array of objects`);
+  } else {
+    rows.forEach((row, index) => {
+      const key = row && typeof row === 'object' && !Array.isArray(row) ? String(row.key || '').trim() : '';
+      if (!key) {
+        errors.push(`${filePath}: item ${index} is missing key`);
+      }
+    });
+  }
+  return { valid: errors.length === 0, errors, warnings: [], file: filePath, type: 'evidence' };
+}
+
+function validateKnowledgeMarkdown(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8');
+  if (!String(text).trim()) {
+    return {
+      valid: false,
+      errors: [`${filePath}: knowledge markdown must not be empty`],
+      warnings: [],
+      file: filePath,
+      type: 'knowledge'
+    };
+  }
+  return { valid: true, errors: [], warnings: [], file: filePath, type: 'knowledge' };
+}
+
+async function validateSettingsFile(appPath) {
+  const yamlPath = path.join(appPath, 'role-assistant.yaml');
+  try {
+    const result = await validateExternalFile(yamlPath, SETTINGS_TYPE);
+    return fileRow(yamlPath, SETTINGS_TYPE, result);
+  } catch (error) {
+    return fileRow(yamlPath, SETTINGS_TYPE, {
+      valid: false,
+      errors: [error.message],
+      warnings: []
+    });
+  }
+}
+
+function collectDuplicateCaseIdErrors(caseFiles) {
+  const seen = new Map();
+  const errors = [];
+  for (const row of caseFiles) {
+    const parseResult = parseJsonFileContent(row.path);
+    const caseId = parseResult.parsed && String(parseResult.parsed.caseId || '').trim();
+    if (!caseId) {
+      continue;
+    }
+    if (seen.has(caseId)) {
+      errors.push(`${row.path}: duplicate caseId "${caseId}" (also ${seen.get(caseId)})`);
+    } else {
+      seen.set(caseId, row.path);
+    }
+  }
+  return errors;
+}
+
+function validateTestFiles(appPath) {
+  const testsDir = path.join(appPath, 'tests');
+  const yamlFiles = listTestCaseFiles(testsDir);
+  if (yamlFiles.length === 0) {
+    return { files: [], errors: [], warnings: [EMPTY_TESTS_SKIP] };
+  }
+  const files = yamlFiles.map((filePath) => fileRow(filePath, 'role-assistant-test-case', validateTestCaseFile(filePath)));
+  const errors = files.flatMap((row) => row.errors);
+  errors.push(...collectDuplicateCaseIdErrors(files));
+  return { files, errors, warnings: [] };
+}
+
+function validateEvidenceFiles(appPath) {
+  const jsonFiles = listFilesByExt(path.join(appPath, 'evidence'), '.json', []);
+  const files = jsonFiles.map((filePath) => fileRow(filePath, 'evidence', validateEvidenceJsonFile(filePath)));
+  return { files, errors: files.flatMap((row) => row.errors), warnings: [] };
+}
+
+function validateKnowledgeFiles(appPath) {
+  const mdFiles = listFilesByExt(path.join(appPath, 'knowledge'), '.md', []).filter((filePath) => {
+    return path.dirname(filePath) === path.join(appPath, 'knowledge');
+  });
+  const files = mdFiles.map((filePath) => fileRow(filePath, 'knowledge', validateKnowledgeMarkdown(filePath)));
+  return { files, errors: files.flatMap((row) => row.errors), warnings: [] };
+}
+
+async function validateRoleAssistantPackage(appPath) {
+  const settings = await validateSettingsFile(appPath);
+  const tests = validateTestFiles(appPath);
+  const evidence = validateEvidenceFiles(appPath);
+  const knowledge = validateKnowledgeFiles(appPath);
+  const files = [settings, ...tests.files, ...evidence.files, ...knowledge.files];
+  const errors = [
+    ...settings.errors,
+    ...tests.errors,
+    ...evidence.errors,
+    ...knowledge.errors
+  ];
+  const warnings = [...settings.warnings, ...tests.warnings, ...evidence.warnings, ...knowledge.warnings];
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    files
+  };
+}
+
+module.exports = {
+  EMPTY_TESTS_SKIP,
+  validateRoleAssistantPackage,
+  validateEvidenceJsonFile,
+  validateKnowledgeMarkdown
+};

package/lib/role-assistant/test-case-assertion-row.js

@@ -0,0 +1,36 @@
+/**
+ * Shared assertion row helpers (pass/fail/warn/notes/skip).
+ * @fileoverview Kind flags for Role Assistant test result rows
+ */
+
+'use strict';
+
+function skipRow(id, message) {
+  return { id, passed: true, skip: true, kind: 'skip', message };
+}
+
+function notesRow(id, message) {
+  return { id, passed: true, notes: true, kind: 'notes', message };
+}
+
+function withKind(row) {
+  if (!row || row.kind) {
+    return row;
+  }
+  if (row.notes === true) {
+    return { ...row, kind: 'notes' };
+  }
+  if (row.skip === true) {
+    return { ...row, kind: 'skip' };
+  }
+  if (row.warn === true) {
+    return { ...row, kind: 'warn' };
+  }
+  return { ...row, kind: row.passed ? 'pass' : 'fail' };
+}
+
+module.exports = {
+  skipRow,
+  notesRow,
+  withKind
+};

package/lib/role-assistant/test-case-copy-bind.js

@@ -0,0 +1,77 @@
+/**
+ * Bind a Work Hub execution to the Role Assistant named on copy.
+ *
+ * @fileoverview Fail closed on mismatch; trust the CLI role when identity is absent
+ */
+
+'use strict';
+
+const {
+  bareRoleKey,
+  roleAssistantSystemKey
+} = require('../utils/role-assistant-paths');
+
+const PLACEHOLDER = new Set(['', 'unknown', 'none', 'null']);
+
+function throwCopyStatus(message, status) {
+  const err = new Error(message);
+  err.status = status;
+  throw err;
+}
+
+function usableIdentity(value) {
+  const token = String(value || '').trim();
+  if (!token || PLACEHOLDER.has(token.toLowerCase())) {
+    return '';
+  }
+  return token;
+}
+
+function pushIdentity(acc, value) {
+  const token = usableIdentity(value);
+  if (token) {
+    acc.push(token);
+  }
+}
+
+function boundIdentityTokens(status, result) {
+  const acc = [];
+  const task = result && result.task && typeof result.task === 'object' ? result.task : {};
+  pushIdentity(acc, status && status.assistantKey);
+  pushIdentity(acc, status && status.digitalWorkerKey);
+  pushIdentity(acc, result && result.assistantKey);
+  pushIdentity(acc, result && result.digitalWorkerKey);
+  pushIdentity(acc, task.assistantKey);
+  pushIdentity(acc, task.digitalWorkerKey);
+  pushIdentity(acc, task.activeBusinessRoleRef);
+  pushIdentity(acc, task.roleKey);
+  return [...new Set(acc)];
+}
+
+function identityMatchesSystem(token, systemKey) {
+  const expectedSystem = roleAssistantSystemKey(systemKey);
+  const expectedBare = bareRoleKey(systemKey).toLowerCase();
+  const lower = token.toLowerCase();
+  if (lower === expectedSystem.toLowerCase()) {
+    return true;
+  }
+  return bareRoleKey(token).toLowerCase() === expectedBare;
+}
+
+function assertCopyBoundToSystem(systemKey, status, result) {
+  const tokens = boundIdentityTokens(status, result);
+  if (tokens.length === 0) {
+    return { bound: false };
+  }
+  const mismatch = tokens.find((token) => !identityMatchesSystem(token, systemKey));
+  if (mismatch) {
+    throwCopyStatus('Execution belongs to a different Role Assistant', 409);
+  }
+  return { bound: true };
+}
+
+module.exports = {
+  throwCopyStatus,
+  boundIdentityTokens,
+  assertCopyBoundToSystem
+};