@aifabrix/builder 2.53.1 → 2.55.0

package/lib/agent-kit/state-file.js

@@ -0,0 +1,83 @@
+/**
+ * Installed Agent Kit state file.
+ * @fileoverview Read/write .aifabrix/agent-kit.yaml
+ */
+
+'use strict';
+
+const path = require('path');
+const yaml = require('js-yaml');
+const fs = require('../internal/fs-real-sync');
+const { STATE_RELATIVE, SECTION_ID } = require('./constants');
+
+/**
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function statePath(repoRoot) {
+  return path.join(repoRoot, STATE_RELATIVE);
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {object|null}
+ */
+function loadState(repoRoot) {
+  const filePath = statePath(repoRoot);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  const parsed = yaml.load(fs.readFileSync(filePath, 'utf8'));
+  if (!parsed || typeof parsed !== 'object') {
+    return null;
+  }
+  return parsed;
+}
+
+/**
+ * @param {object} kit
+ * @param {string[]} hosts
+ * @param {object[]} ops
+ * @param {string} builderVersion
+ * @returns {object}
+ */
+function buildStateDocument(kit, hosts, ops, builderVersion) {
+  const managedFiles = [];
+  for (const op of ops) {
+    if (op.action === 'delete' || op.action === 'retain' || op.action === 'conflict') {
+      continue;
+    }
+    if (op.action === 'skip' && op.fileState === 'MISSING') {
+      continue;
+    }
+    if (!op.targetRel || op.mode === 'obsolete' || op.mode === 'if-missing') {
+      continue;
+    }
+    const row = { path: op.targetRel, sha256: op.sourceHash };
+    if (op.mode === 'managed-section') {
+      row.section = SECTION_ID;
+    }
+    managedFiles.push(row);
+  }
+  return {
+    schemaVersion: '1',
+    kitVersion: kit.manifest.kitVersion,
+    builderVersion,
+    installedAt: new Date().toISOString(),
+    hosts,
+    managedFiles
+  };
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {object} doc
+ * @returns {void}
+ */
+function writeState(repoRoot, doc) {
+  const filePath = statePath(repoRoot);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, yaml.dump(doc, { lineWidth: 120, noRefs: true, sortKeys: false }), 'utf8');
+}
+
+module.exports = { statePath, loadState, buildStateDocument, writeState };

package/lib/agent-kit/status.js

@@ -0,0 +1,50 @@
+/**
+ * Agent Kit status.
+ * @fileoverview Classify installed files without writing
+ */
+
+'use strict';
+
+const { getCliVersion } = require('../utils/installation-log-core');
+const { resolveGitRoot } = require('./repo-guard');
+const { loadKitPackage } = require('./package-load');
+const { listManagedTargets } = require('./file-list');
+const { classifyItems } = require('./classify');
+const { detectV1, listObsoleteV1Items } = require('./v1-detect');
+const { loadState } = require('./state-file');
+const { ACTION } = require('./constants');
+const { kitStateName, buildJsonReport } = require('./report');
+const { ALL_HOSTS } = require('./hosts');
+
+/**
+ * @param {object} options
+ * @returns {object}
+ */
+function runStatus(options) {
+  const repoRoot = resolveGitRoot(options.cwd || process.cwd());
+  const kit = loadKitPackage();
+  const state = loadState(repoRoot);
+  const includeShims = detectV1(repoRoot);
+  const hosts = (state && state.hosts) || ALL_HOSTS.slice();
+  const includeClaude = hosts.includes('claude');
+  const items = listManagedTargets(kit, repoRoot, {
+    includeShims: includeShims && hosts.includes('cursor'),
+    includeClaude
+  });
+  classifyItems(items, state, hosts);
+  items.push(...listObsoleteV1Items(kit, repoRoot, new Set(items.map((item) => item.targetRel))));
+  const ops = items.map((item) => ({ ...item, action: ACTION.SKIP }));
+  const kitState = kitStateName(state, kit, ops);
+  return buildJsonReport({
+    command: 'status',
+    kit,
+    state,
+    hosts,
+    ops,
+    dryRun: true,
+    builderVersion: getCliVersion(),
+    kitState
+  });
+}
+
+module.exports = { runStatus };

package/lib/agent-kit/v1-detect.js

@@ -0,0 +1,81 @@
+/**
+ * Detect v1 Agent Kit files in a customer repository.
+ * @fileoverview Name + hash detection for migration
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { V1_MARKERS, FILE_STATE } = require('./constants');
+const { sha256File } = require('./checksums');
+
+/**
+ * @param {string} repoRoot
+ * @returns {boolean}
+ */
+function detectV1(repoRoot) {
+  return V1_MARKERS.some((rel) => fs.existsSync(path.join(repoRoot, rel)));
+}
+
+/**
+ * @param {object} kit
+ * @param {string} repoRoot
+ * @param {Set<string>} managedRels
+ * @returns {object[]}
+ */
+function listObsoleteV1Items(kit, repoRoot, managedRels) {
+  const rows = (kit.inventory && kit.inventory.v1Files) || [];
+  const items = [];
+  for (const row of rows) {
+    if (row.disposition === 'shim' || !row.installedPath) {
+      continue;
+    }
+    if (managedRels.has(row.installedPath)) {
+      continue;
+    }
+    const targetAbs = path.join(repoRoot, row.installedPath);
+    if (!fs.existsSync(targetAbs)) {
+      continue;
+    }
+    const hash = sha256File(targetAbs);
+    const unchanged = hash === row.sha256;
+    items.push({
+      sourceAbs: null,
+      targetRel: row.installedPath,
+      targetAbs,
+      mode: 'obsolete',
+      sourceHash: row.sha256,
+      currentHash: hash,
+      fileState: unchanged
+        ? FILE_STATE.OBSOLETE_UNCHANGED_MANAGED
+        : FILE_STATE.OBSOLETE_MODIFIED_MANAGED,
+      v1Owner: row.owner
+    });
+  }
+  return items;
+}
+
+/**
+ * Replace unmodified v1 command files with thin shims on install.
+ * @param {object[]} items
+ * @param {object} kit
+ * @returns {void}
+ */
+function markV1ShimReplacements(items, kit) {
+  const byPath = new Map();
+  for (const row of (kit.inventory && kit.inventory.v1Files) || []) {
+    byPath.set(row.installedPath, row);
+  }
+  for (const item of items) {
+    if (!item.optional || !item.currentHash) {
+      continue;
+    }
+    const row = byPath.get(item.targetRel);
+    if (row && row.disposition === 'shim' && item.currentHash === row.sha256) {
+      item.replaceOnInstall = true;
+    }
+  }
+}
+
+module.exports = { detectV1, listObsoleteV1Items, markV1ShimReplacements };

package/lib/agent-kit/validate-kit.js

@@ -0,0 +1,87 @@
+/**
+ * Validate bundled Agent Kit package and optional install.
+ * @fileoverview Schema, paths, skill names, installed conflicts
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { loadKitPackage } = require('./package-load');
+const { listTreeFiles } = require('./file-list');
+const { runStatus } = require('./status');
+const { KIT_STATE } = require('./constants');
+
+const FORBIDDEN_RE = /@[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}|kv:\/\/[^\s]+\/[A-Za-z0-9+/]{12,}|\/home\/[a-z0-9]+\/(?!dev)/i;
+
+/**
+ * @param {object} kit
+ * @returns {string[]}
+ */
+function collectPackageErrors(kit) {
+  const errors = [];
+  const names = kit.manifest.skills || [];
+  if (new Set(names).size !== names.length) {
+    errors.push('Duplicate skill name in agent-kit.yaml.');
+  }
+  for (const name of names) {
+    const skillMd = path.join(kit.root, 'skills', name, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) {
+      errors.push(`Missing SKILL.md for ${name}.`);
+    }
+  }
+  for (const spec of [...(kit.manifest.managed || []), ...(kit.manifest.optional || [])]) {
+    const sourceAbs = path.join(kit.root, spec.source);
+    if (!fs.existsSync(sourceAbs)) {
+      errors.push(`Managed source missing: ${spec.source}`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * @param {object} kit
+ * @returns {string[]}
+ */
+function collectContentErrors(kit) {
+  const errors = [];
+  for (const file of listTreeFiles(kit.root, '')) {
+    if (file.rel === 'parity-inventory.yaml') {
+      continue;
+    }
+    const text = fs.readFileSync(file.abs, 'utf8');
+    if (FORBIDDEN_RE.test(text)) {
+      errors.push(`Forbidden customer/secret pattern in ${file.rel}`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * @param {object} [options]
+ * @returns {object}
+ */
+function runValidate(options = {}) {
+  const kit = loadKitPackage();
+  const errors = [...collectPackageErrors(kit), ...collectContentErrors(kit)];
+  let install = null;
+  try {
+    install = runStatus(options);
+  } catch (error) {
+    if (!String(error.message || '').includes('git repository')) {
+      throw error;
+    }
+  }
+  if (install && install.state === KIT_STATE.CONFLICTS) {
+    errors.push(`Install conflicts: ${install.conflicts.join(', ')}`);
+  }
+  return {
+    success: errors.length === 0,
+    command: 'validate',
+    kitVersion: kit.manifest.kitVersion,
+    errors,
+    install
+  };
+}
+
+module.exports = { runValidate, collectPackageErrors, collectContentErrors };

package/lib/agent-kit/workspace-name.js

@@ -0,0 +1,40 @@
+/**
+ * Resolve workspace directory name for agent-kit init.
+ * @fileoverview Name authority — never rewrite cust-* to aif-*
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * @param {string|undefined} nameOrPath
+ * @param {string} cwd
+ * @returns {{ targetAbs: string, workspaceName: string }}
+ */
+function resolveWorkspaceTarget(nameOrPath, cwd) {
+  const base = path.resolve(cwd || process.cwd());
+  if (!nameOrPath || !String(nameOrPath).trim()) {
+    throw new Error('Workspace name or path is required. Example: aifabrix agent-kit init cust-demo');
+  }
+  const raw = String(nameOrPath).trim();
+  const looksLikePath =
+    path.isAbsolute(raw) || raw.includes('/') || raw.includes('\\') || raw === '.' || raw.startsWith('.');
+  const targetAbs = looksLikePath ? path.resolve(base, raw) : path.join(base, raw);
+  const workspaceName = path.basename(targetAbs);
+  if (!workspaceName || workspaceName === '.' || workspaceName === '..') {
+    throw new Error('Could not derive a workspace name from the path.');
+  }
+  return { targetAbs, workspaceName };
+}
+
+/**
+ * Preserve user-supplied names; never rewrite cust-* prefixes.
+ * @param {string} name
+ * @returns {string}
+ */
+function assertNameUnchanged(name) {
+  return name;
+}
+
+module.exports = { resolveWorkspaceTarget, assertNameUnchanged };

package/lib/agent-kit/workspace-skeleton.js

@@ -0,0 +1,103 @@
+/**
+ * Copy product-neutral workspace skeleton for agent-kit init.
+ * @fileoverview templates/agent-kit/workspace → target
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { getKitRoot } = require('./kit-root');
+
+/**
+ * @returns {string}
+ */
+function getWorkspaceTemplateRoot() {
+  return path.join(getKitRoot(), 'workspace');
+}
+
+/**
+ * @param {string} text
+ * @param {{ workspaceName: string, year?: number, copyrightHolder?: string }} vars
+ * @returns {string}
+ */
+function applyPlaceholders(text, vars) {
+  return String(text)
+    .replace(/\{\{workspaceName\}\}/g, vars.workspaceName)
+    .replace(/\{\{year\}\}/g, String(vars.year || new Date().getFullYear()))
+    .replace(/\{\{copyrightHolder\}\}/g, vars.copyrightHolder || 'Copyright Holder');
+}
+
+/**
+ * @param {string} absDir
+ * @param {string} relPrefix
+ * @returns {{ rel: string, abs: string }[]}
+ */
+function listTemplateFiles(absDir, relPrefix) {
+  if (!fs.existsSync(absDir)) {
+    return [];
+  }
+  const out = [];
+  for (const ent of fs.readdirSync(absDir, { withFileTypes: true })) {
+    const rel = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+    const abs = path.join(absDir, ent.name);
+    if (ent.isDirectory()) {
+      out.push(...listTemplateFiles(abs, rel));
+    } else if (ent.name !== 'LICENSE.mit') {
+      out.push({ rel, abs });
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string} targetAbs
+ * @param {{ workspaceName: string, license?: string, dryRun?: boolean }} options
+ * @returns {string[]} written relative paths
+ */
+function writeWorkspaceSkeleton(targetAbs, options) {
+  const written = [];
+  const vars = { workspaceName: options.workspaceName };
+  const root = getWorkspaceTemplateRoot();
+  for (const file of listTemplateFiles(root, '')) {
+    const dest = path.join(targetAbs, file.rel);
+    if (!options.dryRun) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const body = applyPlaceholders(fs.readFileSync(file.abs, 'utf8'), vars);
+      fs.writeFileSync(dest, body, 'utf8');
+    }
+    written.push(file.rel);
+  }
+  if (options.license === 'mit') {
+    const src = path.join(root, 'LICENSE.mit');
+    const dest = path.join(targetAbs, 'LICENSE');
+    if (!options.dryRun && fs.existsSync(src)) {
+      fs.writeFileSync(dest, applyPlaceholders(fs.readFileSync(src, 'utf8'), vars), 'utf8');
+    }
+    written.push('LICENSE');
+  }
+  if (!options.dryRun) {
+    fs.mkdirSync(path.join(targetAbs, 'integration'), { recursive: true });
+    fs.mkdirSync(path.join(targetAbs, 'role-assistant'), { recursive: true });
+  }
+  return written;
+}
+
+/**
+ * @param {string} targetAbs
+ * @returns {boolean}
+ */
+function isNonEmptyDirectory(targetAbs) {
+  if (!fs.existsSync(targetAbs)) {
+    return false;
+  }
+  const entries = fs.readdirSync(targetAbs).filter((name) => name !== '.git');
+  return entries.length > 0;
+}
+
+module.exports = {
+  getWorkspaceTemplateRoot,
+  applyPlaceholders,
+  writeWorkspaceSkeleton,
+  isNonEmptyDirectory
+};

package/lib/api/assistants.api.js

@@ -8,20 +8,23 @@
 
 const { createDataplaneApiClient } = require('./index');
 
+function encodeAssistantPathKey(assistantKey) {
+  return encodeURIComponent(String(assistantKey || '').trim());
+}
+
 /**
  * GET /api/v1/admin/assistants/{assistantKey}
  * @async
  * @function getAssistantDetails
  * @param {string} dataplaneUrl - Dataplane base URL
- * @param {string} assistantKey - Role Assistant / digital worker key
+ * @param {string} assistantKey - Digital worker system key (exact; never rewritten)
  * @param {Object} authConfig - Auth config for dataplane client
  * @returns {Promise<Object>} API response
  * @requiresPermission {Dataplane} worker:read
  */
 async function getAssistantDetails(dataplaneUrl, assistantKey, authConfig) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  const key = encodeURIComponent(String(assistantKey || '').trim());
-  return await client.get(`/api/v1/admin/assistants/${key}`);
+  return await client.get(`/api/v1/admin/assistants/${encodeAssistantPathKey(assistantKey)}`);
 }
 
 /**
@@ -29,7 +32,7 @@ async function getAssistantDetails(dataplaneUrl, assistantKey, authConfig) {
  * @async
  * @function updateAssistantSettings
  * @param {string} dataplaneUrl
- * @param {string} assistantKey
+ * @param {string} assistantKey - Digital worker system key (exact; never rewritten)
  * @param {Object} authConfig
  * @param {Object} body - AssistantSettingsUpdate fields
  * @returns {Promise<Object>}
@@ -37,7 +40,7 @@ async function getAssistantDetails(dataplaneUrl, assistantKey, authConfig) {
  */
 async function updateAssistantSettings(dataplaneUrl, assistantKey, authConfig, body) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  const key = encodeURIComponent(String(assistantKey || '').trim());
+  const key = encodeAssistantPathKey(assistantKey);
   return await client.patch(`/api/v1/admin/assistants/${key}/settings`, { body });
 }
 

package/lib/api/channel-identity.api.js

@@ -0,0 +1,41 @@
+/**
+ * Dataplane channel identity mapping API.
+ *
+ * @fileoverview Admin batch upsert for Slack/Teams → platform user ids
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+
+const MAPPINGS_ENDPOINT = '/api/v1/assistant/channel-identity/mappings';
+
+/**
+ * Upsert channel_user_identity rows (matched pairs only).
+ * @requiresPermission {Dataplane} worker:update
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {{ sourceChannel: string, items: Array<{ externalUserId: string, platformUserId: string }> }} body
+ * @returns {Promise<{ sourceChannel?: string, linked?: number }>}
+ */
+async function upsertChannelIdentityMappings(dataplaneUrl, authConfig, body) {
+  if (!dataplaneUrl || typeof dataplaneUrl !== 'string') {
+    throw new Error('dataplaneUrl is required and must be a string');
+  }
+  const items = body && Array.isArray(body.items) ? body.items : [];
+  if (items.length === 0) {
+    return { sourceChannel: body && body.sourceChannel, linked: 0 };
+  }
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.post(MAPPINGS_ENDPOINT, {
+    body: {
+      sourceChannel: body.sourceChannel,
+      items
+    }
+  });
+}
+
+module.exports = {
+  upsertChannelIdentityMappings
+};

package/lib/api/evidence-authoring.api.js

@@ -10,6 +10,7 @@ const { createDataplaneApiClient } = require('./index');
 const { listEvidenceKinds } = require('./evidence-kinds.api');
 const { listResourceTypes } = require('./resource-types.api');
 const { getAssistantDetails } = require('./assistants.api');
+const { roleAssistantSystemKey } = require('../utils/role-assistant-paths');
 const {
   listEvidence,
   loadEvidenceBulk,
@@ -191,8 +192,11 @@ async function getEvidenceMetadata(dataplaneUrl, authConfig, roleKey, options =
     throw new Error('controllerUrl is required for evidence.metadata');
   }
 
+  // Evidence.roleKey is the business role. Assistant HTTP uses the digital-worker
+  // system key (ra-{roleKey}), which is a different resource than a connected system.
+  const assistantKey = roleAssistantSystemKey(normalizedRoleKey) || normalizedRoleKey;
   const [assistantDetails, evidenceKindsRes, resourceTypesRes, evidenceRows] = await Promise.all([
-    getAssistantDetails(dataplaneUrl, normalizedRoleKey, authConfig),
+    getAssistantDetails(dataplaneUrl, assistantKey, authConfig),
     listEvidenceKinds(options.controllerUrl, authConfig, { page: 1, pageSize: 500 }),
     listResourceTypes(options.controllerUrl, authConfig, { page: 1, pageSize: 500 }),
     listEvidence(dataplaneUrl, authConfig, { roleKey: normalizedRoleKey }, options)

package/lib/api/evidence.api.js

@@ -62,6 +62,8 @@ async function listEvidence(dataplaneUrl, authConfig, params = {}, options = {})
   if (params.roleKey) query.roleKey = params.roleKey;
   if (params.genericOnly === true) query.genericOnly = true;
   if (params.status) query.status = params.status;
+  if (params.page) query.page = params.page;
+  if (params.pageSize) query.pageSize = params.pageSize;
   const res = assertApiSuccess(
     await client.get(BASE, { params: query }),
     'List evidence'

package/lib/api/role-assistant-test-pack.api.js

@@ -0,0 +1,86 @@
+/**
+ * Dataplane Role Assistant test pack CRUD + case status.
+ *
+ * @fileoverview PUT/GET pack and PATCH case status
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { throwIfApiFailed } = require('./api-response-errors');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+function packEndpoint(dataplaneUrl, systemIdOrKey, suffix) {
+  const base = String(dataplaneUrl || '').replace(/\/$/, '');
+  const key = encodeURIComponent(systemIdOrKey);
+  return `${base}/api/v1/external/systems/${key}/role-assistant-tests${suffix || ''}`;
+}
+
+function packPath(systemIdOrKey, suffix) {
+  const key = encodeURIComponent(systemIdOrKey);
+  return `/api/v1/external/systems/${key}/role-assistant-tests${suffix || ''}`;
+}
+
+function isMissingPackResponse(res) {
+  return Boolean(res && res.success === false && Number(res.status) === 404);
+}
+
+/**
+ * PUT /api/v1/external/systems/{systemIdOrKey}/role-assistant-tests
+ * @requiresPermission {Dataplane} external-system:update
+ * @async
+ */
+async function upsertRoleAssistantTestPack(dataplaneUrl, authConfig, systemIdOrKey, pack) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.put(packPath(systemIdOrKey), { body: { pack } });
+  throwIfApiFailed(res, {
+    endpointUrl: packEndpoint(dataplaneUrl, systemIdOrKey, '')
+  });
+  return unwrapApiData(res);
+}
+
+/**
+ * GET /api/v1/external/systems/{systemIdOrKey}/role-assistant-tests
+ * @requiresPermission {Dataplane} external-system:read
+ * @async
+ */
+async function getRoleAssistantTestPack(dataplaneUrl, authConfig, systemIdOrKey, options = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(packPath(systemIdOrKey));
+  if (options.allowMissing === true && isMissingPackResponse(res)) {
+    return null;
+  }
+  throwIfApiFailed(res, {
+    endpointUrl: packEndpoint(dataplaneUrl, systemIdOrKey, '')
+  });
+  return unwrapApiData(res);
+}
+
+/**
+ * PATCH /api/v1/external/systems/{systemIdOrKey}/role-assistant-tests/cases/{caseId}/status
+ * @requiresPermission {Dataplane} external-system:update
+ * @async
+ */
+async function patchRoleAssistantTestCaseStatus(
+  dataplaneUrl,
+  authConfig,
+  systemIdOrKey,
+  caseId,
+  body
+) {
+  const suffix = `/cases/${encodeURIComponent(caseId)}/status`;
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.patch(packPath(systemIdOrKey, suffix), { body });
+  throwIfApiFailed(res, {
+    endpointUrl: packEndpoint(dataplaneUrl, systemIdOrKey, suffix)
+  });
+  return unwrapApiData(res);
+}
+
+module.exports = {
+  upsertRoleAssistantTestPack,
+  getRoleAssistantTestPack,
+  patchRoleAssistantTestCaseStatus
+};

package/lib/api/types/evidence.types.js

@@ -111,6 +111,8 @@
  * @property {string} [search]
  * @property {number} [limit]
  * @property {number} [offset]
+ * @property {number} [page]
+ * @property {number} [pageSize]
  */
 
 /**