@aifabrix/builder 2.58.0 → 2.60.0

package/lib/agent-kit/setup-managed.js

@@ -0,0 +1,79 @@
+/** Read the provisioned user config for zero-argument managed onboarding. */
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const os = require('os');
+const yaml = require('js-yaml');
+const config = require('../core/config');
+const { normalizeSetup } = require('./setup-context');
+
+function assertConfigFile(file) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error('Managed config.yaml is missing. Ask your administrator to provision this workspace.');
+    }
+    throw error;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error('Managed config.yaml must be a regular file. Ask your administrator to repair it.');
+  }
+}
+
+function assertManagedKeys(file) {
+  let raw;
+  try {
+    raw = yaml.load(fs.readFileSync(file, 'utf8'));
+  } catch {
+    throw new Error('Managed config.yaml is invalid. Ask your administrator to repair it.');
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) ||
+      !['controller', 'environment', 'codingPlatform'].every(key => Object.hasOwn(raw, key))) {
+    throw new Error('Managed config.yaml needs controller, environment, and codingPlatform. Ask your administrator to repair it.');
+  }
+}
+
+function assertManagedOverrides(options) {
+  if (options.code !== undefined || options.controllerUrl !== undefined) {
+    throw new Error('Managed onboarding uses the provisioned Controller; --code and --controller overrides are not allowed.');
+  }
+  if (options.repo !== undefined && options.name !== undefined) {
+    throw new Error('Use either --repo owner/name or --name folder for managed onboarding.');
+  }
+  if (options.coding !== undefined && !['claude', 'codex', 'cursor'].includes(options.coding)) {
+    throw new Error('Use --coding claude, codex, or cursor.');
+  }
+}
+
+function assertManagedValues(values) {
+  if (!values || typeof values !== 'object' || typeof values.controller !== 'string' ||
+      typeof values.environment !== 'string' || !values.environment.trim() ||
+      !['codex', 'claude', 'cursor'].includes(values.codingPlatform)) {
+    throw new Error('Managed config.yaml needs controller, environment, and codingPlatform. Ask your administrator to repair it.');
+  }
+}
+
+async function managedSetupOptions(options = {}) {
+  assertManagedOverrides(options);
+  const file = options.configFile || config.CONFIG_FILE;
+  assertConfigFile(file);
+  assertManagedKeys(file);
+  const values = await (options.getConfig || config.getConfig)();
+  assertManagedValues(values);
+  let context;
+  try {
+    context = normalizeSetup({ controllerUrl: values.controller,
+      code: options.coding || values.codingPlatform, managed: true });
+  } catch {
+    throw new Error('Managed config.yaml has an invalid Controller URL or coding platform. Ask your administrator to repair it.');
+  }
+  const sshHost = values['sync-ssh-host'];
+  const remoteHost = typeof sshHost === 'string' && /^[a-z0-9.-]+$/i.test(sshHost)
+    ? sshHost : os.hostname();
+  return { controllerUrl: context.controller, code: context.code,
+    remoteHost, managed: true };
+}
+
+module.exports = { managedSetupOptions, assertConfigFile, assertManagedKeys };

package/lib/agent-kit/setup-process.js

@@ -0,0 +1,42 @@
+/** Process boundary for onboarding: argv only and no credential-bearing errors. */
+'use strict';
+
+const { execFileSync, spawnSync } = require('child_process');
+
+function capture(bin, args, options = {}) {
+  return (options.execFileSync || execFileSync)(bin, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+}
+
+function checked(bin, args, message, options = {}) {
+  try {
+    return capture(bin, args, options);
+  } catch {
+    throw new Error(message);
+  }
+}
+
+function interactive(bin, args, message, options = {}) {
+  const result = (options.spawnSync || spawnSync)(bin, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    stdio: 'inherit'
+  });
+  if (!result || result.error || result.signal || result.status !== 0) {
+    throw new Error(message);
+  }
+}
+
+function available(bin, options = {}) {
+  try {
+    return String(capture('which', [bin], options)).trim();
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { capture, checked, interactive, available };

package/lib/agent-kit/setup-session.js

@@ -0,0 +1,53 @@
+/** Start or reattach only to a session belonging to this workspace and selected agent. */
+'use strict';
+
+const { createHash } = require('crypto');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+const { runStart, hostUserPrefix, resolveRemoteControlName, resolveSessionName } = require('./start');
+const { tmuxSessionExists } = require('./tmux-sessions');
+const { checked, interactive } = require('./setup-process');
+
+function sessionIdentity(context, options = {}) {
+  const key = `${context.target}\n${context.controller}\n${context.code}`;
+  const hash = createHash('sha256').update(key).digest('hex').slice(0, 16);
+  const legacyName = `aifabrix-${context.code}-${hash}`;
+  const name = options.managed && context.code === 'claude'
+    ? resolveSessionName(undefined, context.target) : legacyName;
+  return { name, key, legacyName };
+}
+
+function verifySession(name, key, options) {
+  const saved = String(checked('tmux', ['show-options', '-v', '-t', name, '@aifabrix-setup'],
+    'Cannot verify existing agent session ownership.', options)).trim();
+  if (saved !== key) throw new Error('Existing session ownership does not match. No session was replaced.');
+}
+
+function prepareSession(context, provider, options = {}) {
+  const { name, key, legacyName } = sessionIdentity(context, options);
+  const exec = (bin, args, extra) => (options.execFileSync || execFileSync)(bin, args, { ...extra, env: provider.env });
+  const spawn = (bin, args, extra) => (options.spawnSync || spawnSync)(bin, args, { ...extra, env: provider.env });
+  const opts = { ...options, env: provider.env };
+  if (tmuxSessionExists(name, exec)) {
+    verifySession(name, key, opts);
+  } else if (name !== legacyName && tmuxSessionExists(legacyName, exec)) {
+    verifySession(legacyName, key, opts);
+    checked('tmux', ['rename-session', '-t', legacyName, name],
+      'Could not rename the existing agent session. Inspect agent-kit list before retrying.', opts);
+  } else {
+    const remoteControlName = context.code === 'claude'
+      ? resolveRemoteControlName(hostUserPrefix(options), path.basename(context.target)) : undefined;
+    runStart({ app: context.code, cwd: context.target, name, detach: true, skipApproveAll: true,
+      binary: provider.binary, remoteControlName, execFileSync: exec, spawnSync: spawn });
+    checked('tmux', ['set-option', '-t', name, '@aifabrix-setup', key],
+      'Agent started but its session could not be marked. Inspect agent-kit list before retrying.', opts);
+  }
+  return name;
+}
+
+function attachSession(name, provider, options = {}) {
+  interactive('tmux', ['attach-session', '-t', `=${name}`],
+    'Could not attach the agent session. Inspect aifabrix agent-kit list.', { ...options, env: provider.env });
+}
+
+module.exports = { prepareSession, attachSession, sessionIdentity };

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

@@ -0,0 +1,52 @@
+/** Machine-local onboarding progress, outside the repository and without credentials. */
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { randomUUID } = require('crypto');
+const { assertDirectory } = require('./setup-context');
+
+function readState(file) {
+  if (!fs.existsSync(file)) return null;
+  if (!fs.lstatSync(file).isFile()) throw new Error('Onboarding state must be a regular file.');
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    throw new Error('Onboarding state is invalid; preserve the workspace and inspect its state file.');
+  }
+}
+
+function acquireWorkspace(context) {
+  const dir = path.join(context.root, '.aifabrix-onboarding');
+  assertDirectory(dir);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, `${context.name}.json`);
+  const lock = `${file}.lock`;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(lock, 'wx', 0o600);
+  } catch {
+    throw new Error(`Workspace setup is locked. If no setup is running, remove the stale lock: ${lock}`);
+  }
+  fs.closeSync(descriptor);
+  const release = () => fs.unlinkSync(lock);
+  try {
+    const state = readState(file);
+    if (state && (state.controller !== context.controller || state.fullName !== context.fullName || state.target !== context.target)) {
+      throw new Error('This workspace belongs to a different Controller or repository. Use a different AI Fabrix work directory.');
+    }
+    return { file, release, state: state || { controller: context.controller, fullName: context.fullName, target: context.target } };
+  } catch (error) {
+    release();
+    throw error;
+  }
+}
+
+function saveProgress(progress, patch) {
+  Object.assign(progress.state, patch);
+  const temporary = `${progress.file}.${randomUUID()}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(progress.state, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+  fs.renameSync(temporary, progress.file);
+}
+
+module.exports = { acquireWorkspace, saveProgress };

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

@@ -0,0 +1,113 @@
+/** Local workspace preparation and optional GitHub clone/create with safe resumability. */
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const { runInit } = require('./init');
+const { runInstall, runUpdate } = require('./run');
+const { resolveGitRoot } = require('./repo-guard');
+const { ensureInitialCommit } = require('./scm/git');
+const { capture, checked } = require('./setup-process');
+const github = require('./setup-github');
+const { saveProgress } = require('./setup-state');
+
+function validateExisting(context, progress, options) {
+  if (progress.state.initializing || progress.state.cloning) {
+    throw new Error('Workspace initialization or clone was interrupted. Inspect the preserved folder and onboarding state before retrying.');
+  }
+  if (!fs.existsSync(context.target) || fs.readdirSync(context.target).length === 0) return false;
+  if (resolveGitRoot(context.target) !== context.target) throw new Error('Workspace must be its own Git repository.');
+  if (context.fullName) {
+    const origin = github.originIdentity(context.target, options);
+    if (origin || !progress.state.initialized) github.assertOrigin(context, options);
+  } else if (!progress.state.initialized || github.originIdentity(context.target, options)) {
+    throw new Error('Local workspace is not an existing local-only onboarding workspace. No files were changed.');
+  }
+  return true;
+}
+
+function checkKit(result) {
+  if (result.conflicts && result.conflicts.length) {
+    throw new Error('Agent Kit files have local conflicts. Resolve them with agent-kit status/update before retrying setup.');
+  }
+}
+
+function initializeLocal(context, progress, options) {
+  // Persist the operation first so an interrupted partial init cannot be adopted on retry.
+  saveProgress(progress, { initializing: true });
+  runInit({ nameOrPath: context.target, host: context.code, noRemote: true, approveAll: false,
+    interactive: false, execFileSync: options.execFileSync });
+  saveProgress(progress, { initialized: true, initializing: false });
+}
+
+function finishNewRemote(context, progress, options) {
+  const opts = { ...options, cwd: context.target };
+  if (!progress.state.initialCommit) {
+    ensureInitialCommit(context.target, opts);
+    const initialCommit = String(capture('git', ['rev-parse', 'HEAD'], opts)).trim();
+    saveProgress(progress, { initialCommit });
+  }
+  if (!progress.state.remoteCreated) {
+    github.createRepository(context.fullName, options);
+    saveProgress(progress, { remoteCreated: true });
+  }
+  if (!github.originIdentity(context.target, options)) {
+    checked('git', ['remote', 'add', 'origin', `https://github.com/${context.fullName}.git`],
+      'Could not configure the GitHub origin. Local files are preserved.', opts);
+  }
+  github.pushInitialCommit(context, progress, saveProgress, options);
+}
+
+function cloneWorkspace(context, progress, options) {
+  if (progress.state.initialized) throw new Error('Previously initialized workspace is missing. Restore it before retrying.');
+  saveProgress(progress, { cloning: true });
+  github.cloneRepository(context, options);
+  saveProgress(progress, { initialized: true, cloning: false });
+}
+
+function prepareGithub(context, progress, options, existing) {
+  if (existing && github.originIdentity(context.target, options)) {
+    if (progress.state.remoteCreated && !progress.state.pushed) finishNewRemote(context, progress, options);
+    return false;
+  }
+  const remote = github.lookupRepository(context.fullName, options);
+  if (!remote) {
+    if (progress.state.remoteCreated) {
+      throw new Error('The existing remote is no longer accessible. Restore access before retrying.');
+    }
+    if (existing && !progress.state.initialCommit) {
+      throw new Error('Initialization stopped before recording the initial commit. Inspect the preserved workspace before creating its remote.');
+    }
+    if (!existing) initializeLocal(context, progress, options);
+    finishNewRemote(context, progress, options);
+    return true;
+  }
+  if (!existing) {
+    cloneWorkspace(context, progress, options);
+  } else if (!progress.state.remoteCreated) {
+    throw new Error('Repository appeared during creation. Inspect the local workspace and remote before connecting them.');
+  }
+  if (progress.state.remoteCreated && !progress.state.pushed) finishNewRemote(context, progress, options);
+  github.assertOrigin(context, options);
+  return false;
+}
+
+function prepareWorkspace(context, progress, options = {}) {
+  const existing = validateExisting(context, progress, options);
+  let installed = false;
+  if (context.fullName) installed = prepareGithub(context, progress, options, existing);
+  else if (!existing) {
+    if (progress.state.initialized) throw new Error('Previously initialized workspace is missing. Restore it before retrying.');
+    initializeLocal(context, progress, options);
+    installed = true;
+  }
+  if (!installed) {
+    const install = options.managed ? runUpdate : runInstall;
+    const preview = install({ cwd: context.target, host: context.code, approveAll: false, dryRun: true });
+    checkKit(preview);
+    checkKit(install({ cwd: context.target, host: context.code, approveAll: false }));
+  }
+  if (!fs.existsSync(context.target)) throw new Error('Workspace preparation did not create its directory.');
+  saveProgress(progress, { initialized: true, ready: true });
+}
+
+module.exports = { validateExisting, prepareWorkspace, checkKit };

package/lib/agent-kit/setup.js

@@ -0,0 +1,87 @@
+/** Portable local-first agent onboarding. */
+'use strict';
+
+const { randomUUID } = require('crypto');
+const logger = require('../utils/logger');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
+const { auditLog } = require('../core/audit-logger');
+const { normalizeSetup, preflight, resolveWork } = require('./setup-context');
+const { acquireWorkspace } = require('./setup-state');
+const { ensureController, ensureGithubLogin, ensureProvider } = require('./setup-auth');
+const { ensureGitIdentity } = require('./git-identity');
+const { prepareWorkspace, validateExisting } = require('./setup-workspace');
+const { prepareSession, attachSession } = require('./setup-session');
+const { managedSetupOptions } = require('./setup-managed');
+
+async function authenticate(context, options, setPhase) {
+  setPhase('controller-login');
+  logger.log('Connecting to AI Fabrix...');
+  await ensureController(context);
+  if (context.fullName) {
+    setPhase('github-login');
+    ensureGithubLogin(options);
+    // Commits need an author. The login token supplies the default; the user can change it.
+    await ensureGitIdentity({ ...options, interactive: options.interactive !== false });
+  }
+  if (context.code === 'cursor') return null;
+  setPhase('agent-login');
+  return ensureProvider(context, options);
+}
+
+async function prepareOnboarding(context, progress, options) {
+  const correlationId = randomUUID();
+  let provider;
+  let session;
+  let phase = 'workspace-check';
+  try {
+    validateExisting(context, progress, options);
+    provider = await authenticate(context, options, value => {
+      phase = value;
+    });
+    phase = 'workspace';
+    prepareWorkspace(context, progress, options);
+    if (!options.managed || context.code === 'claude') {
+      phase = 'agent-start';
+      session = prepareSession(context, provider, options);
+    }
+    await auditLog('AUDIT', 'Agent workspace onboarding ready', { correlationId, path: context.target, agent: context.code });
+  } catch (error) {
+    await auditLog('ERROR', 'Agent workspace onboarding failed', { correlationId, phase });
+    throw error;
+  } finally {
+    progress.release();
+  }
+  return { session, provider };
+}
+
+async function runSetup(options = {}) {
+  const input = normalizeSetup(options);
+  preflight(input, options);
+  const context = await resolveWork(input, options);
+  const progress = acquireWorkspace(context);
+  const { session, provider } = await prepareOnboarding(context, progress, options);
+  logger.log(formatSuccessLine(`Workspace ready: ${context.target}`));
+  if (options.managed) {
+    const host = options.remoteHost || new URL(context.controller).hostname;
+    if (context.code === 'claude') {
+      logger.log(`Claude Code running in tmux session ${session}. Attach: tmux attach -t ${session}`);
+      logger.log(`Next: Open Claude Code Remote Control on ${host}, or attach to ${session}.`);
+      return { path: context.target, code: context.code, session };
+    }
+    const next = {
+      cursor: `In Cursor, connect with Remote SSH to ${host}, then open ${context.target}.`,
+      codex: `In Codex, add the SSH project ${context.target} on ${host}.`
+    }[context.code];
+    logger.log(`Next: ${next} Say "Hi" to begin.`);
+  } else {
+    attachSession(session, provider, options);
+  }
+  return { path: context.target, code: context.code, session };
+}
+
+async function runManagedOnboarding(options = {}) {
+  const managed = await managedSetupOptions(options);
+  return runSetup({ ...options, ...managed });
+}
+
+module.exports = { runSetup, runManagedOnboarding };

package/lib/agent-kit/start.js

@@ -116,6 +116,27 @@ function claudeInnerArgs(p) {
   ]);
 }
 
+/**
+ * POSIX single-quote escaping for a value sent to a shell via tmux send-keys.
+ * @param {string} value - Raw value
+ * @returns {string} Quoted value
+ */
+function shellQuote(value) {
+  const escaped = String(value).split('\'').join('\'\\\'\'');
+  return `'${escaped}'`;
+}
+
+/**
+ * Codex authenticates inside the session, not in the window that launched it. Running it as the
+ * tmux session command makes the session end with the sign-in process, so the shell owns the
+ * window and codex is started inside it with send-keys.
+ * @param {object} p - Start parameters
+ * @returns {string} Shell command to run inside the session
+ */
+function codexStartCommand(p) {
+  return p.binary ? `exec ${shellQuote(p.binary)}` : 'exec codex';
+}
+
 /**
  * @param {object} p
  * @returns {object}
@@ -127,12 +148,17 @@ function buildTmuxSpec(p) {
     ? ['new-session', '-d', '-s', p.session, '-c', p.cwd]
     : ['new-session', '-s', p.session, '-c', p.cwd];
   const remote = p.app === 'claude' && p.remoteControl;
+  // codex: shell owns the window, codex starts inside it (see codexStartCommand).
+  const launchArgs = p.app === 'codex'
+    ? [...mode]
+    : [...mode, ...(p.binary ? ['env', p.binary] : [spec.bin]), ...extra];
   return {
     bin: 'tmux',
-    args: [...mode, spec.bin, ...extra],
+    args: launchArgs,
     session: p.session,
     appBin: spec.bin,
     needTmux: true,
+    innerCommand: p.app === 'codex' ? codexStartCommand(p) : undefined,
     remoteControlName: remote ? p.remoteControlName : undefined,
     remoteControlPrefix: remote ? p.remoteControlPrefix : undefined
   };
@@ -287,16 +313,17 @@ function resolveStartContext(options) {
   const cwd = resolveGitRoot(options.cwd || process.cwd());
   const session = resolveSessionName(options.name, cwd);
   const remoteControlPrefix = hostUserPrefix(options);
-  const remoteControlName = resolveRemoteControlName(remoteControlPrefix, session);
+  const remoteControlName = options.remoteControlName || resolveRemoteControlName(remoteControlPrefix, session);
   const remoteControl = options.remoteControl !== false;
   const spec = buildLaunchSpec({
     app, cwd, session, remoteControlPrefix, remoteControlName,
-    detach: Boolean(options.detach), remoteControl
+    detach: Boolean(options.detach), remoteControl, binary: options.binary
   });
   spec.cwd = cwd;
   const remoteSpec = app === 'codex' && remoteControl
     ? buildCodexRemoteSpec(cwd)
     : undefined;
+  if (remoteSpec && options.binary) remoteSpec.bin = options.binary;
   return { app, cwd, session, remoteControl, spec, remoteSpec };
 }
 
@@ -332,6 +359,22 @@ function executeStart(options, context, execute) {
     startCodexRemote(options, context.remoteSpec);
   }
   spawnLaunch(options, context.spec);
+  sendInnerCommand(options, context.spec);
+}
+
+/**
+ * Starts the agent inside an existing session window. Only codex uses this; the session must exist
+ * first, which is why it runs after the launch.
+ * @param {object} options - Start options
+ * @param {object} spec - Launch spec
+ * @returns {void}
+ */
+function sendInnerCommand(options, spec) {
+  if (!spec.innerCommand) {
+    return;
+  }
+  const exec = options.execFileSync || execFileSync;
+  exec('tmux', ['send-keys', '-t', `=${spec.session}`, spec.innerCommand, 'Enter'], { stdio: 'inherit' });
 }
 
 /**
@@ -362,6 +405,8 @@ function runStart(options) {
 
 module.exports = {
   START_APPS,
+  codexStartCommand,
+  sendInnerCommand,
   normalizeStartApp,
   sanitizeSessionName,
   resolveSessionName,

package/lib/agent-kit/tmux-sessions.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const { execFileSync } = require('child_process');
+const { execFileSync, spawnSync } = require('child_process');
 
 const LIST_FORMAT = [
   '#{session_name}',
@@ -66,7 +66,7 @@ function isNoTmuxServer(error) {
     .filter(Boolean)
     .map(String)
     .join(' ');
-  return /no server running|failed to connect to server/i.test(message);
+  return /no server running|failed to connect to server|error connecting to .*\/tmux-\d+\/.*No such file or directory/i.test(message);
 }
 
 /**
@@ -150,6 +150,22 @@ function runKill(options) {
   return { command: 'kill', session, killed: true };
 }
 
+function runAttach(options) {
+  const exec = options.execFileSync || execFileSync;
+  const session = normalizeExactSessionName(options.name);
+  requireTmux(exec);
+  if (!tmuxSessionExists(session, exec)) {
+    throw new Error(`tmux session "${session}" is not running. Run: aifabrix agent-kit list`);
+  }
+  const insideTmux = Boolean((options.env || process.env).TMUX);
+  const args = [insideTmux ? 'switch-client' : 'attach-session', '-t', `=${session}`];
+  const result = (options.spawnSync || spawnSync)('tmux', args, { stdio: 'inherit' });
+  if (!result || result.error || result.signal || result.status !== 0) {
+    throw new Error(`Could not attach to tmux session "${session}".`);
+  }
+  return { command: 'attach', session, attached: true };
+}
+
 module.exports = {
   LIST_FORMAT,
   hasOnPath,
@@ -159,5 +175,6 @@ module.exports = {
   tmuxSessionExists,
   parseSessionLine,
   runList,
-  runKill
+  runKill,
+  runAttach
 };

package/lib/api/dev.api.js

@@ -198,7 +198,7 @@ async function listUsers(serverUrl, clientCertPem, serverCaPem) {
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
- * @param {Object} body - CreateUserDto: developerId, name, email, optional groups (admin | secret-manager | secret-reader | developer | docker)
+ * @param {Object} body - CreateUserDto: developerId, name, email, optional groups (admin | secret-manager | secret-reader | developer | docker | integrator)
  * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object>} UserResponseDto
  */

package/lib/api/miso-health.api.js

@@ -0,0 +1,26 @@
+/**
+ * Application-token health proof through the public Miso SDK transport.
+ * @fileoverview Never reads or returns the application token itself.
+ */
+'use strict';
+
+/**
+ * POST /api/v1/auth/validate-client-token
+ * @requiresPermission {Controller} Client token
+ * @param {Object} client Initialized runtime client
+ * @param {AbortSignal} signal Probe cancellation
+ * @returns {Promise<void>} Resolves only for an authenticated application
+ */
+async function validateMisoApplicationToken(client, signal) {
+  const response = await client.requestWithAuthStrategy(
+    'POST', '/api/v1/auth/validate-client-token', { methods: ['client-token'] },
+    {}, { signal, timeout: 3000, maxRedirects: 0 }
+  );
+  if (response?.success === false || response?.data?.authenticated !== true) {
+    const error = new Error('Miso application authentication failed');
+    error.statusCode = 401;
+    throw error;
+  }
+}
+
+module.exports = { validateMisoApplicationToken };

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

@@ -0,0 +1,60 @@
+/**
+ * Dataplane asynchronous Role Assistant test job API.
+ *
+ * @fileoverview Enqueue and poll published Role Assistant cases
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { throwIfApiFailed } = require('./api-response-errors');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+function jobPath(systemIdOrKey, suffix = '') {
+  const key = encodeURIComponent(String(systemIdOrKey || '').trim());
+  return `/api/v1/external/systems/${key}/role-assistant-tests/jobs${suffix}`;
+}
+
+function unwrapJob(res) {
+  const value = unwrapApiData(res);
+  if (value && typeof value === 'object' && !Array.isArray(value) && value.data) {
+    return value.data;
+  }
+  return value;
+}
+
+async function enqueueRoleAssistantTestJob(
+  dataplaneUrl,
+  authConfig,
+  systemIdOrKey,
+  body
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const path = jobPath(systemIdOrKey);
+  const res = await client.post(path, { body, timeoutMs: 60000 });
+  throwIfApiFailed(res, {
+    endpointUrl: `${String(dataplaneUrl || '').replace(/\/$/, '')}${path}`
+  });
+  return unwrapJob(res);
+}
+
+async function getRoleAssistantTestJob(
+  dataplaneUrl,
+  authConfig,
+  systemIdOrKey,
+  jobId
+) {
+  const suffix = `/${encodeURIComponent(String(jobId || '').trim())}`;
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const path = jobPath(systemIdOrKey, suffix);
+  const res = await client.get(path, { timeoutMs: 60000 });
+  throwIfApiFailed(res, {
+    endpointUrl: `${String(dataplaneUrl || '').replace(/\/$/, '')}${path}`
+  });
+  return unwrapJob(res);
+}
+
+module.exports = {
+  enqueueRoleAssistantTestJob,
+  getRoleAssistantTestJob
+};