Skip to content

forcedotcom/sf-skills / plugins/builder/service-itsm/skills/service-itsm-agentic-setup-employee-agent-configure

service-itsm-agentic-setup-employee-agent-configure

Unverified

Create and activate an IT Service Employee agent as a Next-Gen Authoring (NGA) native agent from an ITSM Employee agent template's Agent Script, via the Salesforce CLI (sf): read the template, check idempotency, create the NGA bundle then publish and activate, verify live. Defaults to the broad IT Service Employee template; when the user names a specialized Employee template (Password Manager Assistance, Certificate Management, Onboarding, Hardware Request, and ~47 others catalogued in references/specialized-templates.md — all under the `svc_emp_intelligence__` namespace), pins that one instead. Idempotent per developer name. TRIGGER when the user asks to create/set up/provision/activate the Employee agent, the IT Service Employee agent, or a specialized Employee agent (password manager, certificate, onboarding, hardware request, etc.). DO NOT TRIGGER: prerequisite checks (service-itsm-agentic-setup-agentforce-studio-validate), CMDB CRUD, Fulfiller setup (service-itsm-agentic-setup-fulfiller-agent-configure).

FileKindSize
SKILL.mdskill md29.4 KB
references/cli-invocation.mdmarkdown22.4 KB
references/error-taxonomy.mdmarkdown4.1 KB
references/reactivation.mdmarkdown4.2 KB
references/report-format.mdmarkdown4.9 KB
references/specialized-templates.mdmarkdown10.5 KB
references/workflow-detail.mdmarkdown18.2 KB
scripts/build-create-body.mjsexecutablescript4.7 KB
scripts/classify-agent-existence.mjsexecutablescript13.5 KB
scripts/classify-preflight.mjsexecutablescript11.4 KB
scripts/create-scratch-dir.mjsexecutablescript2.3 KB
scripts/render-report.mjsexecutablescript12.2 KB

scripts/classify-preflight.mjs

View on GitHub
#!/usr/bin/env node
// Deterministic preflight classifier for the Employee-agent create flow.
//
// Two fixed JSON-parsing / decision rules that must not live in model prose
// (authoring standard A9):
//   1. Studio access: read `hasAccess` from the agentforce-studio/access/Agents
//      body → PASS (true) / FAIL (false) / CANNOT-CONFIRM (404 / not wired).
//   2. Template provisioning: find the agent-templates item whose masterLabel
//      matches the target ("IT Service Employee"), confirm it carries a non-empty
//      `agentScript` (the Agent Script YAML fed into the NGA bundle create) → PRESENT
//      (+hasAgentScript) / ABSENT (empty data[] or no match) / CANNOT-CONFIRM
//      (404 / not wired).
//
// Usage:
//   node classify-preflight.mjs <studio-access.json> <agent-templates.json> <masterLabel>
//
// Both file args are paths to raw `sf api request rest` stdout captures; the
// files may hold a Connect error array or be empty when the CLI exited non-zero.
// <masterLabel> is the template's display label (default "IT Service Employee").
//
// Emits a single JSON object to stdout:
//   { studio: { hasAccess, signal, reason },
//     template: { present, id, hasAgentScript, botDefinitionId, masterLabel, signal, reason },
//     verdict, reasons: [...] }
// `botDefinitionId` is copied from the matched agent-templates row and passed to
// the Phase-2 idempotency read as the PRIMARY key (the platform's authoritative
// template→BotDefinition link); `id` (the template's OOTB namespaced API name) is
// passed as the AgentTemplate fallback key — it matches `BotDefinition.AgentTemplate`
// on the pre-provisioned broad `IT_Service_Employee` agent regardless of its
// DeveloperName, so it is THE key that catches it — and the collected developerName
// is the last fallback (the guard for self-created agents, which carry a null
// AgentTemplate). `masterLabel` is echoed only for the report's display label; it
// is NOT an idempotency key (a display name is renamable and non-unique). See
// classify-agent-existence.mjs for why. (The template row's `isInstalled`/`isActivated`
// flags are NOT emitted: they ride the same AgentTemplate join as botDefinitionId,
// so for agents this skill creates — which never stamp `templateName` — they read
// false even after the agent exists, and nothing downstream consumes them.)
// where signal is PASS | FAIL | CANNOT-CONFIRM | ERROR and verdict is
// READY | NOT-READY | CANNOT-CONFIRM | ERROR. Exit is always 0 on usable args.
// ERROR (studio only) means the Studio-access read returned a parseable but
// non-404 error body (401/403/unexpected) — that is a failed prerequisite
// read, not an unwired gate, so it must stop the workflow rather than fall
// through to a CANNOT-CONFIRM that a present template can outrun to READY.

import { readFileSync } from 'node:fs';

function readJson(path) {
  try {
    const text = readFileSync(path, 'utf8').trim();
    if (!text) return { ok: false };
    return { ok: true, data: JSON.parse(text) };
  } catch {
    return { ok: false };
  }
}

function asErrorArray(data) {
  if (Array.isArray(data)) return data.filter((e) => e && (e.errorCode || e.message));
  if (data && (data.errorCode || data.message)) return [data];
  return [];
}

function isNotFoundError(data) {
  return asErrorArray(data).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);
}

function classifyStudio(res) {
  if (!res.ok) {
    return { hasAccess: null, signal: 'CANNOT-CONFIRM', reason: 'Studio access — no readable body (endpoint not wired / empty). A successful create/publish/activate is authoritative.' };
  }
  const d = res.data;
  const errs = asErrorArray(d);
  if (errs.length) {
    if (isNotFoundError(d)) return { hasAccess: null, signal: 'CANNOT-CONFIRM', reason: 'Studio access → 404 (access-check gate not wired on this org). Treat as cannot-confirm; a successful create/publish/activate is authoritative.' };
    return { hasAccess: null, signal: 'ERROR', reason: `Studio access read failed: ${errorSnippet(errs)} — surface the raw response and stop; do not treat as an unwired gate.` };
  }
  if (d?.hasAccess === true) return { hasAccess: true, signal: 'PASS', reason: 'Studio access → hasAccess=true.' };
  if (d?.hasAccess === false) return { hasAccess: false, signal: 'FAIL', reason: 'Studio access → hasAccess=false — offer the prerequisite readiness hand-off before any write.' };
  return { hasAccess: null, signal: 'CANNOT-CONFIRM', reason: 'Studio access body had no boolean hasAccess field.' };
}

function classifyTemplate(res, masterLabel) {
  if (!res.ok) {
    return { present: false, id: null, hasAgentScript: false, signal: 'CANNOT-CONFIRM', reason: 'agent-templates — no readable body (endpoint not wired / empty).' };
  }
  const d = res.data;
  if (asErrorArray(d).length) {
    if (isNotFoundError(d)) return { present: false, id: null, hasAgentScript: false, signal: 'CANNOT-CONFIRM', reason: 'agent-templates → 404 (ITSM Connect namespace not provisioned). Hand off to the readiness check.' };
    return { present: false, id: null, hasAgentScript: false, signal: 'CANNOT-CONFIRM', reason: 'agent-templates read returned an error body — surface it.' };
  }
  const items = Array.isArray(d?.data) ? d.data : null;
  if (!items) return { present: false, id: null, hasAgentScript: false, signal: 'CANNOT-CONFIRM', reason: 'agent-templates had no data[] array (unexpected shape).' };
  // Filter to the only namespace this skill instantiates. The endpoint also
  // returns Fulfiller-side (`svc_itsm_intelligence__*`), Slack, ServiceNow,
  // Runtime Insights, and other-namespace entries — some carry masterLabels
  // that collide with in-namespace entries (e.g. `System Password Reset
  // Assistance` exists in both `svc_emp_intelligence__` and `EmpSvcAgent__`).
  // A `masterLabel`-only match would silently pick whichever appeared first
  // in `data[]`; filtering first pins the choice to the correct namespace.
  const inNamespace = items.filter((it) => typeof it?.id === 'string' && it.id.startsWith('svc_emp_intelligence__'));
  const wanted = String(masterLabel).trim().toLowerCase();
  const match = inNamespace.find((it) => String(it?.masterLabel ?? '').trim().toLowerCase() === wanted);
  if (!match) {
    return {
      present: false, id: null, hasAgentScript: false, signal: 'FAIL',
      reason: items.length === 0
        ? 'agent-templates returned an empty data[] — wrong agentType or the org is not ITSM-provisioned; hand off to the readiness check.'
        : inNamespace.length === 0
          ? `agent-templates returned ${items.length} entries but none under the svc_emp_intelligence__ namespace — the Employee IT Service feature toggles are not provisioned on this org; hand off to the readiness check.`
          : `No svc_emp_intelligence__ template with masterLabel "${masterLabel}" (got: ${inNamespace.map((i) => i?.masterLabel).filter(Boolean).join(', ') || 'none'}). Hand off to the readiness check.`,
    };
  }
  // Idempotency identity carried by the matched row — the platform's own link
  // from this template to the BotDefinition it was instantiated into. A populated
  // botDefinitionId is a direct link for PRE-PROVISIONED agents; for the broad
  // Employee agent it is null, so the template's own `id` (matched against
  // `BotDefinition.AgentTemplate` in Phase 2) is what catches the pre-provisioned
  // `IT_Service_Employee` regardless of what DeveloperName this skill would have
  // guessed (see classify-agent-existence.mjs). Agents this skill creates never
  // stamp `templateName`, so they carry BOTH a null row botDefinitionId AND a null
  // AgentTemplate — the Phase-2 read falls back to the collected DeveloperName key
  // for that case.
  const botDefinitionId = typeof match.botDefinitionId === 'string' && match.botDefinitionId.trim() ? match.botDefinitionId : null;
  if (!match.agentScript || typeof match.agentScript !== 'string' || !match.agentScript.trim()) {
    return { present: true, id: match.id ?? null, hasAgentScript: false, botDefinitionId, signal: 'CANNOT-CONFIRM', reason: `Matched "${masterLabel}" (id=${match.id}) but it had no agentScript field — the NGA bundle create needs the template's Agent Script content.` };
  }
  return { present: true, id: match.id ?? null, hasAgentScript: true, botDefinitionId, signal: 'PASS', reason: `Template "${masterLabel}" present (id=${match.id}) with a non-empty agentScript${botDefinitionId ? `; already instantiated (botDefinitionId=${botDefinitionId})` : '; not yet instantiated (no botDefinitionId — the Phase-2 read keys on AgentTemplate=id, then DeveloperName)'} — feed it to scripts/build-create-body.mjs for the NGA bundle create.` };
}

const [studioPath, templatePath, rawLabel] = process.argv.slice(2);
if (!studioPath || !templatePath) {
  process.stderr.write('usage: node classify-preflight.mjs <studio-access.json> <agent-templates.json> [masterLabel]\n');
  process.exit(2);
}
const masterLabel = rawLabel && rawLabel.trim() ? rawLabel : 'IT Service Employee';

const studio = classifyStudio(readJson(studioPath));
const template = classifyTemplate(readJson(templatePath), masterLabel);

// Verdict: the template MUST be present to create. Studio FALSE blocks (hand-off);
// Studio ERROR (non-404 failed read, e.g. 401/403) blocks — surface it, stop.
// Studio CANNOT-CONFIRM (confirmed 404 gate) does not block — create/publish/activate is authoritative.
let verdict;
if (studio.signal === 'ERROR') verdict = 'ERROR';
else if (studio.signal === 'FAIL' || template.signal === 'FAIL') verdict = 'NOT-READY';
else if (template.signal === 'PASS') verdict = 'READY'; // studio PASS, or unconfirmed via a documented 404 gate — template present is enough to attempt
else verdict = 'CANNOT-CONFIRM';

process.stdout.write(JSON.stringify({
  studio: { hasAccess: studio.hasAccess, signal: studio.signal, reason: studio.reason },
  template: {
    present: template.present,
    id: template.id,
    hasAgentScript: template.hasAgentScript,
    // Idempotency identity (from the matched agent-templates row): the Phase-2
    // read uses botDefinitionId as the PRIMARY key, `id` (the template's namespaced
    // API name) as the AgentTemplate key, and the collected developerName as the
    // last fallback. A populated botDefinitionId is a direct "agent already exists"
    // link; null just means this template row was never joined (e.g. a self-created
    // agent) — not "no agent". `id` is the load-bearing catcher for the
    // pre-provisioned broad `IT_Service_Employee`, whose DeveloperName differs from
    // this skill's collected guess: it matches `BotDefinition.AgentTemplate`, the
    // platform-stamped source template. `masterLabel` is echoed only for the
    // report's display label (NOT an idempotency key). The workflow passes
    // botDefinitionId, `id`, and the collected developerName to
    // classify-agent-existence.mjs from this single source.
    botDefinitionId: template.botDefinitionId ?? null,
    masterLabel,
    signal: template.signal,
    reason: template.reason,
  },
  verdict,
  reasons: [studio.reason, template.reason],
}, 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: 472kUpdated 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