@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/references/workflow-detail.md

@@ -0,0 +1,149 @@
+# Fulfiller Agent — Workflow Detail
+
+Detailed per-phase command shapes + verdict narrative for `service-itsm-agentic-setup-fulfiller-agent-configure`. Read this alongside the phase headers in `SKILL.md` — the SKILL body holds the load-bearing rules, this file holds the exact commands and branch-by-branch verdict handling.
+
+All calls go through `sf`; substitute `<alias>` with the collected target org and `<developerName>` / `<label>` with the collected values.
+
+## Phase 0 — Establish the per-run scratch directory
+
+Before any phase writes a transient JSON file, invoke `scripts/create-scratch-dir.mjs` — path selection (`${TMPDIR}` → `/tmp` → `${outputDir}` last-resort, keeping transient captures out of the scored `${outputDir}` tree) and the `mkdtemp` call live in the helper so the deterministic logic never sits in prose (A9). Every subsequent phase writes its scratch JSON under `${SCRATCH_DIR}`, so runs never collide and the transient state stays scoped to the run:
+
+```bash
+SCRATCH_DIR="$(node "<skill_dir>/scripts/create-scratch-dir.mjs" "${outputDir:-}")"
+```
+
+The remaining phases reference `${SCRATCH_DIR}` for every transient path (studio-access, agent-templates, bot-existing, create-bundle-body, publish/activate response captures, report-state, verify). The **durable** run artifact — `${outputDir}/report.md` — is still written to the harness-provided directory.
+
+## Phase 1 — Preflight: confirm Studio access + template provisioning
+
+Capture the Studio-access read and the `agent-templates` read, then let `scripts/classify-preflight.mjs` make the deterministic decisions (never parse `hasAccess` or search `data[]` in prose — A9). The `agent-templates` `agentType` query param is **required** with value `AgentforceEmployeeAgent` (a call without it returns `400 MISSING_ARGUMENT: agentType`):
+
+```bash
+sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" \
+  --method GET --target-org <alias> > ${SCRATCH_DIR}/studio-access.json 2>${SCRATCH_DIR}/studio-access.err || true
+sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" \
+  --method GET --target-org <alias> > ${SCRATCH_DIR}/agent-templates.json 2>${SCRATCH_DIR}/agent-templates.err || true
+node "<skill_dir>/scripts/classify-preflight.mjs" ${SCRATCH_DIR}/studio-access.json ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller"
+```
+
+The classifier prints `{ studio:{hasAccess,signal}, template:{present,id,hasAgentScript,botDefinitionId,signal}, verdict, reasons }`:
+
+- `template.hasAgentScript:true` confirms the template carries the Agent Script content Phase 4 needs; capture the raw `agent-templates.json` file path — Phase 4 re-reads it directly (via `scripts/build-create-body.mjs`) rather than the classifier re-emitting the full script content.
+- **`template.botDefinitionId` is the PRIMARY Phase-2 idempotency key**, but the Fulfiller is never pre-provisioned and this skill's create path never stamps `templateName`, so its template `botDefinitionId` is `null` on every run — the collected `<developerName>` is the guard that actually fires. Capture `botDefinitionId` for Phase 2 and carry the collected `<developerName>` as the fallback key.
+- `verdict:"READY"` ⇒ continue to Phase 2.
+- `verdict:"ERROR"` because `studio.signal="ERROR"` (the Studio-access read returned a parseable but non-404 error body — e.g. `401`/`403`) ⇒ do NOT proceed — surface the raw error and stop. This is a failed prerequisite read, not an unwired gate; do not let a present template push the verdict to READY.
+- `verdict:"NOT-READY"` because `studio.signal="FAIL"` (`hasAccess=false`) ⇒ do NOT proceed — **offer the prerequisite hand-off**:
+  - Present a single `AskUserQuestion`: _"Agentforce for IT Service prerequisites don't look satisfied on this org. Run `service-itsm-agentic-setup-agentforce-studio-validate` to check readiness first?"_ (options: **Yes, check readiness** / **No, stop here**).
+  - On **Yes**: delegate to `service-itsm-agentic-setup-agentforce-studio-validate` (read-only readiness check). If it reports NOT-READY, stop and report the missing prerequisite (enablement is a Setup-UI/admin action, outside both skills' write scope). If READY, resume from Phase 2.
+  - On **No**: stop and report the missing prerequisite verbatim — no writes.
+- `verdict:"NOT-READY"` because `template.signal="FAIL"` (empty/no matching template) ⇒ the org is not ITSM-provisioned; hand off to the readiness check.
+- `template.signal="CANNOT-CONFIRM"` because the matched template has no `agentScript` ⇒ the NGA create has nothing to build from; surface this and stop (do not fall back to the legacy `createAgent` route — it is out of scope for this skill).
+- `studio.signal="CANNOT-CONFIRM"` (a **confirmed** `404` — the access-check gate isn't wired on the org, expected on scratch orgs) does **not** block: a successful create/publish/activate is authoritative. A later `403 FUNCTIONALITY_NOT_ENABLED` on the write is the same signal as `hasAccess=false` — trigger the same hand-off offer.
+
+## Phase 2 — Idempotency: does the target agent already exist, and is it active?
+
+Idempotency is keyed **PRIMARILY** on the template's `botDefinitionId` (captured in Phase 1) and **FALLS BACK** to the collected `<developerName>`. The `botDefinitionId` is the platform's authoritative link from the `agent-templates` row to the `BotDefinition` it was instantiated into, but it is back-filled **only** for pre-provisioned agents — and the Fulfiller is never pre-provisioned: this skill's create path never stamps `templateName`, so its template `botDefinitionId` is `null` on the first run and every run after. The `DeveloperName`-keyed fallback is therefore the guard that actually catches repeat runs (if the agent already exists under a `DeveloperName` matching the collected `<developerName>`, a name-only miss would let the create fail with `DUPLICATE_VALUE`), so never short-circuit to create when `botDefinitionId` is absent.
+
+- **`template.botDefinitionId` is empty/null** (the normal Fulfiller case) ⇒ fall back to a DeveloperName-keyed read (do **not** short-circuit to create — a self-created agent from a prior run has a null template `botDefinitionId` but still exists). The `BotVersions` subquery is required — omitting it leaves `needsActivation` permanently false and hides the reactivation path:
+  ```bash
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE DeveloperName='<developerName>'" \
+    --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "" "<developerName>"
+  ```
+- **`template.botDefinitionId` is present** (a pre-provisioned instantiation, if any — never the normal Fulfiller case) ⇒ read the `BotDefinition` by Id **`OR` by the collected `<developerName>`** in one query, INCLUDING its latest version's status, then classify. The `OR DeveloperName=` clause is what catches a **dangling** template→BotDefinition link — a `botDefinitionId` whose target row was since deleted: the by-Id half returns nothing, but the live same-name agent still surfaces, so the classifier falls back to it (`matchedBy:"developerName"`) instead of concluding `exists:false` and letting the create collide with `DUPLICATE_VALUE`:
+  ```bash
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" \
+    --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId>" "<developerName>"
+  ```
+
+The classifier prints `{ exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }` — `matchedBy` is `"botDefinitionId"` | `"developerName"` | `null`, and `developerName` is the ACTUAL live agent's DeveloperName read from the record, surface it in the report rather than the collected guess:
+
+- `exists:false` ⇒ proceed to Phase 3 (create path).
+- `exists:true` and `needsActivation:false` (latest version `Active`) ⇒ **ALREADY-CREATED** — skip the write, fall through to Phase 7 verification.
+- `exists:true` and `needsActivation:true` (latest version `Inactive`) ⇒ do **not** create a duplicate agent — go to Phase 2b to offer activating the existing version instead.
+- A non-zero exit (exit 3) means the query itself failed — surface the raw CLI error, do not assume the agent is absent.
+
+## Phase 2b — Reactivation offer (existing agent found inactive)
+
+Present the discovery to the user via `AskUserQuestion`: _"A Fulfiller agent named `<developerName>` already exists but its latest version is Inactive. Activate the existing version instead of creating a new agent?"_ (options: **Yes, activate the existing version** / **No, stop here**).
+
+- On **Yes**: activate the captured `latestVersionId` directly — no create/publish needed since the `BotDefinition`/`BotVersion` already exist:
+  ```bash
+  sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" \
+    --method POST --body '{"status":"Active"}' \
+    --target-org <alias> > ${SCRATCH_DIR}/activate-existing.json 2>${SCRATCH_DIR}/activate-existing.err || true
+  ```
+  On success, skip Phases 3–6 entirely (no create/publish/confirm-to-write for a fresh agent) and go straight to Phase 7 to verify. Report the aggregate verdict as **ACTIVATED** in Phase 8, not CREATED.
+- On **No**: stop and report the current state (agent exists, latest version Inactive) without any writes.
+
+## Phase 3 — Confirm-to-Write Checkpoint (REQUIRED, create path only)
+
+**Before raising the confirmation gate**, if `${outputDir}` was provided, render the report file via `scripts/render-report.mjs` with `verdict:"PENDING CONFIRMATION"` so it exists even if the harness parks at the question. Skip this write for interactive runs. Report-state JSON shape + checkpoint policy live in `references/report-format.md`.
+
+```bash
+node "<skill_dir>/scripts/render-report.mjs" ${SCRATCH_DIR}/report-state.json "${outputDir}/report.md"
+```
+
+THEN **present the exact create request** (developerName + label, NGA-native from the Fulfiller template's Agent Script) and require an explicit "yes" via `AskUserQuestion`. **Proceed to Phase 4 ONLY on an explicit "yes".** On "no", stop and — if `${outputDir}` was provided — re-render with `verdict:"DECLINED"` and a one-line `reason`. Never fabricate a partial "create-only" outcome.
+
+## Phase 4 — Create the NGA bundle
+
+Build the `createBundleWithVersion` request body with the helper — it re-reads the Phase-1 `agent-templates.json`, extracts the matched template's `agentScript`, fully HTML-decodes it, and substitutes its internal `config.developer_name` / `config.agent_label` with the **collected** `<developerName>` / `<label>` (so the bundle's outer `apiName` and the script's internal identity match), keeping the large script content and free-text quotes out of an inline shell string:
+
+```bash
+node "<skill_dir>/scripts/build-create-body.mjs" ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json
+sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" \
+  --method POST \
+  --body @${SCRATCH_DIR}/create-bundle-body.json \
+  --target-org <alias> > ${SCRATCH_DIR}/create-bundle.json 2>${SCRATCH_DIR}/create-bundle.err || true
+```
+
+On success, the `POST /nextgen-authoring/bundles` response is a bundle-version detail: `{ apiName, label, bundleId, id, versionStatus:"DRAFT", assets:[...], ... }`. **Capture `id` — that is the `bundleVersionId` used in Phases 5 and 6, not `bundleId`.**
+
+- `403 FUNCTIONALITY_NOT_ENABLED` / `404` → trigger the Phase-1 prerequisite hand-off offer (the NGA authoring namespace isn't provisioned on the org).
+- A build-script exit 3 (template or `agentScript` not found in `${SCRATCH_DIR}/agent-templates.json`) → surface the script's stderr verbatim and stop; do not retry with a hand-typed template id.
+
+## Phase 5 — Publish the bundle version
+
+Publish the captured `bundleVersionId` — empty `--body '{}'` required (the CLI rejects a POST with no `--body`):
+
+```bash
+sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" \
+  --method POST --body '{}' \
+  --target-org <alias> > ${SCRATCH_DIR}/publish-bundle.json 2>${SCRATCH_DIR}/publish-bundle.err || true
+```
+
+On success: `{ lastPublishedOn, publishedBotId, publishedBotVersionId }`. This is the call that creates the underlying `BotDefinition`/`BotVersion`. An error here means the DRAFT version failed platform-side validation — surface it verbatim; do not attempt to activate an unpublished version.
+
+## Phase 6 — Activate the bundle version
+
+Activate the same `bundleVersionId`:
+
+```bash
+sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" \
+  --method POST --body '{}' \
+  --target-org <alias> > ${SCRATCH_DIR}/activate-bundle.json 2>${SCRATCH_DIR}/activate-bundle.err || true
+```
+
+Success returns an **empty body** — do not treat empty stdout as a failure; check the CLI exit code and fall through to Phase 7 to confirm via `BotDefinition`/`BotVersion` state instead of parsing a response payload.
+
+## Phase 7 — Verify the agent is live
+
+Read `BotDefinition` by Id (with `BotVersions` subquery, same shape as Phase 2) and classify. The verify `<verifyId>` is the create path's **`publishedBotId`** (captured from the Phase-5 publish response) or, on the ALREADY-CREATED / reactivation path, the **live matched Id the Phase-2 classifier returned** (its `botDefinitionId`/`agentId` output — the actual `BotDefinition.Id` of the matched record), **not** the Phase-1 template `botDefinitionId` (which is always `null` for the Fulfiller, so on any existing-agent hit using it would run the verify as `WHERE Id=''` and falsely report failure after a successful skip/activation). Never the collected `<developerName>`:
+
+```bash
+sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<verifyId>'" \
+  --target-org <alias> --json > ${SCRATCH_DIR}/bot-verify.json 2>${SCRATCH_DIR}/bot-verify.err || true
+node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-verify.json "<verifyId>"
+```
+
+Confirm `exists:true` with `count:1`, and — on the create or reactivation path — `latestVersionStatus:"Active"`. `exists:false` after a successful activate ⇒ report the discrepancy verbatim, do not fabricate success. Optionally cross-check `GET /nextgen-authoring/bundles` for an entry with the collected `apiName` and `isLegacy:false` to confirm the agent is NGA-native (no external-link icon in Agentforce Studio).
+
+## Phase 8 — Aggregate verdict
+
+Report CREATED / ALREADY-CREATED / ACTIVATED / FAILED plus the `BotDefinition` Id / bundle `id`. Use **ACTIVATED** when Phase 2b's reactivation path was taken (existing agent found inactive, activated instead of creating new). Emit the final report by re-invoking `scripts/render-report.mjs` — the single source of report text. If `${outputDir}` was provided, overwrite `${outputDir}/report.md`; otherwise emit the helper's stdout as the turn-side report.
+
+```bash
+node "<skill_dir>/scripts/render-report.mjs" ${SCRATCH_DIR}/report-state.json "${outputDir}/report.md"
+```

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/scripts/build-create-body.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Build the NGA createBundleWithVersion request body from the shipped
+// Fulfiller template's agentScript.
+//
+// The legacy `agent-templates` read already returns the template's full Agent
+// Script (AFScript) content in its `agentScript` field, HTML-entity-encoded
+// (sometimes double-encoded). This script:
+//   1. Locates the matching template item by masterLabel in the
+//      agent-templates response.
+//   2. Fully HTML-decodes `agentScript` (named + numeric entities, multi-pass
+//      to unwind double-encoding).
+//   3. Substitutes the script's internal `config.developer_name` /
+//      `config.agent_label` with the collected <developerName> / <label> —
+//      the bundle's outer apiName must match the script's internal
+//      developer_name or the two diverge (the platform will otherwise
+//      auto-suffix the apiName).
+//   4. Writes the createBundleWithVersion body
+//      { apiName, label, assets: [{ resourceName: "agentDefinition",
+//        resourceType: "agentDefinition", sections: [], resourceContent }] }
+//      to <outPath>.
+//
+// Usage:
+//   node build-create-body.mjs <agent-templates.json> <masterLabel> <developerName> <label> <outPath>
+//
+// Exits 2 on missing/bad args, 3 if the template or its agentScript can't be found.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const [templatesPath, masterLabel, developerName, label, outPath] = process.argv.slice(2);
+if (!templatesPath || !masterLabel || !developerName || !label || !outPath) {
+  process.stderr.write('usage: node build-create-body.mjs <agent-templates.json> <masterLabel> <developerName> <label> <outPath>\n');
+  process.exit(2);
+}
+
+function decodeHtmlEntities(text) {
+  let prev = text;
+  for (let pass = 0; pass < 4; pass += 1) {
+    const next = prev
+      .replace(/&amp;/g, '&')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(parseInt(code, 10)));
+    if (next === prev) break;
+    prev = next;
+  }
+  return prev;
+}
+
+let templatesData;
+try {
+  templatesData = JSON.parse(readFileSync(templatesPath, 'utf8'));
+} catch {
+  process.stderr.write(`error: could not read/parse ${templatesPath}\n`);
+  process.exit(3);
+}
+
+const items = Array.isArray(templatesData?.data) ? templatesData.data : [];
+const wanted = String(masterLabel).trim().toLowerCase();
+const match = items.find((it) => String(it?.masterLabel ?? '').trim().toLowerCase() === wanted);
+if (!match) {
+  process.stderr.write(`error: no template with masterLabel "${masterLabel}" found in ${templatesPath}\n`);
+  process.exit(3);
+}
+if (!match.agentScript || typeof match.agentScript !== 'string' || !match.agentScript.trim()) {
+  process.stderr.write(`error: template "${masterLabel}" (id=${match.id}) has no agentScript content\n`);
+  process.exit(3);
+}
+
+// Escapes a value for use as a YAML double-quoted scalar — the agentScript's
+// developer_name/agent_label fields are plain `"..."` strings, so a raw
+// double-quote or backslash in a user-supplied label would otherwise break
+// out of the scalar (e.g. label `Sam "Ops"` -> `agent_label: "Sam "Ops""`).
+function yamlDoubleQuoteEscape(text) {
+  return String(text).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+const decoded = decodeHtmlEntities(match.agentScript);
+const developerNameEscaped = yamlDoubleQuoteEscape(developerName);
+const labelEscaped = yamlDoubleQuoteEscape(label);
+
+const substituted = decoded
+  .replace(/developer_name:\s*"[^"]*"/, `developer_name: "${developerNameEscaped}"`)
+  .replace(/agent_label:\s*"[^"]*"/, `agent_label: "${labelEscaped}"`);
+
+if (!substituted.includes(`developer_name: "${developerNameEscaped}"`)) {
+  process.stderr.write('error: failed to substitute config.developer_name in the decoded agentScript\n');
+  process.exit(3);
+}
+if (!substituted.includes(`agent_label: "${labelEscaped}"`)) {
+  process.stderr.write('error: failed to substitute config.agent_label in the decoded agentScript\n');
+  process.exit(3);
+}
+
+const body = {
+  apiName: developerName,
+  label,
+  assets: [
+    {
+      resourceName: 'agentDefinition',
+      resourceType: 'agentDefinition',
+      sections: [],
+      resourceContent: substituted,
+    },
+  ],
+};
+
+writeFileSync(outPath, JSON.stringify(body), 'utf8');
+process.stdout.write(outPath + '\n');

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

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// Deterministic action-availability classifier for the NGA agent activation flow.
+//
+// The Fulfiller Agent Script references a fixed set of `svc_itsm_intelligence__*`
+// invocable actions via its `source:` and `target:` fields (e.g.
+// `source: "svc_itsm_intelligence__SummarizeIncident"`,
+// `target: "generatePromptResponse://svc_itsm_intelligence__SummarizeIncident"`).
+// A bundle version cannot activate when any of those actions is not surfaced by
+// `/services/data/v67.0/actions/custom/generatePromptResponse` for the running
+// user — the activate endpoint returns HTTP 200 with `{success:false,
+// messages:[{... "does not exist"}]}` (silent-failure body). Diagnosing that
+// after the fact is expensive; this classifier flags the mismatch BEFORE the
+// activate call.
+//
+// Two fixed rules (A9 — no prose interpretation):
+//   1. Enumerate every `svc_*__<ActionName>` token that appears inside a
+//      `source:` or `target:` line of the decoded Agent Script.
+//   2. Enumerate every action name exposed by
+//      `/actions/custom/generatePromptResponse` — accepts both response shapes:
+//        (a) legacy `{ actions: [ { name, ... }, ... ] }`
+//        (b) newer  `{ actions: { <fullyQualifiedName>: {...}, ... } }`
+//   Emit `missing = referenced - present`. If missing.length > 0 ⇒ verdict
+//   NOT-READY. On non-parseable inputs, verdict is CANNOT-CONFIRM (never block
+//   on unreadable state — surface it and let the workflow decide).
+//
+// Usage:
+//   node classify-action-availability.mjs \
+//        <agent-templates.json> <masterLabel> <generate-prompt-response.json>
+//
+// <agent-templates.json>          — Phase-1 `agent-templates` capture; the matched
+//                                    template's `agentScript` is decoded exactly
+//                                    like build-create-body.mjs decodes it, then
+//                                    scanned for source:/target: action tokens.
+// <masterLabel>                   — the display label of the target template
+//                                    (e.g. "IT Service Fulfiller").
+// <generate-prompt-response.json> — GET
+//                                    /services/data/v67.0/actions/custom/generatePromptResponse
+//                                    response body.
+//
+// Emits a single JSON object to stdout:
+//   { referenced: [...],
+//     present:    [...],
+//     missing:    [...],
+//     verdict: "READY" | "NOT-READY" | "CANNOT-CONFIRM",
+//     reasons: [...] }
+// Exit is always 0 on parseable inputs; the verdict is carried in the payload.
+// A truly unreadable input (missing/malformed file) becomes CANNOT-CONFIRM +
+// exit 0 so the caller can surface the raw CLI error rather than assuming
+// READY.
+
+import { readFileSync } from 'node:fs';
+
+function readJson(path) {
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false, reason: `empty file: ${path}` };
+    return { ok: true, data: JSON.parse(text) };
+  } catch (e) {
+    return { ok: false, reason: `unreadable/invalid JSON at ${path}: ${e?.message ?? e}` };
+  }
+}
+
+// Multi-pass HTML entity decode — matches build-create-body.mjs so both see the
+// same script content. Connect API bodies can be double-encoded.
+const NAMED = { amp: '&', quot: '"', apos: "'", lt: '<', gt: '>', '#39': "'", nbsp: ' ' };
+function decodeEntitiesOnce(s) {
+  return s.replace(/&(#?\w+);/g, (m, ref) => {
+    if (ref.startsWith('#')) {
+      const n = ref[1] === 'x' || ref[1] === 'X' ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
+      return Number.isFinite(n) ? String.fromCodePoint(n) : m;
+    }
+    return Object.prototype.hasOwnProperty.call(NAMED, ref) ? NAMED[ref] : m;
+  });
+}
+function decodeEntities(s) {
+  let prev = s, next = decodeEntitiesOnce(s);
+  while (next !== prev) { prev = next; next = decodeEntitiesOnce(next); }
+  return next;
+}
+
+function extractReferencedActions(scriptText) {
+  // Only lines whose YAML key is `source` or `target` are load-bearing — a
+  // namespace-prefixed action name mentioned inside a description, instruction,
+  // or comment is documentation, not a required invocation. Scanning globally
+  // would mis-flag such a mention as NOT-READY and block a valid activation.
+  //
+  // Agent Script YAML forms observed:
+  //   source: "svc_itsm_intelligence__SummarizeIncident"
+  //   source: svc_itsm_intelligence__SummarizeIncident
+  //   target: "generatePromptResponse://svc_itsm_intelligence__SummarizeIncident"
+  //   - source: "..."
+  //
+  // The key line regex tolerates leading whitespace, an optional YAML list dash,
+  // and both quoted and unquoted scalar values (single line). Block scalars
+  // (`source: |`) are extraordinarily rare for these fields and safely fall
+  // through to CANNOT-CONFIRM when nothing is extracted.
+  const referenced = new Set();
+  const tokenRe = /\bsvc_[a-z0-9_]+__[A-Za-z][A-Za-z0-9_]*\b/g;
+  const keyLineRe = /^[ \t]*-?[ \t]*(?:source|target)[ \t]*:[ \t]*(.*)$/;
+  for (const rawLine of scriptText.split(/\r?\n/)) {
+    const km = keyLineRe.exec(rawLine);
+    if (!km) continue;
+    const value = km[1];
+    for (const m of value.matchAll(tokenRe)) {
+      referenced.add(m[0]);
+    }
+  }
+  return [...referenced].sort();
+}
+
+function extractPresentActions(actionsData) {
+  const present = new Set();
+  if (!actionsData || typeof actionsData !== 'object') return [];
+  const a = actionsData.actions;
+  if (Array.isArray(a)) {
+    // Shape (a): [ { name, ... }, ... ]
+    for (const it of a) {
+      if (it && typeof it === 'object') {
+        const nm = typeof it.name === 'string' ? it.name : null;
+        if (nm) present.add(nm);
+        const label = typeof it.label === 'string' ? it.label : null;
+        if (label && /svc_[a-z0-9_]+__/.test(label)) present.add(label);
+      }
+    }
+  } else if (a && typeof a === 'object') {
+    // Shape (b): { <name>: {...}, ... }
+    for (const key of Object.keys(a)) present.add(key);
+  }
+  return [...present].sort();
+}
+
+function findTemplateScript(agentTemplatesData, masterLabel) {
+  if (!agentTemplatesData || typeof agentTemplatesData !== 'object') return null;
+  const items = Array.isArray(agentTemplatesData.data) ? agentTemplatesData.data : null;
+  if (!items) return null;
+  const wanted = String(masterLabel).trim().toLowerCase();
+  const match = items.find((it) => String(it?.masterLabel ?? '').trim().toLowerCase() === wanted);
+  if (!match || typeof match.agentScript !== 'string' || !match.agentScript.trim()) return null;
+  return decodeEntities(match.agentScript);
+}
+
+const [templatesPath, rawLabel, actionsPath] = process.argv.slice(2);
+if (!templatesPath || !rawLabel || !actionsPath) {
+  process.stderr.write('usage: node classify-action-availability.mjs <agent-templates.json> <masterLabel> <generate-prompt-response.json>\n');
+  process.exit(2);
+}
+
+const templatesRead = readJson(templatesPath);
+const actionsRead = readJson(actionsPath);
+
+if (!templatesRead.ok) {
+  process.stdout.write(JSON.stringify({
+    referenced: [], present: [], missing: [],
+    verdict: 'CANNOT-CONFIRM',
+    reasons: [templatesRead.reason],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+if (!actionsRead.ok) {
+  process.stdout.write(JSON.stringify({
+    referenced: [], present: [], missing: [],
+    verdict: 'CANNOT-CONFIRM',
+    reasons: [actionsRead.reason],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+const scriptText = findTemplateScript(templatesRead.data, rawLabel);
+if (!scriptText) {
+  process.stdout.write(JSON.stringify({
+    referenced: [], present: [], missing: [],
+    verdict: 'CANNOT-CONFIRM',
+    reasons: [`No template with masterLabel "${rawLabel}" carrying a non-empty agentScript in agent-templates response.`],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+const referenced = extractReferencedActions(scriptText);
+const present = extractPresentActions(actionsRead.data);
+const presentSet = new Set(present);
+const missing = referenced.filter((r) => !presentSet.has(r));
+
+let verdict, reasons;
+if (referenced.length === 0) {
+  verdict = 'CANNOT-CONFIRM';
+  reasons = ['No svc_*__ action tokens were found in the decoded Agent Script — either the script does not use namespace-prefixed invocables or decoding failed. Surface and continue with caution.'];
+} else if (missing.length === 0) {
+  verdict = 'READY';
+  reasons = [`All ${referenced.length} template-referenced invocable action(s) are surfaced by /actions/custom/generatePromptResponse for the running user.`];
+} else {
+  verdict = 'NOT-READY';
+  reasons = [
+    `${missing.length} of ${referenced.length} template-referenced invocable action(s) are NOT surfaced by /actions/custom/generatePromptResponse for the running user.`,
+    `Missing: ${missing.join(', ')}`,
+    'Activate will succeed at the HTTP level but return {success:false, messages:[...]} — the agent will not be usable. Offer to hand off to service-itsm-agentic-setup-itsm-agentforce-permset-assign, which handles both the permset-not-assigned case and the package-not-installed case.',
+  ];
+}
+
+process.stdout.write(JSON.stringify({
+  referenced, present, missing, verdict, reasons,
+}, null, 2) + '\n');

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

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// Deterministic post-activate result classifier for the NGA agent flow.
+//
+// The activate endpoints return **HTTP 200** on both success AND on structural
+// activation failures like "invocable action not found". The failure body is:
+//   { success: false, isActivated: false, messages: [ { code, ... } ] }
+// or an array-wrapped variant. Nothing in the CLI exit code tells the workflow
+// apart from a real success; parsing the body is the only signal.
+//
+// This helper is the single choke point (A9 — no prose interpretation) for that
+// decision, shared by:
+//   - Phase 6 (create path):     POST /nextgen-authoring/bundle-versions/<id>/activate
+//   - Phase 2b (reactivation):   POST /connect/bot-versions/<id>/activation
+//
+// Rules:
+//   - Empty body        → PASS  (documented Phase-6 success shape)
+//   - {success:true}    → PASS
+//   - {success:false}   → FAIL  (surface `messages[]` verbatim)
+//   - unparseable body  → CANNOT-CONFIRM (surface the raw file + let workflow
+//                                          fall back to the Phase-7 verify SOQL)
+//
+// Usage:
+//   node classify-activate-result.mjs <activate-response.json>
+//
+// Emits a single JSON object to stdout:
+//   { verdict: "PASS" | "FAIL" | "CANNOT-CONFIRM",
+//     success, isActivated, messages: [...], reasons: [...] }
+// Exit is always 0 on a readable file; the verdict is carried in the payload.
+
+import { readFileSync } from 'node:fs';
+
+const [respPath] = process.argv.slice(2);
+if (!respPath) {
+  process.stderr.write('usage: node classify-activate-result.mjs <activate-response.json>\n');
+  process.exit(2);
+}
+
+let text;
+try { text = readFileSync(respPath, 'utf8'); }
+catch (e) {
+  process.stdout.write(JSON.stringify({
+    verdict: 'CANNOT-CONFIRM',
+    success: null, isActivated: null, messages: [],
+    reasons: [`unreadable file: ${respPath} (${e?.message ?? e})`],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+const trimmed = text.trim();
+if (!trimmed) {
+  // Documented Phase-6 success — activate returns empty body on success.
+  process.stdout.write(JSON.stringify({
+    verdict: 'PASS',
+    success: true, isActivated: null, messages: [],
+    reasons: ['Empty response body — documented success shape for the activate endpoint. Confirm via the Phase-7 BotDefinition verify read.'],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+let parsed;
+try { parsed = JSON.parse(trimmed); }
+catch {
+  process.stdout.write(JSON.stringify({
+    verdict: 'CANNOT-CONFIRM',
+    success: null, isActivated: null, messages: [],
+    reasons: [`Activate response is non-empty but not JSON — surface it verbatim and rely on the Phase-7 verify read: ${trimmed.slice(0, 500)}`],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+// Some Connect endpoints wrap the body in a single-element array.
+const body = Array.isArray(parsed) && parsed.length === 1 && parsed[0] && typeof parsed[0] === 'object'
+  ? parsed[0]
+  : parsed;
+
+// A Connect error array (each { errorCode, message }) also arrives here on 4xx.
+if (Array.isArray(body)) {
+  const errs = body.filter((e) => e && (e.errorCode || e.message));
+  const asMsgs = errs.map((e) => ({ code: e.errorCode ?? 'ERROR', message: e.message ?? '' }));
+  process.stdout.write(JSON.stringify({
+    verdict: 'FAIL',
+    success: false, isActivated: false, messages: asMsgs,
+    reasons: ['Activate returned a Connect error array — surface every message verbatim.'],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+if (!body || typeof body !== 'object') {
+  process.stdout.write(JSON.stringify({
+    verdict: 'CANNOT-CONFIRM',
+    success: null, isActivated: null, messages: [],
+    reasons: [`Activate response is JSON but not an object — surface it and rely on the Phase-7 verify read: ${trimmed.slice(0, 500)}`],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+const success = typeof body.success === 'boolean' ? body.success : null;
+const isActivated = typeof body.isActivated === 'boolean' ? body.isActivated : null;
+const messages = Array.isArray(body.messages) ? body.messages : [];
+
+if (success === true || isActivated === true) {
+  process.stdout.write(JSON.stringify({
+    verdict: 'PASS',
+    success: success ?? true, isActivated: isActivated ?? null, messages,
+    reasons: ['Activate response indicates success. Confirm via the Phase-7 BotDefinition verify read.'],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+if (success === false || isActivated === false) {
+  const msgSnippet = messages
+    .map((m) => `${m?.code ?? m?.errorCode ?? 'ERROR'}: ${m?.message ?? ''}`.trim())
+    .join(' | ')
+    .slice(0, 800);
+  const missingAction = /does not exist|not found|no such action|invocable action/i.test(msgSnippet);
+  const reasons = [
+    `Activate returned success=false — the agent was NOT activated. Verbatim: ${msgSnippet}`,
+  ];
+  if (missingAction) {
+    reasons.push('At least one referenced invocable action is missing on this org. Prefer running scripts/classify-action-availability.mjs BEFORE activate (Phase 2c) to catch this without a wasted create/publish; if it slipped through, hand off to service-itsm-agentic-setup-itsm-agentforce-permset-assign.');
+  }
+  process.stdout.write(JSON.stringify({
+    verdict: 'FAIL',
+    success: false, isActivated: isActivated ?? false, messages,
+    reasons,
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+// Body present but no success/isActivated fields — surface + rely on verify.
+process.stdout.write(JSON.stringify({
+  verdict: 'CANNOT-CONFIRM',
+  success: null, isActivated: null, messages,
+  reasons: ['Activate body had no success/isActivated field — surface it and rely on the Phase-7 verify read.'],
+}, null, 2) + '\n');