@salesforce/afv-skills 1.44.0 → 1.45.0

package/skills/service-itsm-agentic-setup-agent-runtime-access-assign/scripts/classify-activated-agents.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// Deterministic classifier for the ACTIVATED agents a user needs access to.
+//
+// Reads ONE input:
+//   - BotDefinition query capture (from `sf data query --json`) shaped as:
+//       SELECT Id, DeveloperName, MasterLabel,
+//              (SELECT Status FROM BotVersions WHERE Status='Active')
+//       FROM BotDefinition WHERE Type='InternalCopilot'
+//     Every NGA / Agentforce agent is a BotDefinition with Type='InternalCopilot';
+//     an agent is ACTIVATED iff it has at least one BotVersion with Status='Active'
+//     (the child subquery returns ≥1 record).
+//
+// The Agent Access custom permset should grant access ONLY to activated agents,
+// so this classifier separates activated from inactive and hands the caller the
+// activated set to present for a multi-select.
+//
+// Usage:
+//   node classify-activated-agents.mjs <bot-definitions.json>
+//
+// Emits a single JSON object to stdout:
+//   { agents: [ { Id, DeveloperName, MasterLabel, active } ],
+//     activatedAgents: [ { Id, DeveloperName, MasterLabel } ],
+//     inactiveAgents:  [ { Id, DeveloperName, MasterLabel } ],
+//     verdict: "AGENTS-FOUND" | "NONE-ACTIVE" | "CANNOT-CONFIRM",
+//     reasons: [...] }
+// Exit is always 0 on parseable bodies; verdict carries the decision. Exit 2 on
+// missing argv.
+
+import { readFileSync } from 'node:fs';
+
+function readEnvelope(path) {
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false, reason: `empty file: ${path}` };
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object') return { ok: false, reason: `non-object JSON at ${path}` };
+    if (typeof data.status === 'number' && data.status !== 0) {
+      return { ok: false, reason: `sf data query at ${path} failed with status ${data.status}` };
+    }
+    const records = Array.isArray(data.result?.records) ? data.result.records : null;
+    if (!records) return { ok: false, reason: `missing result.records[] at ${path}` };
+    return { ok: true, records };
+  } catch (e) {
+    return { ok: false, reason: `unreadable/invalid JSON at ${path}: ${e?.message ?? e}` };
+  }
+}
+
+const [botPath] = process.argv.slice(2);
+if (!botPath) {
+  process.stderr.write('usage: node classify-activated-agents.mjs <bot-definitions.json>\n');
+  process.exit(2);
+}
+
+const bots = readEnvelope(botPath);
+if (!bots.ok) {
+  process.stdout.write(JSON.stringify({
+    agents: [], activatedAgents: [], inactiveAgents: [],
+    verdict: 'CANNOT-CONFIRM',
+    reasons: [bots.reason],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+// A child-relationship subquery surfaces as a nested { totalSize, records:[...] }
+// object, or null when there are no matching children.
+function activeVersionCount(r) {
+  const bv = r?.BotVersions;
+  if (!bv) return 0;
+  if (Array.isArray(bv.records)) return bv.records.length;
+  if (typeof bv.totalSize === 'number') return bv.totalSize;
+  return 0;
+}
+
+const agents = bots.records
+  .filter((r) => r && typeof r.Id === 'string')
+  .map((r) => ({
+    Id: r.Id,
+    DeveloperName: r.DeveloperName ?? null,
+    MasterLabel: r.MasterLabel ?? null,
+    active: activeVersionCount(r) > 0,
+  }));
+
+const activatedAgents = agents.filter((a) => a.active).map(({ active, ...rest }) => rest);
+const inactiveAgents = agents.filter((a) => !a.active).map(({ active, ...rest }) => rest);
+
+const reasons = [];
+let verdict;
+if (activatedAgents.length > 0) {
+  verdict = 'AGENTS-FOUND';
+  reasons.push(`Found ${activatedAgents.length} activated agent(s): ${activatedAgents.map((a) => a.MasterLabel ?? a.DeveloperName).join(', ')}.`);
+  if (inactiveAgents.length > 0) {
+    reasons.push(`Excluded ${inactiveAgents.length} agent(s) with no active version (not activated yet): ${inactiveAgents.map((a) => a.MasterLabel ?? a.DeveloperName).join(', ')}.`);
+  }
+  reasons.push('Present the activated agents for a multi-select — the Agent Access permset gets one SetupEntityAccess grant per chosen agent.');
+} else {
+  verdict = 'NONE-ACTIVE';
+  if (agents.length === 0) {
+    reasons.push('No InternalCopilot agents exist on this org — there is nothing for the Agent Access permset to grant. Create + activate an agent first.');
+  } else {
+    reasons.push(`${agents.length} InternalCopilot agent(s) exist but none has an active version — activate an agent before granting access.`);
+  }
+}
+
+process.stdout.write(JSON.stringify({
+  agents, activatedAgents, inactiveAgents, verdict, reasons,
+}, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-agent-runtime-access-assign/scripts/classify-agent-access-state.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// Deterministic idempotency classifier for the custom `Agent_Access` permission
+// set and its per-agent SetupEntityAccess grants.
+//
+// The Agent Access concern has two writes that must be idempotent:
+//   1. Create the `Agent_Access` PermissionSet (Name=Agent_Access,
+//      Label="Agent Access") — only if it does not already exist.
+//   2. For each CHOSEN activated agent, add a SetupEntityAccess row
+//      { ParentId: <Agent_Access permset Id>, SetupEntityId: <BotDefinition Id> }
+//      — only if a grant for that agent is not already present.
+//      (SetupEntityType is NOT sent in the POST body — it is not createable and
+//       is derived from the 0Xx key prefix; it IS filterable on the read.)
+//
+// Reads:
+//   1. `agent-access-permset.json` — `sf data query --json` capture of
+//        SELECT Id, Name, Label FROM PermissionSet WHERE Name='Agent_Access'
+//   2. `sea-existing.json` OR the literal sentinel `NO-PERMSET`:
+//        - permset present ⇒ pass the capture of
+//            SELECT SetupEntityId FROM SetupEntityAccess
+//            WHERE ParentId='<permsetId>' AND SetupEntityType='BotDefinition'
+//        - permset absent ⇒ pass `NO-PERMSET` (there is no parent to query yet).
+//   3. `chosenAgentIds-csv` — comma-separated BotDefinition Ids the user selected.
+//
+// Usage:
+//   node classify-agent-access-state.mjs <agent-access-permset.json> <sea-existing.json | NO-PERMSET> <chosenAgentIds-csv>
+//
+// Emits a single JSON object to stdout:
+//   { permsetExists, permsetId, chosenAgentIds, grantedAgentIds, missingAgentIds,
+//     needsCreate, needsGrants,
+//     verdict: "NEEDS-WORK" | "ALREADY-COMPLETE" | "CANNOT-CONFIRM",
+//     reasons: [...] }
+// Exit is always 0 on parseable bodies; verdict carries the decision. Exit 2 on
+// missing argv.
+
+import { readFileSync } from 'node:fs';
+
+function readEnvelope(path) {
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false, reason: `empty file: ${path}` };
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object') return { ok: false, reason: `non-object JSON at ${path}` };
+    if (typeof data.status === 'number' && data.status !== 0) {
+      return { ok: false, reason: `sf data query at ${path} failed with status ${data.status}` };
+    }
+    const records = Array.isArray(data.result?.records) ? data.result.records : null;
+    if (!records) return { ok: false, reason: `missing result.records[] at ${path}` };
+    return { ok: true, records };
+  } catch (e) {
+    return { ok: false, reason: `unreadable/invalid JSON at ${path}: ${e?.message ?? e}` };
+  }
+}
+
+const argv = process.argv.slice(2).filter((a) => a !== undefined && a !== '');
+if (argv.length < 3) {
+  process.stderr.write('usage: node classify-agent-access-state.mjs <agent-access-permset.json> <sea-existing.json | NO-PERMSET> <chosenAgentIds-csv>\n');
+  process.exit(2);
+}
+const [permsetPath, seaArg, chosenCsv] = argv;
+const chosenAgentIds = chosenCsv.split(',').map((s) => s.trim()).filter(Boolean);
+
+function cannotConfirm(reasons) {
+  process.stdout.write(JSON.stringify({
+    permsetExists: null, permsetId: null, chosenAgentIds,
+    grantedAgentIds: [], missingAgentIds: [],
+    needsCreate: null, needsGrants: null,
+    verdict: 'CANNOT-CONFIRM', reasons,
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+if (chosenAgentIds.length === 0) {
+  cannotConfirm(['no chosen agent Ids supplied — pass the comma-separated BotDefinition Ids the user selected.']);
+}
+
+const permset = readEnvelope(permsetPath);
+if (!permset.ok) cannotConfirm([permset.reason]);
+
+const permsetRow = permset.records.find((r) => r?.Name === 'Agent_Access') ?? null;
+const permsetExists = !!permsetRow;
+const permsetId = permsetExists ? (permsetRow.Id ?? null) : null;
+
+let grantedAgentIds = [];
+if (permsetExists) {
+  if (seaArg === 'NO-PERMSET') {
+    cannotConfirm(['Agent_Access permset exists but the SetupEntityAccess capture was passed as NO-PERMSET — query the existing grants and pass the real capture.']);
+  }
+  const sea = readEnvelope(seaArg);
+  if (!sea.ok) cannotConfirm([sea.reason]);
+  const grantedSet = new Set(sea.records.map((r) => r?.SetupEntityId).filter(Boolean));
+  grantedAgentIds = chosenAgentIds.filter((id) => grantedSet.has(id));
+}
+// When the permset does not exist, seaArg must be NO-PERMSET and nothing is granted.
+
+const missingAgentIds = chosenAgentIds.filter((id) => !grantedAgentIds.includes(id));
+const needsCreate = !permsetExists;
+const needsGrants = missingAgentIds.length > 0;
+
+const reasons = [];
+reasons.push(permsetExists
+  ? `Agent_Access permission set already exists (${permsetId}).`
+  : 'Agent_Access permission set does not exist yet — it will be created.');
+reasons.push(`Chosen agents: ${chosenAgentIds.length}; already granted: ${grantedAgentIds.length}; missing grants: ${missingAgentIds.length}.`);
+
+const verdict = (needsCreate || needsGrants) ? 'NEEDS-WORK' : 'ALREADY-COMPLETE';
+reasons.push(verdict === 'NEEDS-WORK'
+  ? 'Proceed to the confirm-to-write gate, then create the permset (if missing) and add one SetupEntityAccess grant per missing agent.'
+  : 'The Agent_Access permset exists and already grants every chosen agent — no SetupEntityAccess writes needed (still assign the permset to the target user(s) if not yet assigned).');
+
+process.stdout.write(JSON.stringify({
+  permsetExists, permsetId, chosenAgentIds, grantedAgentIds, missingAgentIds,
+  needsCreate, needsGrants, verdict, reasons,
+}, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-agent-runtime-access-assign/scripts/classify-assignment-state.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Deterministic idempotency classifier for the agent-runtime-access-assign flow.
+//
+// Reads the `sf data query --json` captures:
+//   - PermissionSetAssignment (permset ↔ user) for the target user + permset
+//   - PermissionSetLicenseAssign (PSL ↔ user) for the target user + PSL
+//     — ONLY when the selected permset actually has a backing license.
+//       Pass the sentinel `NO-PSL` in place of the PSLA path when the selected
+//       permset has no backing `LicenseId` (a standalone permset such as the
+//       custom `Agent_Access` set — no PSL query, no PSL POST).
+// and decides whether the assign write should be skipped for this user+permset.
+//
+// Rules (A9):
+//   - needsPsl AND both rows present ⇒ needsWrite=false (already fully assigned).
+//   - needsPsl AND either row missing ⇒ needsWrite=true (assign the missing
+//     piece; the workflow assigns PSL before permset regardless of which one is
+//     currently missing to preserve the write-order invariant).
+//   - !needsPsl (pslaPath === "NO-PSL"):
+//       * permsetAssigned ⇒ needsWrite=false (nothing to write).
+//       * !permsetAssigned ⇒ needsWrite=true (assign the permset only — skip the
+//         PSL POST).
+//     `licenseAssigned` is reported as null in this branch (not applicable).
+//   - Query envelope missing/failed ⇒ CANNOT-CONFIRM; surface it and stop.
+//
+// Usage:
+//   node classify-assignment-state.mjs <psa-existing.json> <psla-existing.json | NO-PSL>
+//
+// Emits a single JSON object to stdout:
+//   { permsetAssigned, licenseAssigned, needsWrite,
+//     verdict: "NEEDS-WRITE" | "ALREADY-ASSIGNED" | "CANNOT-CONFIRM",
+//     reasons: [...] }
+// Exit is always 0 on parseable bodies; verdict carries the decision.
+
+import { readFileSync } from 'node:fs';
+
+function readEnvelope(path) {
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false, reason: `empty file: ${path}` };
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object') return { ok: false, reason: `non-object JSON at ${path}` };
+    if (typeof data.status === 'number' && data.status !== 0) {
+      return { ok: false, reason: `sf data query at ${path} failed with status ${data.status}` };
+    }
+    const records = Array.isArray(data.result?.records) ? data.result.records : null;
+    if (!records) return { ok: false, reason: `missing result.records[] at ${path}` };
+    return { ok: true, records };
+  } catch (e) {
+    return { ok: false, reason: `unreadable/invalid JSON at ${path}: ${e?.message ?? e}` };
+  }
+}
+
+const argv = process.argv.slice(2).filter((a) => !!a);
+if (argv.length < 2) {
+  process.stderr.write('usage: node classify-assignment-state.mjs <psa-existing.json> <psla-existing.json | NO-PSL>\n');
+  process.exit(2);
+}
+const [psaPath, pslaArg] = argv;
+const needsPsl = pslaArg !== 'NO-PSL';
+
+const psa = readEnvelope(psaPath);
+const psla = needsPsl ? readEnvelope(pslaArg) : { ok: true, records: [], skipped: true };
+
+const readErrors = [psa, psla].filter((r) => !r.ok).map((r) => r.reason);
+if (readErrors.length) {
+  process.stdout.write(JSON.stringify({
+    permsetAssigned: null, licenseAssigned: null, needsWrite: null,
+    verdict: 'CANNOT-CONFIRM',
+    reasons: readErrors,
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+const permsetAssigned = psa.records.length > 0;
+const licenseAssigned = needsPsl ? psla.records.length > 0 : null;
+const needsWrite = needsPsl
+  ? !(permsetAssigned && licenseAssigned)
+  : !permsetAssigned;
+
+const verdict = needsWrite ? 'NEEDS-WRITE' : 'ALREADY-ASSIGNED';
+const reasons = [
+  `PermissionSetAssignment: ${permsetAssigned ? 'present' : 'missing'} (${psa.records.length} row${psa.records.length === 1 ? '' : 's'}).`,
+  needsPsl
+    ? `PermissionSetLicenseAssign: ${licenseAssigned ? 'present' : 'missing'} (${psla.records.length} row${psla.records.length === 1 ? '' : 's'}).`
+    : 'PermissionSetLicenseAssign: not applicable — the selected permission set has no backing LicenseId (standalone-permset flow; PSL SOQL + POST are skipped).',
+];
+reasons.push(
+  needsWrite
+    ? (needsPsl
+      ? 'At least one assignment is missing — proceed to the confirm-to-write gate, then assign (PSL first, permset second).'
+      : 'Permission set assignment is missing — proceed to the confirm-to-write gate, then assign the permset ONLY (skip the PSL POST).')
+    : (needsPsl
+      ? 'Both the permission set and its backing license are already assigned to this user — skip the write, go straight to verify.'
+      : 'The permission set is already assigned to this user (no backing license required) — skip the write, go straight to verify.')
+);
+
+process.stdout.write(JSON.stringify({
+  permsetAssigned, licenseAssigned, needsWrite, verdict, reasons,
+}, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-agent-runtime-access-assign/scripts/classify-platform-permset-availability.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Deterministic availability classifier for the platform feature permsets an
+// ITSM agent's actions need at RUNTIME (so a user can exercise the agent).
+//
+// Reads ONE input:
+//   - PermissionSet query capture (from `sf data query --json`) filtered to the
+//     six known platform feature permset `Name` values across three features,
+//     each with a "use" tier (lighter, user/agent-facing) and an "admin" tier:
+//
+//       Feature            use tier                          admin tier
+//       -----------------  --------------------------------  --------------------------------
+//       Prompt Templates   EinsteinGPTPromptTemplateUser     EinsteinGPTPromptTemplateManager
+//       Data Cloud         GenieUserEnhancedSecurity         GenieAdmin
+//       Unified Catalog    UnifiedCatalogCommunityUser       UnifiedCatalogAdmin
+//
+// No single org is guaranteed to have all three features provisioned, so the
+// classifier reports which tiers are actually PRESENT (a row exists) and which
+// are ABSENT (feature not provisioned on this org — skip it, do not fail).
+//
+// `needsPsl` is derived PER ROW from `LicenseId !== null` — the write path POSTs
+// a PermissionSetLicenseAssign using the row's own `LicenseId`; PSL names are
+// never hard-coded. `displayLabel` prefers the org's actual `Label`, falling
+// back to a canonical label when the row is absent.
+//
+// Usage:
+//   node classify-platform-permset-availability.mjs <permsets.json>
+//
+// Emits a single JSON object to stdout:
+//   { features: [ { feature, tiers: { use, admin }, anyPresent } ],
+//     provisionedFeatures: [...], absentFeatures: [...],
+//     verdict: "ASSIGNABLE" | "NONE-PROVISIONED" | "CANNOT-CONFIRM",
+//     reasons: [...] }
+// where each tier is { tier, name, displayLabel, present, Id, LicenseId, needsPsl }.
+// Exit is always 0 on parseable bodies; verdict carries the decision. Exit 2 on
+// missing argv.
+
+import { readFileSync } from 'node:fs';
+
+// The fixed catalog. `label` is the canonical fallback; the org's own Label wins
+// when the row is present (e.g. GenieAdmin ships as "Data Cloud Architect" on
+// some orgs, "Data Cloud Admin" on others — render whatever the org says).
+const CATALOG = [
+  {
+    feature: 'Prompt Templates',
+    use: { name: 'EinsteinGPTPromptTemplateUser', label: 'Prompt Template User' },
+    admin: { name: 'EinsteinGPTPromptTemplateManager', label: 'Prompt Template Manager' },
+  },
+  {
+    feature: 'Data Cloud',
+    use: { name: 'GenieUserEnhancedSecurity', label: 'Data Cloud User' },
+    admin: { name: 'GenieAdmin', label: 'Data Cloud Admin' },
+  },
+  {
+    feature: 'Unified Catalog',
+    use: { name: 'UnifiedCatalogCommunityUser', label: 'Unified Catalog Community User' },
+    admin: { name: 'UnifiedCatalogAdmin', label: 'Unified Catalog Admin' },
+  },
+];
+
+function readEnvelope(path) {
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false, reason: `empty file: ${path}` };
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object') return { ok: false, reason: `non-object JSON at ${path}` };
+    if (typeof data.status === 'number' && data.status !== 0) {
+      return { ok: false, reason: `sf data query at ${path} failed with status ${data.status}` };
+    }
+    const records = Array.isArray(data.result?.records) ? data.result.records : null;
+    if (!records) return { ok: false, reason: `missing result.records[] at ${path}` };
+    return { ok: true, records };
+  } catch (e) {
+    return { ok: false, reason: `unreadable/invalid JSON at ${path}: ${e?.message ?? e}` };
+  }
+}
+
+const [psPath] = process.argv.slice(2);
+if (!psPath) {
+  process.stderr.write('usage: node classify-platform-permset-availability.mjs <permsets.json>\n');
+  process.exit(2);
+}
+
+const ps = readEnvelope(psPath);
+if (!ps.ok) {
+  process.stdout.write(JSON.stringify({
+    features: [],
+    provisionedFeatures: [],
+    absentFeatures: CATALOG.map((f) => f.feature),
+    verdict: 'CANNOT-CONFIRM',
+    reasons: [ps.reason],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+// Index the query rows by PermissionSet.Name for O(1) lookup.
+const byName = new Map();
+for (const r of ps.records) {
+  if (r && typeof r.Name === 'string') byName.set(r.Name, r);
+}
+
+function tierOf(tier, spec) {
+  const row = byName.get(spec.name);
+  const present = !!row;
+  return {
+    tier,
+    name: spec.name,
+    displayLabel: (present && typeof row.Label === 'string' && row.Label) ? row.Label : spec.label,
+    present,
+    Id: present ? (row.Id ?? null) : null,
+    LicenseId: present ? (row.LicenseId ?? null) : null,
+    needsPsl: present ? ((row.LicenseId ?? null) !== null) : false,
+  };
+}
+
+const features = CATALOG.map((f) => {
+  const use = tierOf('use', f.use);
+  const admin = tierOf('admin', f.admin);
+  return { feature: f.feature, tiers: { use, admin }, anyPresent: use.present || admin.present };
+});
+
+const provisionedFeatures = features.filter((f) => f.anyPresent).map((f) => f.feature);
+const absentFeatures = features.filter((f) => !f.anyPresent).map((f) => f.feature);
+
+const reasons = [];
+let verdict;
+if (provisionedFeatures.length === 0) {
+  verdict = 'NONE-PROVISIONED';
+  reasons.push('None of the three platform features (Prompt Templates, Data Cloud, Unified Catalog) is provisioned on this org — no runtime action-execution permset can be assigned.');
+  reasons.push('This does NOT block the Agent Access concern; continue there so users can still open the activated agents.');
+} else {
+  verdict = 'ASSIGNABLE';
+  reasons.push(`Provisioned feature(s) with an assignable tier: ${provisionedFeatures.join(', ')}.`);
+  if (absentFeatures.length > 0) {
+    reasons.push(`Not provisioned on this org (report as unavailable, do not assign): ${absentFeatures.join(', ')}.`);
+  }
+  reasons.push('For EACH provisioned feature, ask the user which tier to assign (use/agent vs admin) — do not auto-select a tier.');
+  const standalone = [];
+  for (const f of features) {
+    for (const t of ['use', 'admin']) {
+      const row = f.tiers[t];
+      if (row.present && !row.needsPsl) standalone.push(row.name);
+    }
+  }
+  if (standalone.length > 0) {
+    reasons.push(`Standalone tier(s) with no backing LicenseId (assign skips PSL SOQL/POST if selected): ${standalone.join(', ')}.`);
+  }
+}
+
+process.stdout.write(JSON.stringify({
+  features,
+  provisionedFeatures,
+  absentFeatures,
+  verdict,
+  reasons,
+}, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-agent-runtime-access-assign/scripts/gate-unified-catalog-tiers.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Per-target-user eligibility gate for the Unified Catalog feature tiers. The
+// Unified Catalog PSLs are license-SHAPE gated (not seat-gated): the Community
+// User tier can be held only by a Unified Employee-licensed user, and the Admin
+// tier is meaningful only for a System Administrator. Offering a tier the user's
+// license/profile can never hold produces a hard license-shape failure at write
+// time, so this gate decides which UC tiers to OFFER for a given user — or to omit
+// Unified Catalog for that user entirely. A pre-write eligibility gate, evaluated
+// per target user; it never writes.
+//
+// Inputs (argv):
+//   1. availability.json — the classify-platform-permset-availability.mjs output
+//      capture (carries the Unified Catalog tiers with present/Id/LicenseId/needsPsl).
+//   2. user.json         — a `sf data query --json` capture of the ONE target user,
+//      selecting Profile.Name and Profile.UserLicense.Name.
+//
+// Output (stdout JSON):
+//   { feature:"Unified Catalog", provisioned,
+//     user:{ profile, license, unifiedEmployee, sysAdmin },
+//     offer:[ <tier objects from the availability classifier> ], omit, note }
+//   offer[] is the subset of PRESENT UC tiers this user is eligible for:
+//     - "use"   (UnifiedCatalogCommunityUser) → only when the user is Unified Employee
+//     - "admin" (UnifiedCatalogAdmin)         → only when the user is System Administrator
+//   omit=true (offer empty) ⇒ do NOT present Unified Catalog for this user; report it
+//   "not applicable for this user's license/profile — skipped" (never a failed write).
+//   Fails CLOSED: an unreadable user capture yields omit=true (better to skip than to
+//   offer a tier that will fail). Exit 0 on parseable bodies; exit 2 on missing argv.
+
+import { readFileSync } from 'node:fs';
+
+// The Unified Employee cohort (Community User tier) and the System Administrator
+// profile (Admin tier) — the only two cohorts whose license/profile shape can hold
+// a Unified Catalog tier.
+const UNIFIED_RE = /unified\s*employee/i;
+const SYSADMIN_RE = /system\s*administrator/i;
+
+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}` };
+  }
+}
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+
+const [availPath, userPath] = process.argv.slice(2);
+if (!availPath || !userPath) {
+  process.stderr.write('usage: node gate-unified-catalog-tiers.mjs <availability.json> <user.json>\n');
+  process.exit(2);
+}
+
+const avail = readJson(availPath);
+const userEnv = readJson(userPath);
+
+// Locate the Unified Catalog feature block emitted by the availability classifier.
+const ucFeature = avail.ok && Array.isArray(avail.data?.features)
+  ? avail.data.features.find((f) => f.feature === 'Unified Catalog')
+  : null;
+const useTier = ucFeature?.tiers?.use ?? null;
+const adminTier = ucFeature?.tiers?.admin ?? null;
+const provisioned = !!(useTier?.present || adminTier?.present);
+
+// The one target user's profile + license (result.records[0]).
+const rec = userEnv.ok ? (userEnv.data?.result?.records?.[0] ?? null) : null;
+const profile = `${rec?.Profile?.Name ?? ''}`;
+const license = `${rec?.Profile?.UserLicense?.Name ?? ''}`;
+const unifiedEmployee = UNIFIED_RE.test(license) || UNIFIED_RE.test(profile);
+const sysAdmin = SYSADMIN_RE.test(profile);
+
+const offer = [];
+if (useTier?.present && unifiedEmployee) offer.push(useTier);
+if (adminTier?.present && sysAdmin) offer.push(adminTier);
+
+const omit = offer.length === 0;
+let note;
+if (!avail.ok) {
+  note = `availability capture unreadable (${avail.reason}) — cannot gate Unified Catalog; omit for this user.`;
+} else if (!provisioned) {
+  note = 'Unified Catalog is not provisioned on this org — skip it (already handled by the availability classifier).';
+} else if (!userEnv.ok) {
+  note = `target-user capture unreadable (${userEnv.reason}) — cannot confirm the user's cohort; omit Unified Catalog for this user.`;
+} else if (omit) {
+  note = `This user (license "${license || '?'}", profile "${profile || '?'}") is neither a Unified Employee (Community User tier) nor a System Administrator (Admin tier) — omit Unified Catalog for this user; report "not applicable for this user's license/profile — skipped".`;
+} else {
+  note = `Offer the ${offer.map((t) => t.tier).join(' + ')} tier(s) for Unified Catalog (unifiedEmployee=${unifiedEmployee}, sysAdmin=${sysAdmin}).`;
+}
+
+emit({
+  feature: 'Unified Catalog',
+  provisioned,
+  user: { profile, license, unifiedEmployee, sysAdmin },
+  offer,
+  omit,
+  note,
+});

package/skills/service-itsm-agentic-setup-agent-runtime-access-assign/scripts/rank-candidate-users.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Ranks REAL, human candidate users to offer as selectable options behind the
+// Phase-2 AskUserQuestion when the caller did not name a target user. This is a
+// presentation aid, never a gating decision — it keeps the offered list
+// deterministic (no editorializing down to one name) and audience-appropriate.
+//
+// Inputs (argv):
+//   1. users.json     — capture of `sf data query --json` selecting active users
+//                        with Id, Name, Username, Profile.Name, Profile.UserLicense.Name.
+//   2. audience       — 'fulfiller' | 'employee' | 'any' (anything else ⇒ 'any').
+//                       A Fulfiller agent is run by IT staff on a STANDARD license;
+//                       an Employee agent by end employees on a UNIFIED EMPLOYEE
+//                       license — so the matching cohort is surfaced first.
+//   3. runningUserId  — optional; the "Me" user, excluded here (offered separately
+//                       as the recommended option).
+//
+// Output (stdout JSON):
+//   { candidates: [ { Id, Name, Username, profile, cohort } ], audience, total, note }
+//   at most 5 candidates; service/integration/bot/agent accounts removed. Exit is
+//   always 0 on a parseable body (empty candidates ⇒ offer "Me" + free-text only);
+//   exit 2 only on missing argv.
+
+import { readFileSync } from 'node:fs';
+
+// Non-human / service accounts are never good runtime-access targets. Matched on
+// profile name, license name, username, OR display name so a mislabeled record
+// on any one field is still filtered.
+const SERVICE_RE = /integration|automated process|einstein agent|analytics cloud|salesforceiq|\binsights\b|chatter (free|external)|guest|portal|sites|\bbot\b|botuser|digitalagent/i;
+
+// The Unified Employee cohort — the human tier an Employee agent's users belong to.
+// It is defined by the Unified Employee USER LICENSE, which is the authoritative
+// signal; the profile name is only a defensive fallback (a custom profile carrying
+// the license must still rank as Unified Employee).
+const UNIFIED_RE = /unified\s*employee/i;
+
+function readEnvelope(path) {
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false, reason: `empty file: ${path}` };
+    const data = JSON.parse(text);
+    if (data && typeof data.status === 'number' && data.status !== 0) {
+      return { ok: false, reason: `sf data query at ${path} failed with status ${data.status}` };
+    }
+    const records = Array.isArray(data?.result?.records) ? data.result.records : null;
+    if (!records) return { ok: false, reason: `missing result.records[] at ${path}` };
+    return { ok: true, records };
+  } catch (e) {
+    return { ok: false, reason: `unreadable/invalid JSON at ${path}: ${e?.message ?? e}` };
+  }
+}
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+
+const [usersPath, audienceArg, runningUserId] = process.argv.slice(2);
+if (!usersPath) {
+  process.stderr.write('usage: node rank-candidate-users.mjs <users.json> [fulfiller|employee|any] [runningUserId]\n');
+  process.exit(2);
+}
+const audience = (audienceArg === 'fulfiller' || audienceArg === 'employee') ? audienceArg : 'any';
+
+const env = readEnvelope(usersPath);
+if (!env.ok) {
+  emit({ candidates: [], audience, total: 0, note: `${env.reason} — offer "Me" plus free-text entry only.` });
+  process.exit(0);
+}
+
+const profileName = (r) => `${r?.Profile?.Name ?? ''}`;
+const licenseName = (r) => `${r?.Profile?.UserLicense?.Name ?? ''}`;
+const isService = (r) =>
+  SERVICE_RE.test(profileName(r)) || SERVICE_RE.test(licenseName(r)) ||
+  SERVICE_RE.test(`${r?.Username ?? ''}`) || SERVICE_RE.test(`${r?.Name ?? ''}`);
+const cohortOf = (r) =>
+  (UNIFIED_RE.test(licenseName(r)) || UNIFIED_RE.test(profileName(r)) ? 'unified-employee' : 'standard');
+
+const humans = env.records
+  .filter((r) => r && typeof r.Id === 'string')
+  .filter((r) => r.Id !== runningUserId)
+  .filter((r) => !isService(r))
+  .map((r) => ({ Id: r.Id, Name: r.Name ?? r.Username, Username: r.Username, profile: profileName(r), cohort: cohortOf(r) }));
+
+// Rank the audience-matching cohort first, preserving input order within a cohort
+// (the query already orders by most-recent login).
+const prefer = audience === 'employee' ? 'unified-employee' : audience === 'fulfiller' ? 'standard' : null;
+const ranked = prefer
+  ? [...humans.filter((u) => u.cohort === prefer), ...humans.filter((u) => u.cohort !== prefer)]
+  : humans;
+
+const candidates = ranked.slice(0, 5);
+const note = candidates.length === 0
+  ? 'No non-service human users found besides the running user — offer "Me" plus free-text entry only.'
+  : `Offering ${candidates.length} candidate(s)${prefer ? `, ${prefer} cohort first (audience: ${audience})` : ''}.`;
+
+emit({ candidates, audience, total: humans.length, note });