@aifabrix/builder 2.58.0 → 2.60.0

package/lib/programmatic/bearer-auth.js

@@ -8,8 +8,7 @@
 
 'use strict';
 
-/** @type {import('@aifabrix/miso-client').MisoClient | null} */
-let misoClientSingleton = null;
+const { getBuilderMisoRuntime } = require('./builder-miso-runtime');
 
 /**
  * @param {import('http').IncomingMessage} req
@@ -36,65 +35,10 @@ function assertNoForbiddenAuthHeaders(req) {
 }
 
 /**
- * @returns {string}
- */
-function resolveControllerUrlFromEnv() {
-  const raw =
-    process.env.MISO_CONTROLLER_URL ||
-    process.env.CONTROLLER_URL ||
-    process.env.MISO_WEB_SERVER_URL ||
-    '';
-  const url = String(raw).trim().replace(/\/$/, '');
-  if (!url) {
-    throw new Error('MISO_CONTROLLER_URL (or CONTROLLER_URL) is required for token validation');
-  }
-  return url;
-}
-
-/**
- * @returns {import('@aifabrix/miso-client/dist/types/config.types').MisoClientConfig}
- */
-function buildMisoClientConfigFromEnv() {
-  const clientId = (process.env.MISO_CLIENTID || '').trim();
-  const clientSecret = (process.env.MISO_CLIENTSECRET || '').trim();
-  if (!clientId || !clientSecret) {
-    throw new Error('MISO_CLIENTID and MISO_CLIENTSECRET are required for builder-api auth');
-  }
-  return {
-    clientId,
-    clientSecret,
-    controllerUrl: resolveControllerUrlFromEnv(),
-    logLevel: (process.env.LOG_LEVEL || 'info').toLowerCase()
-  };
-}
-
-/**
- * Test hook — reset cached MisoClient between Jest cases.
- */
-function resetMisoClientForTests() {
-  misoClientSingleton = null;
-}
-
-/**
- * @returns {Promise<import('@aifabrix/miso-client').MisoClient>}
+ * @returns {Promise<import('@aifabrix/miso-client').MisoClient>} Initialized shared client
  */
 async function getMisoClientForAuth() {
-  let MisoClient;
-  try {
-    ({ MisoClient } = require('@aifabrix/miso-client'));
-  } catch {
-    const err = new Error('@aifabrix/miso-client is required for builder-api auth');
-    err.statusCode = 503;
-    throw err;
-  }
-
-  if (!misoClientSingleton) {
-    misoClientSingleton = new MisoClient(buildMisoClientConfigFromEnv());
-  }
-  if (!misoClientSingleton.isInitialized()) {
-    await misoClientSingleton.initialize();
-  }
-  return misoClientSingleton;
+  return getBuilderMisoRuntime().getClient();
 }
 
 /**
@@ -167,9 +111,6 @@ async function authenticateRequest(req, opts = {}) {
 module.exports = {
   extractBearerToken,
   assertNoForbiddenAuthHeaders,
-  resolveControllerUrlFromEnv,
-  buildMisoClientConfigFromEnv,
-  resetMisoClientForTests,
   getMisoClientForAuth,
   validateBearerToken,
   authenticateRequest

package/lib/programmatic/builder-api-startup.js

@@ -0,0 +1,51 @@
+/** @fileoverview Await SDK bootstrap and token proof before accepting requests. */
+'use strict';
+
+const { initializeBuilderMisoRuntime, closeBuilderMisoRuntime } = require('./builder-miso-runtime');
+const { ensureBuilderApiRuntimeConfigDir } = require('./builder-api-runtime-config');
+
+/** @param {Object} server HTTP server @returns {Promise<void>} Listener closed */
+function closeServer(server) {
+  return new Promise(resolve => {
+    server.close(resolve);
+    server.closeAllConnections();
+  });
+}
+
+/**
+ * @param {Object} [options] Startup dependencies
+ * @returns {Promise<{server: Object, close: Function}>} Running application
+ */
+async function startBuilderApi(options = {}) {
+  ensureBuilderApiRuntimeConfigDir();
+  let server;
+  let closing;
+  const close = () => {
+    if (!closing) {
+      closing = Promise.all([server ? closeServer(server) : undefined, closeBuilderMisoRuntime()]);
+    }
+    return closing;
+  };
+  try {
+    const runtime = await initializeBuilderMisoRuntime(options.initSecrets);
+    await runtime.health();
+    const createServer = options.createServer || require('./builder-api-server').createBuilderApiServer;
+    server = createServer(options.port ?? Number(process.env.PORT || 3005));
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.once('listening', () => {
+        server.removeListener('error', reject); resolve();
+      });
+    });
+    return { server, close };
+  } catch (error) {
+    await close().catch(() => {});
+    // Only our allowlisted health errors can cross the process boundary.
+    const failure = new Error('Builder API startup failed: Miso application runtime or authentication unavailable');
+    failure.statusCode = 503;
+    if (error?.statusCode === 503 && error?.errorType?.startsWith('/Errors/miso_')) throw error;
+    throw failure;
+  }
+}
+
+module.exports = { startBuilderApi };

package/lib/programmatic/builder-miso-runtime.js

@@ -0,0 +1,167 @@
+/**
+ * Builder's process-owned SDK runtime and application-token health check.
+ * @fileoverview SDK owns providers, secrets, renewal and connections.
+ */
+'use strict';
+
+const { validateMisoApplicationToken } = require('../api/miso-health.api');
+let activeRuntime;
+
+/** @param {string} code Safe category @returns {Error} Service-unavailable error */
+function runtimeError(code) {
+  const messages = {
+    miso_authentication_failed: 'Miso application authentication failed',
+    miso_timeout: 'Miso application token check timed out',
+    miso_unreachable: 'Miso Controller is unavailable',
+    miso_runtime_unavailable: 'Miso application runtime is unavailable'
+  };
+  return Object.assign(new Error(messages[code]), {
+    statusCode: 503, code, errorType: `/Errors/${code}`
+  });
+}
+
+/** @param {unknown} error SDK error @returns {string} Safe category */
+function failureCode(error) {
+  const status = error?.statusCode || error?.errorResponse?.status || error?.response?.status;
+  if ([401, 403].includes(status) || error?.code === 'authorization-denied') {
+    return 'miso_authentication_failed';
+  }
+  if (['ECONNABORTED', 'ETIMEDOUT', 'ERR_CANCELED'].includes(error?.code)) {
+    return 'miso_timeout';
+  }
+  return 'miso_unreachable';
+}
+
+/** SDK resource ownership and fail-closed application state. */
+class RuntimeController {
+  /** @param {Object} runtime SDK runtime */
+  constructor(runtime) {
+    this.runtime = runtime;
+    this.unsubscribe = runtime.onInvalidated(reason => {
+      this.unavailable = reason === 'authorization-denied'
+        ? 'miso_authentication_failed' : 'miso_runtime_unavailable';
+      this.abort?.abort();
+    });
+  }
+
+  /** @returns {void} Throws when the SDK snapshot is unavailable */
+  assertAvailable() {
+    if (this.unavailable) throw runtimeError(this.unavailable);
+    try {
+      this.runtime.secrets.get('');
+    } catch {
+      throw runtimeError(this.unavailable || 'miso_runtime_unavailable');
+    }
+  }
+
+  /** @returns {Object} Initialized client */
+  getClient() {
+    this.assertAvailable();
+    return this.runtime.client;
+  }
+
+  /** @returns {Promise<void>} Idempotent cleanup */
+  close() {
+    if (!this.closing) {
+      this.unavailable = this.unavailable || 'miso_runtime_unavailable';
+      this.abort?.abort();
+      this.unsubscribe();
+      this.closing = Promise.resolve().then(() => this.runtime.close()).catch(() => {
+        throw runtimeError('miso_runtime_unavailable');
+      });
+    }
+    return this.closing;
+  }
+
+  /** @returns {Promise<void>} Fresh, coalesced token proof; never caches success */
+  health() {
+    this.assertAvailable();
+    if (!this.pending) {
+      this.abort = new AbortController();
+      this.pending = runProbe(this.runtime.client, this.abort,
+        () => this.assertAvailable(), code => {
+          this.unavailable = code;
+          void this.close().catch(() => {});
+        }, () => {
+          this.pending = undefined;
+        });
+    }
+    return this.pending;
+  }
+}
+
+/** @param {Object} runtime SDK runtime @returns {RuntimeController} Consumer controls */
+function createRuntimeController(runtime) {
+  return new RuntimeController(runtime);
+}
+
+/**
+ * Coalesce until transport settles, including SDK-owned token acquisition after a deadline.
+ * @param {Object} client SDK client
+ * @param {AbortController} abort Cancellation
+ * @param {Function} assertAvailable Runtime guard
+ * @param {Function} invalidate Terminal rejection
+ * @param {Function} settled Release in-flight work
+ * @returns {Promise<void>} Bounded health result
+ */
+function runProbe(client, abort, assertAvailable, invalidate, settled) {
+  let timer;
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      abort.abort(); reject(runtimeError('miso_timeout'));
+    }, 3000);
+  });
+  const request = validateMisoApplicationToken(client, abort.signal).then(() => {
+    assertAvailable();
+  }).catch(error => {
+    let code = failureCode(error);
+    try {
+      assertAvailable();
+    } catch (unavailable) {
+      code = unavailable.code;
+    }
+    if (code === 'miso_authentication_failed') invalidate(code);
+    throw runtimeError(code);
+  }).finally(() => {
+    clearTimeout(timer); settled();
+  });
+  return Promise.race([request, deadline]);
+}
+
+/** @param {Function} [init] SDK factory for tests @returns {Promise<Object>} Runtime controls */
+async function initializeBuilderMisoRuntime(init) {
+  if (activeRuntime) throw runtimeError('miso_runtime_unavailable');
+  const factory = init || require('@aifabrix/miso-client/bootstrap').initSecrets;
+  try {
+    activeRuntime = createRuntimeController(await factory());
+    return activeRuntime;
+  } catch {
+    throw runtimeError('miso_runtime_unavailable');
+  }
+}
+
+/** @returns {Object} Active guarded runtime */
+function getBuilderMisoRuntime() {
+  if (!activeRuntime) throw runtimeError('miso_runtime_unavailable');
+  return activeRuntime;
+}
+
+/** @returns {Promise<void>} Close and release process-owned runtime */
+async function closeBuilderMisoRuntime() {
+  const current = activeRuntime;
+  activeRuntime = undefined;
+  await current?.close();
+}
+
+/** @param {boolean} [ready] Readiness response @returns {Promise<Object>} Healthy payload */
+async function checkBuilderMisoHealth(ready = false) {
+  await getBuilderMisoRuntime().health();
+  return ready
+    ? { status: 'ready', dataplaneUrl: process.env.DATAPLANE_URL || null }
+    : { status: 'ok' };
+}
+
+module.exports = {
+  initializeBuilderMisoRuntime, getBuilderMisoRuntime, closeBuilderMisoRuntime,
+  checkBuilderMisoHealth, createRuntimeController
+};

package/lib/programmatic/openapi-descriptions.js

@@ -213,14 +213,14 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
     tags: ['repository']
   },
   health: {
-    summary: 'Liveness probe',
+    summary: 'Application-token health probe',
     description:
-      'Returns ok when the builder-api process is running. Portal availability probe. Empty channel catalog is not a down signal. No authentication.',
+      'Returns ok only after Miso accepts the application client token. Returns 503 when authentication, runtime validity or connectivity fails. No caller authentication; user credentials cannot substitute for the application token.',
     tags: ['infra']
   },
   ready: {
     summary: 'Readiness probe',
-    description: 'Returns ready with configured dataplaneUrl. Does not verify Dataplane connectivity in V1.',
+    description: 'Verifies the application client token with Miso and returns ready with configured dataplaneUrl. Returns 503 for an unusable token or unavailable Miso runtime. Does not verify Dataplane connectivity.',
     tags: ['infra']
   },
   getBuilderHelp: {

package/lib/programmatic/openapi-schema-descriptions-core.js

@@ -113,11 +113,11 @@ const CORE_SCHEMA_DESCRIPTIONS = {
     deleted: 'Always true when the workspace folder was removed.'
   },
   HealthData: {
-    _schema: 'Liveness probe payload when the builder-api process is running.',
-    status: 'Always ok for successful liveness checks.'
+    _schema: 'Health payload after Miso accepts the application client token.',
+    status: 'Always ok after successful application-token validation.'
   },
   ReadyData: {
-    _schema: 'Readiness probe payload; does not verify Dataplane connectivity in V1.',
+    _schema: 'Readiness after Miso application-token validation; does not verify Dataplane connectivity.',
     status: 'Always ready when the service accepts traffic.',
     dataplaneUrl: 'Configured dev Dataplane base URL, or null when unset.'
   },

package/lib/programmatic/openapi-spec.js

@@ -68,7 +68,8 @@ function buildStandardErrorResponses() {
     408: problemResponseContent('Request exceeded capability timeout.'),
     409: problemResponseContent('Workspace lock held by another in-flight operation.'),
     413: problemResponseContent('Request body exceeds MAX_BODY_BYTES.'),
-    500: problemResponseContent('Unexpected server error.')
+    500: problemResponseContent('Unexpected server error.'),
+    503: problemResponseContent('Miso application authentication failed, token check timed out, or runtime/Controller unavailable. Safe failure category appears in type.')
   };
 }
 

package/lib/programmatic/route-handler-map.js

@@ -8,6 +8,7 @@
 
 'use strict';
 
+const { checkBuilderMisoHealth } = require('./builder-miso-runtime');
 const { buildContext } = require('./route-handlers-context');
 const { listSystems, createSystem, getSystemManifest, deleteSystem } = require('./workspace-ops');
 const { persistSuppliedOpenApi } = require('./persist-supplied-openapi');
@@ -230,8 +231,8 @@ const HANDLER_MAP = {
   getRepositoryStatus: (params, auth) => getRepositoryStatus(buildContext(auth, params.systemKey)),
   runRepositoryDispatchPipeline: (params, auth, body) =>
     runRepositoryDispatchPipeline(buildContext(auth, params.systemKey), body),
-  health: () => ({ status: 'ok' }),
-  ready: () => ({ status: 'ready', dataplaneUrl: process.env.DATAPLANE_URL || null }),
+  health: () => checkBuilderMisoHealth(),
+  ready: () => checkBuilderMisoHealth(true),
   getBuilderHelp: (_params, _auth, _body, query) => handleGetBuilderHelp(query || {}),
   getEvidenceMetadata: (params, auth) =>
     getEvidenceMetadata(buildContext(auth, '_evidence'), params.roleKey),

package/lib/role-assistant/test-cases-search.js

@@ -142,6 +142,9 @@ function evaluateSearchExpectations(expectedSearch, observation) {
 
 function skillsResourceEntry(skillsPayload, resourceType) {
   const root = skillsEnvelope(skillsPayload) || asObject(skillsPayload);
+  if (String(root.resourceType || '').trim() === resourceType) {
+    return root;
+  }
   const rts = asObject(asObject(root).search).resourceTypes;
   return asObject(asObject(rts)[resourceType]);
 }

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

@@ -0,0 +1,125 @@
+/**
+ * Run one published Role Assistant case as an explicitly selected subject.
+ *
+ * @fileoverview Async test-job isolation for the Role Assistant CLI
+ */
+
+'use strict';
+
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { resolveUserIdOrEmail } = require('../identity/resolve-user-id');
+const {
+  enqueueRoleAssistantTestJob,
+  getRoleAssistantTestJob
+} = require('../api/role-assistant-test-job.api');
+const { roleAssistantSystemKey } = require('../utils/role-assistant-paths');
+
+function selectedSubject(opts) {
+  const ids = Array.isArray(opts.subjectUserId)
+    ? opts.subjectUserId.map((value) => String(value || '').trim()).filter(Boolean)
+    : [];
+  const emails = Array.isArray(opts.subjectEmail)
+    ? opts.subjectEmail.map((value) => String(value || '').trim()).filter(Boolean)
+    : [];
+  if (ids.length + emails.length > 1) {
+    throw new Error('Role Assistant case execution accepts exactly one isolation subject.');
+  }
+  return { userId: ids[0] || '', email: emails[0] || '' };
+}
+
+function hasRoleAssistantTestSubject(opts) {
+  const subject = selectedSubject(opts);
+  return Boolean(subject.userId || subject.email);
+}
+
+async function resolveSubjectUserId(opts, authConfig) {
+  const subject = selectedSubject(opts);
+  if (subject.userId) {
+    return subject.userId;
+  }
+  const controllerUrl = await resolveControllerUrl();
+  return resolveUserIdOrEmail(controllerUrl, authConfig, subject.email);
+}
+
+function waitFor(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function pollJob(roleKey, authContext, jobId, opts) {
+  const timeoutMs = Number(opts.pollTimeoutMs) || 180000;
+  const intervalMs = Number(opts.pollIntervalMs) || 750;
+  const startedAt = Date.now();
+  let job = null;
+  while (Date.now() - startedAt < timeoutMs) {
+    job = await getRoleAssistantTestJob(
+      authContext.dataplaneUrl,
+      authContext.authConfig,
+      roleAssistantSystemKey(roleKey),
+      jobId
+    );
+    const status = String(job?.status || '').trim().toLowerCase();
+    if (['completed', 'failed', 'cancelled'].includes(status)) {
+      return job;
+    }
+    await waitFor(intervalMs);
+  }
+  throw new Error(`Role Assistant test job ${jobId} did not finish within ${timeoutMs} ms.`);
+}
+
+function evaluationFromJobCase(roleCase, job, row, fallbackJobId = null) {
+  const assertions = Array.isArray(row?.assertions)
+    ? row.assertions.map((assertion) => ({
+      ...assertion,
+      passed: String(assertion?.kind || '').toLowerCase() !== 'fail'
+    }))
+    : [];
+  return {
+    caseId: row?.caseId || roleCase.caseId,
+    sourceFile: roleCase.sourceFile || null,
+    passed: row?.passed === true,
+    lifecycleState: row?.lifecycleState || String(job?.status || 'failed'),
+    assertions,
+    failedAssertions: assertions.filter((assertion) => assertion.passed === false),
+    warnings: assertions.filter((assertion) => assertion.kind === 'warn'),
+    execution: {
+      processExecutionId: row?.processExecutionId || null,
+      finalStatus: row?.lifecycleState || job?.status || null,
+      waitReason: null,
+      interactions: [],
+      workResultError: job?.errorMessage || null,
+      testJobId: job?.jobId || job?.id || fallbackJobId || null
+    }
+  };
+}
+
+async function runPublishedCaseAsSubject(roleKey, roleCase, opts, authContext) {
+  const subjectUserId = await resolveSubjectUserId(opts, authContext.authConfig);
+  const accepted = await enqueueRoleAssistantTestJob(
+    authContext.dataplaneUrl,
+    authContext.authConfig,
+    roleAssistantSystemKey(roleKey),
+    { caseId: roleCase.caseId, subjectUserId }
+  );
+  const jobId = String(accepted?.jobId || '').trim();
+  if (!jobId) {
+    throw new Error('Role Assistant test job enqueue did not return jobId.');
+  }
+  const job = await pollJob(roleKey, authContext, jobId, opts);
+  const row = Array.isArray(job?.cases)
+    ? job.cases.find((candidate) => candidate?.caseId === roleCase.caseId)
+    : null;
+  if (!row) {
+    throw new Error(
+      job?.errorMessage ||
+        `Published Role Assistant case '${roleCase.caseId}' returned no result in job ${jobId}.`
+    );
+  }
+  return evaluationFromJobCase(roleCase, job, row, jobId);
+}
+
+module.exports = {
+  hasRoleAssistantTestSubject,
+  runPublishedCaseAsSubject,
+  evaluationFromJobCase,
+  selectedSubject
+};

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

@@ -17,7 +17,7 @@ const {
   wantsSkillsOnlyPath
 } = require('./test-runner-workhub-helpers');
 
-function operationKeys(spec) {
+function directOperationKeys(spec) {
   const raw = Array.isArray(spec && spec.operations) ? spec.operations : [];
   const keys = [];
   for (const item of raw) {
@@ -33,6 +33,42 @@ function operationKeys(spec) {
   return keys;
 }
 
+function operationClassKeys(spec) {
+  const classes = spec && typeof spec.operationClasses === 'object'
+    ? spec.operationClasses
+    : {};
+  const keys = [];
+  for (const rows of Object.values(classes)) {
+    if (!Array.isArray(rows)) {
+      continue;
+    }
+    for (const row of rows) {
+      const key = String(row || '').trim();
+      if (key && !keys.includes(key)) {
+        keys.push(key);
+      }
+    }
+  }
+  return keys;
+}
+
+function operationKeys(spec) {
+  return [...new Set([...directOperationKeys(spec), ...operationClassKeys(spec)])];
+}
+
+function skillsRequestOptions(testCase) {
+  if (!wantsSkillsOnlyPath(testCase)) {
+    return undefined;
+  }
+  const input = resolveInput(testCase);
+  const resourceType = String(input.resourceType || '').trim();
+  const operation = String(input.operation || '').trim();
+  if (operation) {
+    return { detail: 'operation', resourceType, operation };
+  }
+  return resourceType ? { detail: 'resource', resourceType } : undefined;
+}
+
 function pickResourceType(skillsPayload, operation) {
   const rts = resourceTypesMap(skillsPayload);
   const keys = Object.keys(rts);
@@ -139,7 +175,12 @@ async function runSearchCaseLifecycle(roleKey, testCase, runtimeContext) {
     throw new Error('Role assistant search case requires dataplane auth context.');
   }
   const roleRef = resolveRoleRef(roleKey, testCase);
-  const skillsRes = await getWorkSkills(dataplaneUrl, authConfig, roleRef);
+  const skillsRes = await getWorkSkills(
+    dataplaneUrl,
+    authConfig,
+    roleRef,
+    skillsRequestOptions(testCase)
+  );
   if (wantsSkillsOnlyPath(testCase)) {
     return searchLifecycleResult(roleKey, testCase, roleRef, skillsRes, null, null);
   }
@@ -157,6 +198,7 @@ module.exports = {
   wantsSearchPath,
   wantsSkillsOnlyPath,
   operationKeys,
+  skillsRequestOptions,
   pickResourceType,
   resolveRoleRef,
   buildSearchArguments,