@salesforce/afv-skills 1.40.0 → 1.41.0

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// Deterministic idempotency / verification classifier for the Fulfiller-agent create flow.
+//
+// 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`.
+// 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.)
+//
+// 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
+// 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]
+//
+// 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,
+//     (SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1)
+//     FROM BotDefinition WHERE Id='<botDefinitionId>' 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.
+// `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
+// needsActivation false, which silently disables the reactivation path.)
+//
+// Emits a single JSON object to stdout:
+//   { exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }
+// where exists is true|false, developerName is the ACTUAL DeveloperName read
+// from the matched record (NOT the collected guess `IT_Service_Fulfiller_Agent`)
+// — so the report surfaces the live agent's real identity;
+// latestVersionStatus is "Active"|"Inactive"|null (null means no BotVersion
+// 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
+// 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);
+if (!queryPath) {
+  process.stderr.write('usage: node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName]\n');
+  process.exit(2);
+}
+
+// Salesforce Ids compare on their case-sensitive 15-char base (the trailing 3
+// chars are a case-normalizing checksum), so a 15-char and an 18-char form of
+// the same record compare equal on the first 15 chars.
+function idKey(v) {
+  return String(v ?? '').trim().slice(0, 15);
+}
+
+function notSet(v) {
+  const s = String(v ?? '').trim().toLowerCase();
+  return s === '' || s === '-' || s === 'null' || s === 'undefined';
+}
+
+const botDefinitionId = String(rawBotDefinitionId ?? '').trim();
+const developerName = String(rawDeveloperName ?? '').trim();
+const noId = notSet(botDefinitionId);
+const noName = notSet(developerName);
+
+const NOT_EXISTS = {
+  exists: false,
+  count: 0,
+  matchedBy: null,
+  agentId: null,
+  botDefinitionId: null,
+  developerName: null,
+  latestVersionId: null,
+  latestVersionStatus: null,
+  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) {
+  process.stdout.write(JSON.stringify(NOT_EXISTS, null, 2) + '\n');
+  process.exit(0);
+}
+
+let data;
+try {
+  const text = readFileSync(queryPath, 'utf8').trim();
+  data = text ? JSON.parse(text) : null;
+} catch {
+  process.stderr.write(`error: could not read/parse ${queryPath}\n`);
+  process.exit(3);
+}
+
+// A failed `sf data query --json` has status !== 0 (e.g. malformed SOQL, auth error).
+// Do NOT treat that as "agent does not exist" — surface it.
+if (!data || (typeof data.status === 'number' && data.status !== 0) || data.result === undefined) {
+  process.stderr.write('error: query did not return a results envelope; surface the raw CLI error and stop\n');
+  process.exit(3);
+}
+
+const records = Array.isArray(data.result?.records) ? data.result.records : [];
+
+// PRIMARY key: the template's `botDefinitionId` (the platform's authoritative
+// template→BotDefinition link) — catches a pre-provisioned agent whose live
+// DeveloperName differs from this skill's collected guess. For the Fulfiller this
+// branch is defensive: the template `botDefinitionId` is null on every run (the
+// Fulfiller is never pre-provisioned and this skill's create path never stamps
+// `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
+// 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.
+let matches = [];
+let matchedBy = null;
+if (!noId) {
+  const wantedIdKey = idKey(botDefinitionId);
+  matches = records.filter((r) => idKey(r?.Id) === wantedIdKey);
+  if (matches.length) matchedBy = 'botDefinitionId';
+}
+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';
+}
+const exists = matches.length > 0;
+
+// The BotVersions child subquery (if present in the SOQL) surfaces the latest
+// version's Status so we can tell "already created and active" apart from
+// "already created but inactive" — the latter should offer reactivation
+// instead of a silent ALREADY-CREATED skip. The actual BotVersion status is
+// authoritative over the template's `isActivated` flag.
+const latestVersion = exists ? matches[0]?.BotVersions?.records?.[0] ?? null : null;
+const latestVersionStatus = latestVersion?.Status ?? null;
+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.
+  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.
+  botDefinitionId: exists ? (matches[0].Id ?? null) : (noId ? null : botDefinitionId),
+  developerName: exists ? (matches[0].DeveloperName ?? null) : null,
+  latestVersionId: latestVersion?.Id ?? null,
+  latestVersionStatus,
+  needsActivation,
+}, null, 2) + '\n');

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

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// Deterministic preflight classifier for the Fulfiller-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 Fulfiller"), 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 Fulfiller").
+//
+// Emits a single JSON object to stdout:
+//   { studio: { hasAccess, signal, reason },
+//     template: { present, id, hasAgentScript, botDefinitionId, 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
+// `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 createAgent 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 createAgent 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).' };
+  const wanted = String(masterLabel).trim().toLowerCase();
+  const match = items.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.'
+        : `No template with masterLabel "${masterLabel}" in data[] (got: ${items.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 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.
+  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.` };
+}
+
+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 Fulfiller';
+
+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 — createAgent 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 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".
+    botDefinitionId: template.botDefinitionId ?? null,
+    signal: template.signal,
+    reason: template.reason,
+  },
+  verdict,
+  reasons: [studio.reason, template.reason],
+}, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/scripts/create-scratch-dir.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Deterministic Phase-0 scratch-directory creator for the Fulfiller-agent
+// create/activate flow.
+//
+// Phase-0 path selection + `mkdtemp` behavior are deterministic and must not
+// live in workflow prose (authoring standard A9).
+//
+// The scratch dir MUST stay OUTSIDE the harness's scored `${outputDir}` tree.
+// Several phases capture raw `sf api request rest` stdout, and that command is
+// in beta — it prints beta/update/plugin diagnostics to STDERR. If an agent
+// captures combined output (`2>&1`) instead of the documented `2>…err` split,
+// that stderr preamble is merged into the captured file; a raw capture rooted
+// under `${outputDir}` would then land in the eval's scored artifact set and
+// fail the `core:json-valid` assertion even though the response body itself is
+// well-formed JSON. So the scratch dir roots under `${TMPDIR}` (private,
+// user-scoped), then `/tmp`, and only as an ultimate fallback (both temp bases
+// unwritable) under the harness `${outputDir}`. `mkdtempSync` creates the run
+// dir mode 0700 (owner-only) with a random suffix, so the world-writable `/tmp`
+// parent is not a concern. Only the durable `${outputDir}/report.md` (written
+// directly by render-report.mjs) is ever meant to be scored.
+//
+// Usage:
+//   node create-scratch-dir.mjs [outputDir]
+//
+// Emits the absolute path of the created directory to stdout (a single line,
+// trailing newline). Exit 0 on success, 3 when no candidate base is writable.
+
+import { mkdtempSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PREFIX = 'itsm-fulfiller-agent.';
+
+// Candidate scratch bases, in priority order. `${outputDir}` is LAST so
+// transient captures never enter the scored tree except when no temp dir works.
+const candidates = [];
+const tmp = (process.env.TMPDIR ?? '').trim();
+if (tmp) candidates.push(tmp);
+candidates.push('/tmp');
+const outputDir = (process.argv[2] ?? '').trim();
+if (outputDir) candidates.push(outputDir);
+
+let dir = null;
+let lastErr = null;
+for (const base of candidates) {
+  try {
+    dir = mkdtempSync(join(base, PREFIX));
+    break;
+  } catch (err) {
+    lastErr = err;
+  }
+}
+
+if (dir) {
+  process.stdout.write(`${dir}\n`);
+} else {
+  process.stderr.write(`error: mkdtemp failed under all of [${candidates.join(', ')}]: ${lastErr?.message ?? 'no base dir'}\n`);
+  process.exit(3);
+}

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

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// Deterministic renderer for the Fulfiller-agent create/activate report.
+//
+// Composing the report from phase state in model prose is unreliable
+// (authoring standard A9) — the layout, field placement, and next-step
+// wording all belong in a script that emits byte-identical output for a
+// given state input. This helper is the single source of report text for
+// both the chat-turn response and the harness's ${outputDir}/report.md
+// file, so the two never diverge.
+//
+// Usage:
+//   node render-report.mjs <state.json> [outPath]
+//
+// state.json shape (all fields optional except `verdict`):
+//   {
+//     "org":            string,
+//     "developerName":  string,
+//     "label":          string,
+//     "preflight":      { "studioHasAccess": "true" | "false" | "cannot-confirm",
+//                         "templateAgentScriptPresent": "yes" | "no" | "pending" },
+//     "enumerate":      { "existsBeforeWrite": "yes" | "no" | "pending",
+//                         "latestVersionStatus": "Active" | "Inactive" | "n/a" | "pending" },
+//     "confirmToWrite": "true" | "false" | "pending",
+//     "createBundle":   string,
+//     "publish":        string,
+//     "activate":       string,
+//     "verify":         string,
+//     "verdict":        "CREATED" | "ALREADY-CREATED" | "ACTIVATED" |
+//                       "PENDING CONFIRMATION" | "DECLINED" | "FAILED",
+//     "reason":         string
+//   }
+//
+// If `outPath` is provided, writes to that path; otherwise emits to stdout.
+// The rendered report is always ~30 lines and shape-identical run to run.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const [statePath, outPath] = process.argv.slice(2);
+if (!statePath) {
+  process.stderr.write('usage: node render-report.mjs <state.json> [outPath]\n');
+  process.exit(2);
+}
+
+let state;
+try {
+  state = JSON.parse(readFileSync(statePath, 'utf8'));
+} catch (err) {
+  process.stderr.write(`error: could not read/parse ${statePath}: ${err.message}\n`);
+  process.exit(3);
+}
+
+const VALID_VERDICTS = new Set([
+  'CREATED', 'ALREADY-CREATED', 'ACTIVATED',
+  'PENDING CONFIRMATION', 'DECLINED', 'FAILED',
+]);
+const verdict = String(state?.verdict ?? '').trim();
+if (!VALID_VERDICTS.has(verdict)) {
+  process.stderr.write(`error: verdict "${verdict}" is not one of: ${[...VALID_VERDICTS].join(', ')}\n`);
+  process.exit(3);
+}
+
+function field(v, fallback = 'pending') {
+  const s = v === undefined || v === null ? '' : String(v).trim();
+  return s === '' ? fallback : s;
+}
+
+const org = field(state.org, '<unspecified>');
+const devName = field(state.developerName, '<pending>');
+const label = field(state.label, '<pending>');
+
+const preStudio = field(state?.preflight?.studioHasAccess, 'pending');
+const preTmpl = field(state?.preflight?.templateAgentScriptPresent, 'pending');
+const enumExists = field(state?.enumerate?.existsBeforeWrite, 'pending');
+const enumVer = field(state?.enumerate?.latestVersionStatus, 'pending');
+
+function classifyPreflightVerdict() {
+  const explicit = field(state?.preflight?.verdict, '');
+  if (explicit !== 'pending' && explicit !== '') return explicit;
+  if (preStudio === 'false' || preTmpl === 'no') return 'NOT-READY';
+  const okStudio = preStudio === 'true';
+  const okTmpl = preTmpl === 'yes';
+  if (okStudio && okTmpl) return 'READY';
+  if (preStudio === 'cannot-confirm' || preTmpl === 'pending') return 'CANNOT-CONFIRM';
+  return 'pending';
+}
+function classifyEnumerate() {
+  const explicit = field(state?.enumerate?.verdict, '');
+  if (explicit !== 'pending' && explicit !== '') return explicit;
+  if (enumExists === 'yes') {
+    if (enumVer === 'Active') return 'exists:true, needsActivation:false';
+    if (enumVer === 'Inactive') return 'exists:true, needsActivation:true';
+    return 'exists:true';
+  }
+  if (enumExists === 'no') return 'exists:false';
+  return 'pending';
+}
+const preVerdict = classifyPreflightVerdict();
+const enumVerdict = classifyEnumerate();
+
+const confirm = field(state.confirmToWrite, 'pending');
+const isPending = verdict === 'PENDING CONFIRMATION';
+const isDeclined = verdict === 'DECLINED';
+const isCreated = verdict === 'CREATED';
+const isActivated = verdict === 'ACTIVATED';
+const isAlready = verdict === 'ALREADY-CREATED';
+const isFailed = verdict === 'FAILED';
+const gatedFallback = isPending
+  ? 'pending confirmation'
+  : isDeclined ? 'skipped'
+  : isAlready ? 'skipped (already exists)'
+  : isFailed ? 'skipped'
+  : 'pending';
+
+const bundleVersionId = field(state.bundleVersionId, '');
+const bundleVersionIdSuffix = bundleVersionId ? ` bundleVersionId=${bundleVersionId}` : '';
+const onBundleVersionId = bundleVersionId ? ` on bundleVersionId=${bundleVersionId}` : '';
+
+function withCreateSuffix(base) {
+  if (base === 'pending' || base.startsWith('skipped') || base === 'pending confirmation') return base;
+  return `${base}${bundleVersionIdSuffix}`;
+}
+function withPublishActivateSuffix(base) {
+  if (base === 'pending' || base.startsWith('skipped') || base === 'pending confirmation') return base;
+  return `${base}${onBundleVersionId}`;
+}
+
+const createBundle = withCreateSuffix(field(state.createBundle, gatedFallback));
+const publish = withPublishActivateSuffix(field(state.publish, gatedFallback));
+const activate = withPublishActivateSuffix(field(state.activate, gatedFallback));
+const verifyFallback = isDeclined || isPending || isFailed
+  ? 'skipped'
+  : isAlready
+    ? `exists:true; latestVersionStatus=${enumVer}`
+    : 'pending';
+let verify = field(state.verify, verifyFallback);
+if (
+  (isCreated || isActivated) &&
+  verify !== 'pending' &&
+  !verify.startsWith('skipped') &&
+  !/exists\s*[:=]/i.test(verify)
+) {
+  verify = `${verify}; exists:true; latestVersionStatus=Active`;
+}
+
+const reason = String(state.reason ?? '').trim();
+
+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.',
+  '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.',
+  '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.',
+  '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':
+    'No write occurred. This skill\'s create + publish + activate run 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. The user\'s decline (or "hold off on activation") kept the run at the gate. Re-run and confirm when ready for the full sequence.',
+  'FAILED':
+    reason
+      ? `Review the Reason above and remediate. Enablement of missing prerequisites is a Setup-UI/admin action outside this skill's scope — use \`service-itsm-agentic-setup-agentforce-studio-validate\` or \`service-itsm-agentic-setup-agentforce-studio-configure\` to check/enable readiness first. Re-run this skill once the blocker is resolved.`
+      : 'Review the observed error and remediate. Enablement of missing prerequisites is a Setup-UI/admin action outside this skill\'s scope — use `service-itsm-agentic-setup-agentforce-studio-validate` or `service-itsm-agentic-setup-agentforce-studio-configure` to check/enable readiness first. Re-run this skill once the blocker is resolved.',
+};
+
+const report = `# Fulfiller Agent — Create & Activate
+
+IT Service Fulfiller Agent Creation (via service-itsm-agentic-setup-fulfiller-agent-configure)
+
+Org:      ${org} (API v67.0)
+Agent:    ${devName} ("${label}") — NGA-native bundle
+
+  Preflight  ......................... Studio hasAccess=${preStudio}; template agentScript present=${preTmpl}; verdict=${preVerdict}
+  Enumerate  ......................... target agent exists before write=${enumExists}; latest version status=${enumVer}; verdict=${enumVerdict}
+  Confirm-to-write ................... user-confirmed=${confirm}${(confirm === 'true' && (devName !== '<pending>' || label !== '<pending>')) ? `; confirmed developerName=${devName}, label="${label}"` : ''}
+  Create bundle ...................... ${createBundle}
+  Publish ............................ ${publish}
+  Activate ........................... ${activate}
+  Verify ............................. ${verify}
+
+Verdict: ${verdict}
+Reason:  ${reason}
+
+Next steps:
+  - ${NEXT_STEPS[verdict]}
+`;
+
+if (outPath) {
+  writeFileSync(outPath, report, 'utf8');
+  process.stdout.write(outPath + '\n');
+} else {
+  process.stdout.write(report);
+}