@salesforce/afv-skills 1.44.0 → 1.45.0

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/scripts/classify-agent-existence.mjs

@@ -3,51 +3,67 @@
 //
 // Idempotency for this flow is keyed PRIMARILY on the TEMPLATE's own
 // `botDefinitionId` — the platform's authoritative link from an `agent-templates`
-// row to the live `BotDefinition` it was instantiated into — and FALLS BACK to a
-// `DeveloperName`-keyed read when that row carries no `botDefinitionId`.
+// row to the live `BotDefinition` it was instantiated into — and FALLS BACK
+// first to the BotDefinition's own `AgentTemplate` field (the OOTB, namespaced
+// template API name it was instantiated from, e.g.
+// `svc_itsm_intelligence__ITSrvcMgmtFulfiller`), then to a `DeveloperName`-keyed
+// read.
 // If the Fulfiller template was already instantiated under a DeveloperName that
 // differs from this skill's default collected `IT_Service_Fulfiller_Agent`, a
 // DeveloperName-only read false-negatives (exists:false) and the create then
-// collides on `apiName` with `DUPLICATE_VALUE` — hence botDefinitionId is the
-// primary key. But botDefinitionId is back-filled onto the template row ONLY for
-// platform-pre-provisioned agents (the ITSM create path never stamps
-// `templateName`, so the platform never joins the agent-templates row to its
-// BotDefinition), and the Fulfiller is never pre-provisioned — so its template
-// `botDefinitionId` is null on the first run and every run after, and the
-// DeveloperName-keyed read is the guard that actually protects this path, used as
-// the FALLBACK below. (Preflight emits `template.botDefinitionId`; the workflow
-// passes it as the primary key and the collected developerName as the fallback key.)
+// collides on `apiName` with `DUPLICATE_VALUE`. `AgentTemplate` closes that gap
+// far more reliably than a display name would: it is the platform-stamped source
+// template on the live BotDefinition, so it survives any DeveloperName rename and
+// carries the namespace prefix the skill already knows (preflight `template.id`).
+// The template-row `botDefinitionId` is back-filled ONLY for platform-
+// pre-provisioned agents (the ITSM create path never stamps `templateName`, so
+// the platform never joins the agent-templates row to its BotDefinition), and the
+// Fulfiller is never pre-provisioned — so its template `botDefinitionId` is null
+// on the first run and every run after. Self-created Fulfiller agents also carry
+// a NULL `AgentTemplate` (the create path doesn't stamp the source template), so
+// for the Fulfiller the DeveloperName-keyed read is the guard that actually
+// protects this path; `AgentTemplate` is a defensive key that would catch a
+// hypothetical pre-provisioned Fulfiller and keeps this classifier identical to
+// the Employee one (where `AgentTemplate` IS the load-bearing catcher). (Preflight
+// emits `template.botDefinitionId`, `template.id`, and the collected
+// developerName; the workflow passes the botDefinitionId as the primary key,
+// template.id as the AgentTemplate key, and the developerName as the fallback.)
 //
 // This classifier consumes the raw JSON of a `sf data query ... --json` read of
-// BotDefinition (BY Id primarily, BY DeveloperName on the fallback) and decides
+// BotDefinition (BY Id primarily, BY AgentTemplate then DeveloperName on the
+// fallback) and decides
 // whether the agent already exists — and if so, whether its latest BotVersion is
 // Inactive (so the workflow can offer to activate it instead of creating a
 // duplicate). This is the deterministic decision that gates whether the write is
 // skipped — it MUST NOT be interpreted by the model in prose (authoring standard A9).
 //
 // Usage:
-//   node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName]
+//   node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName] [agentTemplate]
 //
 // When <botDefinitionId> is empty, `-`, or the literal `null`/`undefined` (the
 // matched template carries no botDefinitionId), the classifier FALLS BACK to
-// keying on <developerName>, and <bot-query.json> must be a DeveloperName-keyed
-// BotDefinition read: self-created agents are never back-filled with a
-// botDefinitionId (the ITSM create path doesn't stamp `templateName`, so the
-// platform never joins the agent-templates row to its BotDefinition), so
-// DeveloperName is the only idempotency guard left for them. Only when BOTH
-// <botDefinitionId> and <developerName> are absent is exists:false emitted
-// without reading a query file. Otherwise <bot-query.json> is a FILE PATH to the
-// stdout captured from:
-//   sf data query -q "SELECT Id,DeveloperName,MasterLabel,
+// keying on <agentTemplate> (the source template API name), and then to
+// <developerName> when the AgentTemplate misses too. <bot-query.json> must
+// therefore be a read that ORs all three keys together: self-created agents are
+// never back-filled with a botDefinitionId AND carry a null AgentTemplate (the
+// ITSM create path doesn't stamp `templateName`), so DeveloperName is their only
+// idempotency guard; a pre-provisioned agent whose live DeveloperName differs from
+// this skill's collected guess is caught by AgentTemplate. Only when ALL of
+// <botDefinitionId>, <agentTemplate>, and <developerName> are absent is
+// exists:false emitted without reading a query file. Otherwise <bot-query.json> is
+// a FILE PATH to the stdout captured from:
+//   sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,
 //     (SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1)
-//     FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" \
+//     FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>'
+//       OR DeveloperName='<developerName>'" \
 //     --target-org <org> --json > file.json
-// (The present-id read ORs in DeveloperName so a DANGLING template→BotDefinition
-// link — a botDefinitionId whose target BotDefinition was since deleted — still
-// surfaces the live same-name agent: the classifier tries the Id first, then
-// falls back to the name on the SAME records. The pure FALLBACK read, taken when
-// the template row carries no botDefinitionId at all, keys on
-// `DeveloperName='<developerName>'` only; everything else is identical.
+// (The present-id read ORs in AgentTemplate AND DeveloperName so a DANGLING
+// template→BotDefinition link — a botDefinitionId whose target BotDefinition was
+// since deleted — still surfaces the live agent: the classifier tries the Id
+// first, then the AgentTemplate, then the DeveloperName on the SAME records. The
+// pure FALLBACK read, taken when the template row carries no botDefinitionId at
+// all, keys on `AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'`;
+// everything else is identical.
 // `sf data query --json` wraps results in a `.result.records[]` envelope. The
 // BotVersions subquery is required so this classifier can see the latest
 // version's Status — a query without it leaves latestVersionStatus null and
@@ -62,16 +78,17 @@
 // child row was returned), and needsActivation is true only when exists is true
 // AND latestVersionStatus is "Inactive" — the signal to offer activating the
 // existing version instead of creating a new agent. `matchedBy` is
-// "botDefinitionId" | "developerName" | null, recording which key hit. Exit code
+// "botDefinitionId" | "agentTemplate" | "developerName" | null, recording which
+// key hit. Exit code
 // is always 0 on a parseable body (or when neither key is supplied); the verdict
 // is carried in the payload. On an unparseable/failed query it exits 3 so the
 // workflow surfaces the raw error rather than assuming NOT-EXISTS.
 
 import { readFileSync } from 'node:fs';
 
-const [queryPath, rawBotDefinitionId, rawDeveloperName] = process.argv.slice(2);
+const [queryPath, rawBotDefinitionId, rawDeveloperName, rawAgentTemplate] = process.argv.slice(2);
 if (!queryPath) {
-  process.stderr.write('usage: node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName]\n');
+  process.stderr.write('usage: node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName] [agentTemplate]\n');
   process.exit(2);
 }
 
@@ -89,8 +106,10 @@ function notSet(v) {
 
 const botDefinitionId = String(rawBotDefinitionId ?? '').trim();
 const developerName = String(rawDeveloperName ?? '').trim();
+const agentTemplate = String(rawAgentTemplate ?? '').trim();
 const noId = notSet(botDefinitionId);
 const noName = notSet(developerName);
+const noTemplate = notSet(agentTemplate);
 
 const NOT_EXISTS = {
   exists: false,
@@ -104,11 +123,12 @@ const NOT_EXISTS = {
   needsActivation: false,
 };
 
-// Nothing to key on — no botDefinitionId AND no developerName fallback. There is
-// no way to detect an existing agent, so this is the create path. (The workflow
-// should always pass the collected developerName so the fallback below can run;
-// this bare branch only fires when neither key is supplied.)
-if (noId && noName) {
+// Nothing to key on — no botDefinitionId AND no AgentTemplate fallback AND no
+// DeveloperName fallback. There is no way to detect an existing agent, so this is
+// the create path. (The workflow should always pass the collected developerName
+// and the template's id/AgentTemplate so the fallbacks below can run; this bare
+// branch only fires when none of the three keys is supplied.)
+if (noId && noTemplate && noName) {
   process.stdout.write(JSON.stringify(NOT_EXISTS, null, 2) + '\n');
   process.exit(0);
 }
@@ -139,20 +159,22 @@ const records = Array.isArray(data.result?.records) ? data.result.records : [];
 // `templateName`), so in practice the DeveloperName fallback below is what fires.
 // The matching LOGIC here is kept identical to the Employee classifier on
 // purpose — one shared matching contract, so the two can't drift and a future
-// platform change that DOES populate the Fulfiller's botDefinitionId is handled
-// correctly rather than silently mismatched; see that script's header for the
-// pre-provisioned rationale it exercises.
-// FALLBACK: the collected DeveloperName. Self-created agents are NOT
-// back-filled — the ITSM create path never stamps `templateName`, so the
-// platform never joins the agent-templates row to its BotDefinition and
-// `botDefinitionId` stays null on every later read — so DeveloperName is their
-// only guard. We ALSO fall back to DeveloperName when a PRESENT botDefinitionId
+// platform change that DOES populate the Fulfiller's botDefinitionId/AgentTemplate
+// is handled correctly rather than silently mismatched; see that script's header
+// for the pre-provisioned rationale it exercises.
+// FALLBACK: the BotDefinition's own `AgentTemplate`, then the collected
+// DeveloperName. `AgentTemplate` is the OOTB source-template API name the platform
+// stamps on a template-instantiated agent — the reliable "an agent from THIS
+// template already exists" signal for pre-provisioned agents, independent of any
+// DeveloperName rename. Self-created agents are NOT stamped (the ITSM create path
+// never sets `templateName`), so their `AgentTemplate` is null and DeveloperName
+// is their guard. We ALSO fall back this way when a PRESENT botDefinitionId
 // matches nothing (a dangling link whose target BotDefinition was deleted): the
-// present-id Phase-2 SOQL reads `WHERE Id=... OR DeveloperName=...`, so a stale
-// link still surfaces the live same-name agent instead of slipping through to the
-// create path and colliding with DUPLICATE_VALUE. Try the Id first, then the
-// name; each filter is self-checking on top of the SOQL WHERE so a wrong-keyed
-// read can't false-positive.
+// present-id Phase-2 SOQL reads `WHERE Id=... OR AgentTemplate=... OR
+// DeveloperName=...`, so a stale link still surfaces the live agent instead of
+// slipping through to the create path and colliding with DUPLICATE_VALUE. Try the
+// Id first, then the template, then the name; each filter is self-checking on top
+// of the SOQL WHERE so a wrong-keyed read can't false-positive.
 let matches = [];
 let matchedBy = null;
 if (!noId) {
@@ -160,12 +182,38 @@ if (!noId) {
   matches = records.filter((r) => idKey(r?.Id) === wantedIdKey);
   if (matches.length) matchedBy = 'botDefinitionId';
 }
+// FIRST FALLBACK: the BotDefinition's `AgentTemplate` (source template API name).
+// When a live agent was instantiated from this template under a DeveloperName
+// that differs from this skill's collected guess AND its template row carries no
+// botDefinitionId, the Id and DeveloperName keys both miss and the create then
+// collides with DUPLICATE_VALUE. `AgentTemplate` is the platform-stamped source
+// template, so matching on it recovers that live agent reliably. SOQL text
+// comparison is case-insensitive, so compare the same way. `AgentTemplate` is NOT
+// unique (a template can be instantiated more than once), so if more than one
+// record shares it we keep them all but surface an Active version first (see
+// below) — the report should treat the already-active one as the real match.
+if (!matches.length && !noTemplate) {
+  const wantedTemplate = agentTemplate.toLowerCase();
+  matches = records.filter((r) => String(r?.AgentTemplate ?? '').trim().toLowerCase() === wantedTemplate);
+  if (matches.length) matchedBy = 'agentTemplate';
+}
+// SECOND FALLBACK: the collected DeveloperName — the guard for self-created agents
+// (null AgentTemplate). DeveloperName uniqueness is case-insensitive; compare
+// accordingly.
 if (!matches.length && !noName) {
-  // DeveloperName uniqueness is case-insensitive; compare accordingly.
   const wantedName = developerName.toLowerCase();
   matches = records.filter((r) => String(r?.DeveloperName ?? '').trim().toLowerCase() === wantedName);
   if (matches.length) matchedBy = 'developerName';
 }
+if (matchedBy === 'agentTemplate' && matches.length > 1) {
+  // Prefer a record whose latest BotVersion is Active so `matches[0]` (used for
+  // latestVersion/agentId below) reflects the live agent rather than a stale draft.
+  matches = [...matches].sort((a, b) => {
+    const aActive = a?.BotVersions?.records?.[0]?.Status === 'Active' ? 0 : 1;
+    const bActive = b?.BotVersions?.records?.[0]?.Status === 'Active' ? 0 : 1;
+    return aActive - bActive;
+  });
+}
 const exists = matches.length > 0;
 
 // The BotVersions child subquery (if present in the SOQL) surfaces the latest
@@ -180,12 +228,15 @@ const needsActivation = exists && latestVersionStatus === 'Inactive';
 process.stdout.write(JSON.stringify({
   exists,
   count: matches.length,
-  // Which key matched — `botDefinitionId` (primary) or `developerName` (the
-  // fallback for self-created agents). null when nothing matched.
+  // Which key matched — `botDefinitionId` (primary), `agentTemplate` (the
+  // reliable catcher for a pre-provisioned agent whose DeveloperName differs from
+  // the collected guess), or `developerName` (the fallback for self-created
+  // agents). null when nothing matched.
   matchedBy: exists ? matchedBy : null,
   agentId: exists ? (matches[0].Id ?? null) : null,
-  // On a DeveloperName-fallback hit this surfaces the live BotDefinition Id the
-  // template row was missing; on the Id path it echoes the queried id.
+  // On an AgentTemplate- or DeveloperName-fallback hit this surfaces the live
+  // BotDefinition Id the template row was missing; on the Id path it echoes the
+  // queried id.
   botDefinitionId: exists ? (matches[0].Id ?? null) : (noId ? null : botDefinitionId),
   developerName: exists ? (matches[0].DeveloperName ?? null) : null,
   latestVersionId: latestVersion?.Id ?? null,

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/scripts/classify-preflight.mjs

@@ -20,12 +20,17 @@
 //
 // Emits a single JSON object to stdout:
 //   { studio: { hasAccess, signal, reason },
-//     template: { present, id, hasAgentScript, botDefinitionId, 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); the collected developerName is the FALLBACK key
-// there. See classify-agent-existence.mjs for why. (The template row's
+// template→BotDefinition link); `id` (the template's OOTB namespaced API name) is
+// passed as the AgentTemplate fallback key — it matches `BotDefinition.AgentTemplate`
+// on a template-instantiated agent regardless of its DeveloperName — 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
@@ -107,16 +112,18 @@ function classifyTemplate(res, masterLabel) {
   }
   // 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 the reliable idempotency signal for PRE-PROVISIONED agents
-  // (see classify-agent-existence.mjs): it means the agent already exists
-  // regardless of what DeveloperName this skill would have guessed. Agents this
-  // skill creates never stamp `templateName`, so their row's botDefinitionId stays
-  // null — the Phase-2 read falls back to a DeveloperName key for that case.
+  // botDefinitionId is a direct link for PRE-PROVISIONED agents; when it is null,
+  // the template's own `id` (matched against `BotDefinition.AgentTemplate` in
+  // Phase 2) still catches a pre-provisioned agent 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 falls back to DeveloperName)'} — feed it to scripts/build-create-body.mjs for the NGA bundle create.` };
+  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);
@@ -145,11 +152,18 @@ process.stdout.write(JSON.stringify({
     id: template.id,
     hasAgentScript: template.hasAgentScript,
     // Idempotency identity (from the matched agent-templates row): the Phase-2
-    // read uses botDefinitionId as the PRIMARY key and the collected developerName
-    // as the FALLBACK. A populated botDefinitionId is the load-bearing "agent
-    // already exists" signal for pre-provisioned agents; null just means this
-    // template row was never joined (e.g. a self-created agent) — not "no agent".
+    // 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 reliable catcher for a pre-provisioned
+    // agent 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,
   },

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/scripts/render-report.mjs

@@ -144,13 +144,19 @@ if (
 
 const reason = String(state.reason ?? '').trim();
 
+// The "set up access" next step below is the handoff to the
+// `service-itsm-agentic-setup-agent-runtime-access-assign` skill (declared in
+// this skill's metadata.relatedSkills). We deliberately surface it in plain
+// admin language ("grant this agent's runtime access") rather than by raw skill
+// name — the routing metadata carries the linkage, so the user-facing report
+// stays friendly while the relationship remains discoverable.
 const NEXT_STEPS = {
   'CREATED':
-    'The IT Service Fulfiller agent is live as an NGA-native agent (no external-link icon in Agentforce Studio). No new agent was provisioned beyond the one just created. Verify end-to-end in Agentforce Studio\'s Agents list.',
+    'The IT Service Fulfiller agent is live as an NGA-native agent (no external-link icon in Agentforce Studio). No new agent was provisioned beyond the one just created. Verify end-to-end in Agentforce Studio\'s Agents list. **Next — set up access:** before anyone can use the agent, the user needs the runtime permissions the agent\'s actions use (Prompt Templates, Data Cloud, or Unified Catalog, depending on what is provisioned). Just ask to **grant this agent\'s runtime access** and those feature permissions — plus an "Agent Access" permission set covering the agent — will be set up for the user(s) you choose.',
   'ALREADY-CREATED':
-    'The IT Service Fulfiller agent was already present and active — no new agent was provisioned. Verify end-to-end in Agentforce Studio\'s Agents list.',
+    'The IT Service Fulfiller agent was already present and active — no new agent was provisioned. Verify end-to-end in Agentforce Studio\'s Agents list. **Next — set up access:** before anyone can use the agent, the user needs the runtime permissions the agent\'s actions use (Prompt Templates, Data Cloud, or Unified Catalog, depending on what is provisioned). Just ask to **grant this agent\'s runtime access** and those feature permissions — plus an "Agent Access" permission set covering the agent — will be set up for the user(s) you choose.',
   'ACTIVATED':
-    'The existing IT Service Fulfiller agent was found inactive and has been activated — no new agent was provisioned. Verify end-to-end in Agentforce Studio\'s Agents list.',
+    'The existing IT Service Fulfiller agent was found inactive and has been activated — no new agent was provisioned. Verify end-to-end in Agentforce Studio\'s Agents list. **Next — set up access:** before anyone can use the agent, the user needs the runtime permissions the agent\'s actions use (Prompt Templates, Data Cloud, or Unified Catalog, depending on what is provisioned). Just ask to **grant this agent\'s runtime access** and those feature permissions — plus an "Agent Access" permission set covering the agent — will be set up for the user(s) you choose.',
   'PENDING CONFIRMATION':
     'The run is paused at the confirm-to-write gate. In this skill, create + publish + activate happen as one atomic sequence gated by a single confirmation — there is no supported create-only or publish-without-activate mode, and no partial "create-only" mode of any kind. Re-run and reply "yes" when you are ready for the agent to go live.',
   'DECLINED':