Skip to content

forcedotcom/sf-skills / plugins/builder/service-itsm/skills/service-itsm-agentic-setup-agentforce-studio-validate

service-itsm-agentic-setup-agentforce-studio-validate

Unverified

Validate the Agentforce for IT Service prerequisites for a Fulfiller or Employee agent, using the Salesforce CLI (sf). The READ-ONLY prerequisite check: it reads the Salesforce Go feature toggles behind the Agentforce for IT Service setup page (Agentforce Studio, the IT Service Fulfiller Template / IT Service Employee Template, Specialized Agent Templates for Employee) via one Connect API call, then a helper script classifies the chosen path into a READY / NOT-READY verdict. It never enables anything; when a toggle is off it hands off to agentforce-studio-configure to enable it. Use when asked to check Agentforce prerequisites, validate the org is ready for an ITSM agent, or verify Agentforce Studio is enabled. Triggers: check agentforce prerequisites, validate agentforce readiness, is my org ready for the fulfiller agent, verify agentforce studio enabled. DO NOT TRIGGER: enabling or turning on the toggles, creating the fulfiller agent (service-itsm-agentic-setup-fulfiller-agent-configure), or CMDB CRUD.

FileKindSize
SKILL.mdskill md16.8 KB
references/cli-invocation.mdmarkdown10.4 KB
scripts/classify-readiness.mjsexecutablescript10.2 KB

scripts/classify-readiness.mjs

View on GitHub
#!/usr/bin/env node
// Deterministic readiness classifier for the Agentforce for IT Service prerequisite check.
//
// Consumes the raw JSON body of a single `sf api request rest` read of the
// Salesforce Go feature-status endpoint and, for a chosen agent path
// (fulfiller | employee), decides whether every required feature toggle is ON.
// This is the deterministic decision table that MUST NOT be interpreted by the
// model in prose (authoring standard A9).
//
// Usage:
//   node classify-readiness.mjs <features-status.json> <agentType> [exitStatus]
//
// <features-status.json> is a FILE PATH to the raw stdout captured from:
//   sf api request rest "/services/data/vXX.0/connect/setup/discovery/features/status" \
//     --method POST --body '{"featureApiNames":[...]}' --target-org <org> > file.json
// The body shape is { items: [ { apiName, status, enableBlockedReasons[],
// dependencyStatuses[] } ] } where status is "ENABLED" | "NOT_ENABLED".
// The file may instead hold the CLI error payload (a JSON array like
// [{"errorCode":"NOT_FOUND",...}]) or be empty when the CLI exited non-zero.
//
// <exitStatus> is the OPTIONAL numeric exit code of the `sf` command ($? in the
// shell). Pass it so the classifier can tell a *confirmed* 404-style "gate not
// wired" (→ CANNOT-CONFIRM) apart from an auth / permission / transport failure
// (→ ERROR, surface the raw response and stop). An empty or unparseable body is
// treated as ERROR, never CANNOT-CONFIRM.
//
// <agentType> is one of: fulfiller | employee. It selects which feature toggles
// are required — fulfiller checks the fulfiller template pref, employee checks
// the requestor + specialized-employee template prefs. Both paths also require
// the shared Agentforce Studio pref and the ITSM parent umbrella.
//
// Emits a single JSON object to stdout:
//   { agentType, readState,
//     features: { <apiName>: { status, signal, enableBlockedReasons, enableable, enableRoute } },
//     verdict, notEnabled: [<apiName>...], enableable: [<apiName>...], reasons: [...], rawError }
// where each signal is PASS | FAIL | CANNOT-CONFIRM | ERROR and verdict is
// READY | NOT-READY | CANNOT-CONFIRM | ERROR. Exit code is always 0 on a usable
// agentType; the verdict is carried in the payload, not the exit status.

import { readFileSync } from 'node:fs';

// Required feature toggles per agent path. The apiNames are the real Salesforce
// Go featureApiNames behind the "Agentforce for IT Service" page toggles.
const STUDIO = 'sales-cloud-agent-studio';                 // "Turn on Agentforce Studio"
const PARENT = 'service-cloud-agentforce-for-itsm';        // "Agentforce for IT Service" umbrella
const FULFILLER = 'service-cloud-it-fulfiller-agent';      // "IT Service Fulfiller"
const REQUESTOR = 'service-cloud-requestor-agent';         // "IT Service Employee"
const SPECIALIZED = 'service-cloud-it-service-employee-agent'; // "Specialized Agent Templates for Employee"

const REQUIRED = {
  fulfiller: [STUDIO, PARENT, FULFILLER],
  employee: [STUDIO, PARENT, REQUESTOR, SPECIALIZED],
};

// Report labels — the authoritative strings these reports render. The two
// agent-template rows intentionally differ from their shorter Salesforce Go
// setup-page toggle caption, the same way the Studio caption "Turn on
// Agentforce Studio" renders as "Agentforce Studio": these toggles enable agent
// *templates*, so their report label carries a deliberate "Template" suffix. By
// design — do not simplify it to the bare caption. It is also distinct from the
// installed agent the agent-configure skills create ("IT Service Fulfiller
// Agent" / "IT Service Employee Agent", no "Template").
const LABEL = {
  [STUDIO]: 'Agentforce Studio',
  [PARENT]: 'Agentforce for IT Service',
  [FULFILLER]: 'IT Service Fulfiller Template',
  [REQUESTOR]: 'IT Service Employee Template',
  [SPECIALIZED]: 'Specialized Agent Templates for Employee',
};

function enableRoute(apiName) {
  return `POST /connect/setup/discovery/feature/${apiName}/enable`;
}

function readJson(path) {
  // { ok:true, data } on a parseable body; { ok:false, empty:true } when the file
  // is missing/empty; { ok:false, empty:false } when it holds non-JSON garbage.
  try {
    const text = readFileSync(path, 'utf8').trim();
    if (!text) return { ok: false, empty: true };
    return { ok: true, data: JSON.parse(text) };
  } catch {
    return { ok: false, empty: false };
  }
}

function asErrorArray(data) {
  // sf api request rest surfaces Connect API errors as an array of
  // {errorCode,message} (or a single such object). Returns [] if not an error body.
  if (Array.isArray(data)) return data.filter((e) => e && (e.errorCode || e.message));
  if (data && (data.errorCode || data.message)) return [data];
  return [];
}

function isNotFoundError(errs) {
  // A 404 / NOT_FOUND / gate-not-wired is the ONLY error shape that maps to
  // "cannot confirm". Auth (401), permission (403), and everything else = ERROR.
  return errs.some((e) => {
    const code = String(e?.errorCode ?? '').toUpperCase();
    const msg = String(e?.message ?? '').toUpperCase();
    return code.includes('NOT_FOUND') || code.includes('NOT_EXIST') ||
      msg.includes('NOT FOUND') || msg.includes('DOES NOT EXIST') ||
      msg.includes('COULD NOT BE FOUND');
  });
}

function errorSnippet(errs) {
  return errs.map((e) => `${e.errorCode ?? 'ERROR'}: ${e.message ?? ''}`.trim()).join(' | ').slice(0, 500);
}

// Returns { readState, statusMap, rawError }:
//   readState 'ok'        → statusMap has per-apiName { status, enableBlockedReasons }
//   readState 'not-wired' → a confirmed 404 (feature-discovery surface not wired)
//   readState 'error'     → empty / auth / permission / transport / unexpected body
function readFeatureStatus(res, exitStatus) {
  if (!res.ok) {
    // Empty or non-JSON body. Never a confirmed 404 → ERROR (surface it, stop).
    const why = res.empty
      ? (Number.isFinite(exitStatus) && exitStatus !== 0
          ? `The read command exited ${exitStatus} with an empty body (auth / permission / transport failure).`
          : 'The read produced an empty body — the response could not be read.')
      : 'The read produced a non-JSON body that could not be parsed.';
    return { readState: 'error', statusMap: null, rawError: why };
  }
  const d = res.data;
  const errs = asErrorArray(d);
  if (errs.length) {
    if (isNotFoundError(errs)) return { readState: 'not-wired', statusMap: null, rawError: null };
    return { readState: 'error', statusMap: null, rawError: errorSnippet(errs) };
  }
  const items = Array.isArray(d?.items) ? d.items : null;
  if (!items) {
    return { readState: 'error', statusMap: null, rawError: 'The response had no "items" array (unexpected shape).' };
  }
  const map = new Map();
  for (const it of items) {
    if (it?.apiName) {
      map.set(it.apiName, {
        status: String(it.status ?? '').toUpperCase(),
        enableBlockedReasons: Array.isArray(it.enableBlockedReasons) ? it.enableBlockedReasons : [],
      });
    }
  }
  return { readState: 'ok', statusMap: map, rawError: null };
}

function classifyFeature(apiName, statusMap) {
  const label = LABEL[apiName] ?? apiName;
  if (!statusMap || !statusMap.has(apiName)) {
    return {
      status: 'UNKNOWN', signal: 'CANNOT-CONFIRM', enableBlockedReasons: [], enableable: false, enableRoute: null,
      reason: `${label} (${apiName}) — no status returned (endpoint not wired / not in response).`,
    };
  }
  const { status, enableBlockedReasons } = statusMap.get(apiName);
  if (status === 'ENABLED') {
    return { status, signal: 'PASS', enableBlockedReasons: [], enableable: false, enableRoute: null, reason: `${label} (${apiName}) → ENABLED.` };
  }
  if (status === 'NOT_ENABLED') {
    const blocked = enableBlockedReasons.length > 0;
    return {
      status, signal: 'FAIL', enableBlockedReasons,
      enableable: !blocked,
      enableRoute: blocked ? null : enableRoute(apiName),
      reason: blocked
        ? `${label} (${apiName}) → NOT_ENABLED, but blocked: ${enableBlockedReasons.map((r) => (typeof r === 'string' ? r : (r?.message ?? JSON.stringify(r)))).join('; ')}.`
        : `${label} (${apiName}) → NOT_ENABLED (enableable).`,
    };
  }
  return {
    status, signal: 'CANNOT-CONFIRM', enableBlockedReasons: [], enableable: false, enableRoute: null,
    reason: `${label} (${apiName}) → unexpected status "${status}".`,
  };
}

const [statusPath, rawAgentType, rawExit] = process.argv.slice(2);
const agentType = String(rawAgentType ?? '').toLowerCase();
if (!statusPath || !REQUIRED[agentType]) {
  process.stderr.write('usage: node classify-readiness.mjs <features-status.json> <fulfiller|employee> [exitStatus]\n');
  process.exit(2);
}
const exitStatus = rawExit === undefined ? NaN : Number(rawExit);

const { readState, statusMap, rawError } = readFeatureStatus(readJson(statusPath), exitStatus);

const features = {};
const reasons = [];
const notEnabled = [];
const enableable = [];

if (readState === 'error') {
  // Hard read failure (auth / permission / transport / unexpected). Do NOT
  // pretend the gate is merely un-wired — surface it and stop.
  for (const apiName of REQUIRED[agentType]) {
    features[apiName] = { status: 'UNKNOWN', signal: 'ERROR', enableBlockedReasons: [], enableable: false, enableRoute: null };
  }
  reasons.push(`Feature status could not be read: ${rawError} Surface the raw response and stop — do not treat as a wiring gap.`);
  process.stdout.write(JSON.stringify({
    agentType, readState, features, verdict: 'ERROR', notEnabled, enableable, reasons, rawError,
  }, null, 2) + '\n');
  process.exit(0);
}

const signals = [];
for (const apiName of REQUIRED[agentType]) {
  const c = classifyFeature(apiName, statusMap);
  features[apiName] = {
    status: c.status, signal: c.signal,
    enableBlockedReasons: c.enableBlockedReasons, enableable: c.enableable, enableRoute: c.enableRoute,
  };
  reasons.push(c.reason);
  signals.push(c.signal);
  if (c.signal === 'FAIL') notEnabled.push(apiName);
  if (c.enableable) enableable.push(apiName);
}

let verdict;
if (signals.includes('FAIL')) verdict = 'NOT-READY';
else if (signals.every((s) => s === 'PASS')) verdict = 'READY';
else verdict = 'CANNOT-CONFIRM';

process.stdout.write(JSON.stringify({
  agentType,
  readState,
  features,
  verdict,
  notEnabled,
  enableable,
  reasons,
  rawError,
}, null, 2) + '\n');
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall