@salesforce/afv-skills 1.47.0 → 1.49.0

package/skills/service-omni-supervisor-surface-deploy/scripts/deploy-and-report.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+# deploy-and-report.sh - populate the Omni Supervisor action + tab surface on an existing OmniSupervisorConfig by inserting OmniSupervisorConfigAction / OmniSupervisorConfigTab rows via the Data API. Idempotent (inserts only the missing types). Args, env, exit codes: SKILL.md; type vocabulary + reference-only exclusions: references/api-notes.md.
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo '{"error":"Usage: bash deploy-and-report.sh <org-alias> [config_developer_name]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+CONFIG_DN="${2:-}"
+
+# Reference-free standard types (safe to insert as bare companion rows).
+DEFAULT_ACTIONS="AllAgents.ChangeQueues,AllAgents.ChangeSkills,AllAgents.ChangeGroups,AllAgents.AssignLearning,QueuesBacklog.ManageQueues"
+DEFAULT_TABS="Wallboard,Agents,QueuesBacklog,AssignedWork,SkillsBacklog"
+SAFE_ACTIONS="AllAgents.ChangeQueues AllAgents.ChangeSkills AllAgents.ChangeGroups AllAgents.AssignLearning QueuesBacklog.ManageQueues"
+SAFE_TABS="Wallboard Agents QueuesBacklog AssignedWork SkillsBacklog Reports Alerts"
+
+ACTIONS_CSV="${SUPERVISOR_ACTIONS:-$DEFAULT_ACTIONS}"
+TABS_CSV="${SUPERVISOR_TABS:-$DEFAULT_TABS}"
+
+if [ -n "$CONFIG_DN" ] && ! [[ "$CONFIG_DN" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
+  echo "{\"error\":\"Invalid config_developer_name '$CONFIG_DN'. Must start with a letter and contain only letters, digits, underscores (max 80).\"}" >&2
+  exit 1
+fi
+
+if ! sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
+  echo "{\"error\":\"Org alias '$ORG' is not authenticated. Run: sf org login web -a $ORG -r <my-domain-url>\"}" >&2
+  exit 1
+fi
+
+emit_blocked() {
+  local msg="$1"; local target_skill="${2:-}"
+  local manual_actions='[]'
+  if [ -n "$target_skill" ]; then
+    manual_actions=$(jq -n --arg ts "$target_skill" '[{id:"MISSING_PREREQ",title:"Run prerequisite skill",target_skill:$ts}]')
+  fi
+  EMITTED=1
+  jq -n --arg msg "$msg" --arg cdn "${CONFIG_DN:-}" --argjson ma "$manual_actions" \
+    '{skill:"service-omni-supervisor-surface-deploy",status:"blocked",
+      config:{developer_name:(if $cdn=="" then null else $cdn end),id:null},
+      actions:{requested:[],created:[],reused:[],count:0},
+      tabs:{requested:[],created:[],reused:[],count:0},
+      manual_actions:$ma,blocking_issue:$msg}'
+  exit 1
+}
+
+# Fail-safe: under `set -euo pipefail` an unguarded jq/sf failure could otherwise kill the
+# script with empty stdout. Emit a structured blocked JSON on any exit before a real result so
+# the coordinator never parses empty output. EMITTED flips to 1 before each intentional emit.
+EMITTED=0
+on_exit() {
+  if [ "$EMITTED" != "1" ]; then
+    jq -n --arg cdn "${CONFIG_DN:-}" \
+      '{skill:"service-omni-supervisor-surface-deploy",status:"blocked",
+        config:{developer_name:(if $cdn=="" then null else $cdn end),id:null},
+        actions:{requested:[],created:[],reused:[],count:0},
+        tabs:{requested:[],created:[],reused:[],count:0},
+        manual_actions:[],
+        blocking_issue:"Supervisor surface deploy aborted before completing (unexpected error; see stderr). Re-run."}'
+  fi
+}
+trap on_exit EXIT
+
+# Split a CSV into a space list, trimming blanks.
+csv_to_items() { printf '%s' "$1" | tr ',' '\n' | sed 's/^ *//;s/ *$//' | grep -v '^$' || true; }
+
+# Reject types that need an external reference (custom action, FlexiPage, AWS, AI) - a bare
+# companion row cannot point at them (only OmniSupervisorConfigId/Type/DisplayOrder are createable).
+requires_reference() {
+  case "$1" in
+    *CustomAction|*AWSDashboard|FlexipageType|AIAgents|AgentforceSDR) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+in_list() { local needle="$1"; shift; local x; for x in $*; do [ "$x" = "$needle" ] && return 0; done; return 1; }
+
+# ---- validate requested types up front (reject before any write) ----
+REQ_ACTIONS=(); while IFS= read -r a; do REQ_ACTIONS+=("$a"); done < <(csv_to_items "$ACTIONS_CSV")
+REQ_TABS=();    while IFS= read -r t; do REQ_TABS+=("$t");    done < <(csv_to_items "$TABS_CSV")
+
+for a in "${REQ_ACTIONS[@]:-}"; do
+  [ -z "$a" ] && continue
+  if requires_reference "$a"; then
+    emit_blocked "Action type '$a' needs an external reference (custom action / AWS dashboard) that a bare OmniSupervisorConfigAction row cannot carry; configure it in Setup. Supported reference-free types: $SAFE_ACTIONS."
+  fi
+  in_list "$a" $SAFE_ACTIONS || emit_blocked "Unsupported action type '$a'. Supported reference-free types: $SAFE_ACTIONS."
+done
+for t in "${REQ_TABS[@]:-}"; do
+  [ -z "$t" ] && continue
+  if requires_reference "$t"; then
+    emit_blocked "Tab type '$t' needs an external reference (FlexiPage / AI agent) that a bare OmniSupervisorConfigTab row cannot carry; configure it in Setup. Supported reference-free types: $SAFE_TABS."
+  fi
+  in_list "$t" $SAFE_TABS || emit_blocked "Unsupported tab type '$t'. Supported reference-free types: $SAFE_TABS."
+done
+
+# Step 1 - safe_to_write guard
+ORG_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" --json 2>/dev/null) \
+  || emit_blocked "Failed to query Organization for the safe_to_write guard."
+IS_SANDBOX=$(echo "$ORG_JSON" | jq -r '.result.records[0].IsSandbox')
+TRIAL_EXP=$(echo "$ORG_JSON"  | jq -r '.result.records[0].TrialExpirationDate // "null"')
+ORG_TYPE=$(echo "$ORG_JSON"   | jq -r '.result.records[0].OrganizationType')
+SAFE_TO_WRITE=false
+if [ "$IS_SANDBOX" = "true" ] || [ "$TRIAL_EXP" != "null" ] \
+   || [ "$ORG_TYPE" = "Developer Edition" ] || [ "$ORG_TYPE" = "Base Edition" ]; then
+  SAFE_TO_WRITE=true
+fi
+[ "$SAFE_TO_WRITE" = "true" ] || emit_blocked "Refusing to write the supervisor surface to a real production customer org (IsSandbox=$IS_SANDBOX, TrialExpirationDate=$TRIAL_EXP, OrganizationType=$ORG_TYPE). Target a sandbox, trial CDO, or Developer Edition org."
+
+# Step 2 - resolve the OmniSupervisorConfig (by DeveloperName, else the org's sole config)
+if [ -n "$CONFIG_DN" ]; then
+  CFG_JSON=$(sf data query --target-org "$ORG" --json \
+    --query "SELECT Id, DeveloperName FROM OmniSupervisorConfig WHERE DeveloperName='$CONFIG_DN'" 2>/dev/null || echo '{}')
+else
+  CFG_JSON=$(sf data query --target-org "$ORG" --json \
+    --query "SELECT Id, DeveloperName FROM OmniSupervisorConfig ORDER BY CreatedDate LIMIT 2" 2>/dev/null || echo '{}')
+fi
+CFG_COUNT=$(echo "$CFG_JSON" | jq -r '.result.records | length' 2>/dev/null || echo 0)
+if [ "${CFG_COUNT:-0}" -eq 0 ]; then
+  emit_blocked "No OmniSupervisorConfig found${CONFIG_DN:+ named '$CONFIG_DN'} on this org. Deploy it first." "service-omni-supervisor-config-deploy"
+fi
+if [ -z "$CONFIG_DN" ] && [ "$CFG_COUNT" -gt 1 ]; then
+  NAMES=$(echo "$CFG_JSON" | jq -r '[.result.records[].DeveloperName] | join(", ")')
+  emit_blocked "Multiple OmniSupervisorConfigs exist ($NAMES); pass one as the config_developer_name argument."
+fi
+CONFIG_ID=$(echo "$CFG_JSON" | jq -r '.result.records[0].Id')
+CONFIG_DN=$(echo "$CFG_JSON" | jq -r '.result.records[0].DeveloperName')
+
+# Step 3 - read existing surface rows (idempotency baseline). A failed/inconclusive read must
+# NOT fall through to an empty baseline, or we would re-insert rows that already exist. Require a
+# definitive .result.records array; otherwise block.
+EX_ACTIONS_JSON=$(sf data query --target-org "$ORG" --json \
+  --query "SELECT OmniSupervisorActionType, DisplayOrder FROM OmniSupervisorConfigAction WHERE OmniSupervisorConfigId='$CONFIG_ID'" 2>/dev/null) \
+  || emit_blocked "Failed to read existing OmniSupervisorConfigAction rows (inconclusive; refusing to insert to avoid duplicates)."
+echo "$EX_ACTIONS_JSON" | jq -e '.result.records' >/dev/null 2>&1 \
+  || emit_blocked "OmniSupervisorConfigAction baseline read returned no records array (inconclusive; refusing to insert to avoid duplicates)."
+EX_TABS_JSON=$(sf data query --target-org "$ORG" --json \
+  --query "SELECT OmniSupervisorTabType, DisplayOrder FROM OmniSupervisorConfigTab WHERE OmniSupervisorConfigId='$CONFIG_ID'" 2>/dev/null) \
+  || emit_blocked "Failed to read existing OmniSupervisorConfigTab rows (inconclusive; refusing to insert to avoid duplicates)."
+echo "$EX_TABS_JSON" | jq -e '.result.records' >/dev/null 2>&1 \
+  || emit_blocked "OmniSupervisorConfigTab baseline read returned no records array (inconclusive; refusing to insert to avoid duplicates)."
+EXIST_ACTIONS=$(echo "$EX_ACTIONS_JSON" | jq -r '[.result.records[]?.OmniSupervisorActionType] | @json' 2>/dev/null || echo '[]')
+EXIST_TABS=$(echo "$EX_TABS_JSON"       | jq -r '[.result.records[]?.OmniSupervisorTabType]  | @json' 2>/dev/null || echo '[]')
+MAX_ACTION_ORDER=$(echo "$EX_ACTIONS_JSON" | jq -r '[.result.records[]?.DisplayOrder // 0] | max // 0' 2>/dev/null || echo 0)
+MAX_TAB_ORDER=$(echo "$EX_TABS_JSON"       | jq -r '[.result.records[]?.DisplayOrder // 0] | max // 0' 2>/dev/null || echo 0)
+
+has_existing() { echo "$1" | jq -e --arg v "$2" 'index($v) != null' >/dev/null 2>&1; }
+
+# PLAN_ONLY - report intent, no write.
+if [ "${PLAN_ONLY:-}" = "1" ]; then
+  EMITTED=1
+  jq -n --arg cdn "$CONFIG_DN" --arg cid "$CONFIG_ID" \
+        --argjson ra "$(printf '%s\n' "${REQ_ACTIONS[@]:-}" | jq -R . | jq -s 'map(select(length>0))')" \
+        --argjson rt "$(printf '%s\n' "${REQ_TABS[@]:-}"    | jq -R . | jq -s 'map(select(length>0))')" \
+        --argjson ea "$EXIST_ACTIONS" --argjson et "$EXIST_TABS" \
+    '{skill:"service-omni-supervisor-surface-deploy",status:"action_needed",plan_mode:true,
+      config:{developer_name:$cdn,id:$cid},
+      plan_detail:("Would ensure \($ra|length) action type(s) and \($rt|length) tab type(s) on OmniSupervisorConfig \($cdn); existing actions=\($ea|length), tabs=\($et|length). Inserts only the missing types."),
+      actions:{requested:$ra,created:[],reused:$ea,count:($ea|length)},
+      tabs:{requested:$rt,created:[],reused:$et,count:($et|length)},
+      manual_actions:[],blocking_issue:null}'
+  exit 0
+fi
+
+# Step 4 - insert missing action rows
+CREATED_ACTIONS="[]"; REUSED_ACTIONS="[]"; ORDER=$MAX_ACTION_ORDER
+for a in "${REQ_ACTIONS[@]:-}"; do
+  [ -z "$a" ] && continue
+  if has_existing "$EXIST_ACTIONS" "$a"; then
+    REUSED_ACTIONS=$(echo "$REUSED_ACTIONS" | jq --arg v "$a" '. + [$v]')
+    continue
+  fi
+  ORDER=$((ORDER + 1))
+  RES=$(sf data create record --target-org "$ORG" --sobject OmniSupervisorConfigAction \
+    --values "OmniSupervisorConfigId=$CONFIG_ID OmniSupervisorActionType=$a DisplayOrder=$ORDER" --json 2>/dev/null || true)
+  OKID=$(echo "$RES" | jq -r '.result.id // ""' 2>/dev/null)
+  if [ -z "$OKID" ] || [ "$OKID" = "null" ]; then
+    MSG=$(echo "$RES" | jq -r '.message // "unknown insert error"' 2>/dev/null | tr -d '\n' | head -c 300)
+    emit_blocked "Failed to insert OmniSupervisorConfigAction '$a': $MSG"
+  fi
+  CREATED_ACTIONS=$(echo "$CREATED_ACTIONS" | jq --arg v "$a" '. + [$v]')
+done
+
+# Step 5 - insert missing tab rows
+CREATED_TABS="[]"; REUSED_TABS="[]"; ORDER=$MAX_TAB_ORDER
+for t in "${REQ_TABS[@]:-}"; do
+  [ -z "$t" ] && continue
+  if has_existing "$EXIST_TABS" "$t"; then
+    REUSED_TABS=$(echo "$REUSED_TABS" | jq --arg v "$t" '. + [$v]')
+    continue
+  fi
+  ORDER=$((ORDER + 1))
+  RES=$(sf data create record --target-org "$ORG" --sobject OmniSupervisorConfigTab \
+    --values "OmniSupervisorConfigId=$CONFIG_ID OmniSupervisorTabType=$t DisplayOrder=$ORDER" --json 2>/dev/null || true)
+  OKID=$(echo "$RES" | jq -r '.result.id // ""' 2>/dev/null)
+  if [ -z "$OKID" ] || [ "$OKID" = "null" ]; then
+    MSG=$(echo "$RES" | jq -r '.message // "unknown insert error"' 2>/dev/null | tr -d '\n' | head -c 300)
+    emit_blocked "Failed to insert OmniSupervisorConfigTab '$t': $MSG"
+  fi
+  CREATED_TABS=$(echo "$CREATED_TABS" | jq --arg v "$t" '. + [$v]')
+done
+
+CREATED_TOTAL=$(( $(echo "$CREATED_ACTIONS" | jq 'length') + $(echo "$CREATED_TABS" | jq 'length') ))
+STATUS="reused"; [ "$CREATED_TOTAL" -gt 0 ] && STATUS="created"
+
+EMITTED=1
+jq -n --arg status "$STATUS" --arg cdn "$CONFIG_DN" --arg cid "$CONFIG_ID" \
+  --argjson ca "$CREATED_ACTIONS" --argjson rua "$REUSED_ACTIONS" \
+  --argjson ct "$CREATED_TABS"    --argjson rut "$REUSED_TABS" \
+  '{skill:"service-omni-supervisor-surface-deploy",status:$status,
+    config:{developer_name:$cdn,id:$cid},
+    actions:{requested:(($ca+$rua)|sort),created:$ca,reused:$rua,count:(($ca+$rua)|length)},
+    tabs:{requested:(($ct+$rut)|sort),created:$ct,reused:$rut,count:(($ct+$rut)|length)},
+    manual_actions:[],blocking_issue:null}'

package/skills/service-omni-supervisor-surface-deploy/scripts/tests/_bootstrap.py

@@ -0,0 +1,95 @@
+"""Shared paths + fake-`sf` harness for the supervisor-surface-deploy contract suite.
+
+The fake serves the org guard query, config resolution, existing-surface reads, and record
+inserts from env tunables. Org-free and network-free.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SKILL_DIR = "service-omni-supervisor-surface-deploy"
+SCRIPT = f"{SKILL_DIR}/scripts/deploy-and-report.sh"
+
+# Tunables (env):
+#   FAKE_SANDBOX       = true|false           (safe_to_write guard; default true)
+#   FAKE_CFG_COUNT     = 0|1|2                (OmniSupervisorConfig rows; default 1)
+#   FAKE_EXIST_ACTIONS = JSON array of types  (existing OmniSupervisorConfigAction; default [])
+#   FAKE_EXIST_TABS    = JSON array of types  (existing OmniSupervisorConfigTab;    default [])
+#   FAKE_CREATE_OK     = true|false           (record insert result; default true)
+_FAKE_SF = r"""#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+SANDBOX="${FAKE_SANDBOX:-true}"
+CFG_COUNT="${FAKE_CFG_COUNT:-1}"
+EXIST_ACTIONS="${FAKE_EXIST_ACTIONS:-[]}"
+EXIST_TABS="${FAKE_EXIST_TABS:-[]}"
+CREATE_OK="${FAKE_CREATE_OK:-true}"
+
+case "$sub" in
+  "org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
+  "data query")
+    if printf '%s' "$args" | grep -q "FROM Organization"; then
+      if [ "$SANDBOX" = "true" ]; then OT="Developer Edition"; else OT="Enterprise Edition"; fi
+      echo "{\"status\":0,\"result\":{\"records\":[{\"IsSandbox\":$SANDBOX,\"TrialExpirationDate\":null,\"OrganizationType\":\"$OT\"}]}}"
+    elif printf '%s' "$args" | grep -q "FROM OmniSupervisorConfig\b"; then
+      case "$CFG_COUNT" in
+        0) echo '{"status":0,"result":{"records":[]}}';;
+        2) echo '{"status":0,"result":{"records":[{"Id":"0Q2xx0000000001AAA","DeveloperName":"Omni_Supervisor"},{"Id":"0Q2xx0000000002AAA","DeveloperName":"Second_Config"}]}}';;
+        *) echo '{"status":0,"result":{"records":[{"Id":"0Q2xx0000000001AAA","DeveloperName":"Omni_Supervisor"}]}}';;
+      esac
+    elif printf '%s' "$args" | grep -q "FROM OmniSupervisorConfigAction"; then
+      echo "{\"status\":0,\"result\":{\"records\":$(printf '%s' "$EXIST_ACTIONS" | jq -c 'to_entries | map({OmniSupervisorActionType:.value, DisplayOrder:(.key+1)})')}}"
+    elif printf '%s' "$args" | grep -q "FROM OmniSupervisorConfigTab"; then
+      echo "{\"status\":0,\"result\":{\"records\":$(printf '%s' "$EXIST_TABS" | jq -c 'to_entries | map({OmniSupervisorTabType:.value, DisplayOrder:(.key+1)})')}}"
+    else
+      echo '{"status":0,"result":{"records":[]}}'
+    fi
+    exit 0;;
+  "data create")
+    if [ "$CREATE_OK" = "true" ]; then
+      echo '{"status":0,"result":{"id":"0Q3xx0000000001AAA","success":true}}'
+    else
+      echo '{"status":1,"name":"FIELD_INTEGRITY_EXCEPTION","message":"bad value for restricted picklist field"}'
+    fi
+    exit 0;;
+  *) echo '{"status":0,"result":{}}'; exit 0;;
+esac
+"""
+
+
+def run(args, path_prefix=None, scrub_sf=False, extra_env=None):
+    env = dict(os.environ)
+    if scrub_sf:
+        kept = [d for d in env.get("PATH", "").split(os.pathsep)
+                if d and not os.path.exists(os.path.join(d, "sf"))]
+        env["PATH"] = os.pathsep.join(kept)
+    if path_prefix:
+        env["PATH"] = path_prefix + os.pathsep + env.get("PATH", "")
+    if extra_env:
+        env.update({k: str(v) for k, v in extra_env.items()})
+    proc = subprocess.run(
+        ["bash", str(SKILLS_ROOT / SCRIPT), *args],
+        capture_output=True, text=True, env=env, cwd=str(SKILLS_ROOT),
+    )
+    return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+
+class FakeSf:
+    def __init__(self, body=_FAKE_SF):
+        self._body = body
+        self._tmp = None
+
+    def __enter__(self):
+        self._tmp = tempfile.mkdtemp(prefix="supsurface-fake-sf-")
+        sf = Path(self._tmp) / "sf"
+        sf.write_text(self._body)
+        sf.chmod(0o755)
+        return self._tmp
+
+    def __exit__(self, *exc):
+        import shutil
+        if self._tmp:
+            shutil.rmtree(self._tmp, ignore_errors=True)

package/skills/service-omni-supervisor-surface-deploy/scripts/tests/test_supervisor_surface_contracts.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Contract tests for service-omni-supervisor-surface-deploy/scripts/deploy-and-report.sh."""
+from __future__ import annotations
+
+import json
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _bootstrap import FakeSf, _FAKE_SF, run  # noqa: E402
+
+
+def _last_json(out: str) -> dict:
+    dec = json.JSONDecoder()
+    obj, i, n = None, 0, len(out)
+    while i < n:
+        if out[i] in "{[":
+            try:
+                cand, end = dec.raw_decode(out, i)
+                if isinstance(cand, dict):
+                    obj = cand
+                i = end
+                continue
+            except json.JSONDecodeError:
+                pass
+        i += 1
+    assert obj is not None, f"no JSON object found in output:\n{out}"
+    return obj
+
+
+def _detect(env=None, args=("org",)):
+    with FakeSf(_FAKE_SF) as p:
+        return run(list(args), path_prefix=p, extra_env=env or {})
+
+
+class InputContractTests(unittest.TestCase):
+    def test_missing_args_rejected(self):
+        rc, out = run([], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Usage", out)
+
+    def test_bad_config_name_rejected(self):
+        rc, out = run(["org", "1badname"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid config_developer_name", out)
+
+    def test_reference_required_action_blocked(self):
+        rc, out = _detect({"SUPERVISOR_ACTIONS": "AllAgents.CustomAction"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("external reference", v["blocking_issue"], out)
+
+    def test_reference_required_tab_blocked(self):
+        rc, out = _detect({"SUPERVISOR_TABS": "FlexipageType"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+
+    def test_unsupported_type_blocked(self):
+        rc, out = _detect({"SUPERVISOR_TABS": "NotARealTab"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("Unsupported tab type", v["blocking_issue"], out)
+
+
+class SafetyAndResolutionTests(unittest.TestCase):
+    def test_production_org_blocked(self):
+        rc, out = _detect({"FAKE_SANDBOX": "false"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("production", v["blocking_issue"], out)
+
+    def test_no_config_blocks_with_pointer(self):
+        rc, out = _detect({"FAKE_CFG_COUNT": "0"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertTrue(any(a.get("target_skill") == "service-omni-supervisor-config-deploy"
+                            for a in v["manual_actions"]), out)
+
+    def test_multiple_configs_without_name_blocks(self):
+        rc, out = _detect({"FAKE_CFG_COUNT": "2"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("Multiple", v["blocking_issue"], out)
+
+
+class StateModelTests(unittest.TestCase):
+    def test_created_on_empty_surface(self):
+        rc, out = _detect({"FAKE_EXIST_ACTIONS": "[]", "FAKE_EXIST_TABS": "[]"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "created", out)
+        self.assertEqual(len(v["actions"]["created"]), 5, out)
+        self.assertEqual(len(v["tabs"]["created"]), 5, out)
+        self.assertEqual(v["actions"]["reused"], [], out)
+
+    def test_reused_when_all_present(self):
+        acts = json.dumps(["AllAgents.ChangeQueues", "AllAgents.ChangeSkills",
+                           "AllAgents.ChangeGroups", "AllAgents.AssignLearning",
+                           "QueuesBacklog.ManageQueues"])
+        tabs = json.dumps(["Wallboard", "Agents", "QueuesBacklog", "AssignedWork", "SkillsBacklog"])
+        rc, out = _detect({"FAKE_EXIST_ACTIONS": acts, "FAKE_EXIST_TABS": tabs})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "reused", out)
+        self.assertEqual(v["actions"]["created"], [], out)
+        self.assertEqual(v["tabs"]["created"], [], out)
+
+    def test_partial_diff_inserts_only_missing(self):
+        rc, out = _detect({
+            "FAKE_EXIST_ACTIONS": json.dumps(["AllAgents.ChangeQueues"]),
+            "FAKE_EXIST_TABS": json.dumps(["Wallboard"]),
+        })
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "created", out)
+        self.assertIn("AllAgents.ChangeQueues", v["actions"]["reused"], out)
+        self.assertNotIn("AllAgents.ChangeQueues", v["actions"]["created"], out)
+        self.assertEqual(len(v["actions"]["created"]), 4, out)
+        self.assertEqual(len(v["tabs"]["created"]), 4, out)
+
+    def test_plan_only_makes_no_writes(self):
+        rc, out = _detect({"PLAN_ONLY": "1"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "action_needed", out)
+        self.assertTrue(v["plan_mode"], out)
+        self.assertEqual(v["actions"]["created"], [], out)
+
+    def test_insert_failure_blocks(self):
+        rc, out = _detect({"FAKE_CREATE_OK": "false"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("Failed to insert", v["blocking_issue"], out)
+
+    def test_custom_tab_set_honored(self):
+        rc, out = _detect({"SUPERVISOR_TABS": "Wallboard,Reports,Alerts",
+                           "SUPERVISOR_ACTIONS": "AllAgents.ChangeQueues"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "created", out)
+        self.assertEqual(sorted(v["tabs"]["created"]), ["Alerts", "Reports", "Wallboard"], out)
+        self.assertEqual(v["actions"]["created"], ["AllAgents.ChangeQueues"], out)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/service-omni-supervisor-users-create/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: service-omni-supervisor-users-create
+description: "Use to create N Omni-Channel supervisor users on a Salesforce org via Anonymous Apex, using the supervisor{i}.<suffix>@example.com pattern with SOQL-based idempotency (re-runs skip existing usernames). Passwords are set via System.setPassword and handled fail-closed: the wrapper proves no active debug TraceFlag before setting a password, and otherwise leaves the user ACTIVE and reset_required. Triggers: create supervisor users, provision supervisor accounts, scaffold supervisor personas. Do not use on production customer orgs (blocked by the safe_to_write guard), to bind supervisors to OmniSupervisorConfig (service-omni-supervisor-config-deploy), or to assign the ContactCenterSupervisor permission set (service-omni-supervisor-permset-assign)."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-agent-users-create"
+    - "service-omni-supervisor-config-deploy"
+    - "service-omni-supervisor-permset-assign"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-supervisor-users-create
+
+Create N supervisor users on a Salesforce org for the classic Omni-Channel Supervisor Configuration (`OmniSupervisorConfig`), which binds named user records via `OmniSupervisorConfigUser`. Users follow a deterministic `supervisor{i}.<suffix>@example.com` pattern so the coordinator can rediscover them across runs. It is the supervisor counterpart to `service-omni-agent-users-create` and shares its detection, password, and idempotency model; the only differences are the username/alias prefixes and the debug-log marker. Binding these users into a config (`service-omni-supervisor-config-deploy`) and granting them supervisor access (`service-omni-supervisor-permset-assign`) are separate leaves.
+
+## Inputs
+
+Confirm once, up front:
+
+- `org-alias` (required, no default) — must resolve via `sf org display`.
+- Supervisor count (optional, default `1`, range `1..5`; the coordinator typically requests 1).
+- Profile name (optional, default `Standard User`). The coordinator overrides this to a Service Cloud profile so supervisors consume Service Cloud licenses; supervisor access itself comes from the standard `ContactCenterSupervisor` permission set assigned later.
+
+Usernames and passwords are never accepted from the operator — both are generated (usernames from the org suffix, passwords via Anonymous Apex).
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI (My Domain URL, not `.lightning.force.com`), Service Cloud license present, `sf` CLI ≥ 2.139.6.
+- The executing user has `PermissionsModifyAllData` and `PermissionsManagePasswordPolicies` (standard on System Administrator).
+- **Production guardrail:** the detect script computes `safe_to_write` as `IsSandbox` OR `TrialExpirationDate != null` OR `OrganizationType` in {Developer Edition, Base Edition}, and the skill blocks with no override when it is false. CDOs, scratch orgs, and dev orgs are permitted.
+
+**Password handling (fail-closed).** Passwords are set by Anonymous Apex `System.setPassword` (`sf user password generate` cannot target Apex-inserted users). The literal appears in the inline executeAnonymous debug log and, only when a debug-log TraceFlag is active for the running user, in a queryable `ApexLog`. The wrapper therefore fails closed *before* the first `System.setPassword`: it proves via a SOQL-filtered Tooling API query (`ExpirationDate > now`) that no active TraceFlag exists. If safety cannot be positively proven, it sets no password at all; the user is left ACTIVE, flagged `password_status:"reset_required"`, and a `security_warning` explains why. It never deletes logs. A user whose password could not be set is kept ACTIVE and flagged for reset — never deactivated.
+
+## Run
+
+```bash
+# read-only preview (never writes)
+bash scripts/detect-and-create.sh plan <org-alias> [count] [profile-name]
+# detect, enforce safe_to_write, then insert only the missing supervisors
+bash scripts/detect-and-create.sh run  <org-alias> [count=1] [profile-name="Standard User"]
+```
+
+`detect-and-create.sh` is the canonical entry point: it re-runs detection, enforces the production guard, and only then inserts. Do not call `scripts/run-create.sh` directly — it is internal and does not enforce the guard.
+
+## Behavior
+
+**Detection.** The detector derives an 8-char suffix from `Organization.Id`, resolves the profile by name, and queries `User` for `supervisor{i}.<suffix>@example.com`, splitting occupied slots into active `existing_users` and `inactive_users`.
+
+**Insertion.** The Apex loads `assets/create-supervisors.apex.template`, substitutes `__COUNT__`/`__PROFILE_ID__`/`__SUFFIX__`, and inserts only the missing indexes, re-checking inside the transaction to prevent a single run from double-inserting; across *concurrent* runs this check is not a guarantee (both can pass their pre-query before either commits), so duplicate protection there relies on the global username-uniqueness constraint plus the `DUPLICATE_USERNAME` retry (see references/apex-template-notes.md). Created users get the Service Cloud feature (`UserPermissionsSupportUser=true`); if the profile's license does not allow it, the Apex strips the flag and retries (the permset assign will then block until the user is on a suitable license). Each created user is reported via `SUPERVISOR_CREATED|<id>|<username>|<email>` (no password in the marker — it is set by the separate `System.setPassword` submission).
+
+**Inactive occupants.** An inactive user occupying a supervisor slot is not a reusable supervisor and cannot be recreated (usernames are globally unique). It is surfaced as a required manual reactivation and never counted toward the requested slots — counting it would under-provision the config.
+
+**Verification.** After insertion the detector re-runs and must show `missing_count == 0`.
+
+## Output contract
+
+`detect-and-create.sh` emits a single JSON object with `status` ∈ `created` | `partial` | `reused` | `action_needed` | `blocked`, plus `detect`, `create` (`null` when nothing was created), `created_count`, `reused_count`, `total_present_after`, `users_needing_password_reset`, `action_required`, and `safe_to_write`.
+
+- `created` — every missing index landed with a working password.
+- `partial` — some landed but not all, any `System.setPassword` failed (kept ACTIVE, listed in `users_needing_password_reset`), or a slot is occupied by an inactive user needing reactivation.
+- `reused` — all requested slots already existed; no DML.
+- `action_needed` — plan mode only.
+- `blocked` — precondition failed.
+
+`create.created_users[].password` is populated only for users created this run whose `System.setPassword` succeeded. `create.rolled_back_users` is always empty (this skill never deactivates a user). Generated passwords are a secret: the returned JSON is the only place they appear; a caller that persists stdout must write it only to a restricted `CREDENTIALS.json` (mode 0600), redact it elsewhere, and delete it after distribution — the coordinator does this automatically.
+
+## Limitations
+
+- Username pattern and org suffix are fixed and never operator-configurable — that determinism is what enables idempotent re-runs.
+- Creates only supervisor users; it never deletes or deactivates users, including orphaned supervisors from prior runs.
+- Common User errors (`DUPLICATE_USERNAME`, `INVALID_EMAIL`, `LICENSE_LIMIT_EXCEEDED`) are translated into operator-friendly messages rather than surfaced raw.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/apex-patterns.md` | Before running the Apex — Apex structure, User field defaults, password policy, and the profile-localization risk |
+| `references/apex-template-notes.md` | When creation returns a duplicate, license, password, or trace-safety error |
+| `assets/create-supervisors.apex.template` | Loaded by `scripts/run-create.sh` when missing supervisor users must be inserted |
+| `scripts/detect-existing.sh` | Loaded by `scripts/detect-and-create.sh` for the read-only org, profile, safety, and existing-user checks |
+| `scripts/run-create.sh` | Internal writer loaded by `scripts/detect-and-create.sh` only after guard checks pass |

package/skills/service-omni-supervisor-users-create/assets/create-supervisors.apex.template

@@ -0,0 +1,72 @@
+// service-omni-supervisor-users-create - Anonymous Apex asset template. Tokens __COUNT__/__PROFILE_ID__/__SUFFIX__ resolved by run-create.sh. Idempotency, password/TraceFlag security note, output contract: references/apex-template-notes.md.
+
+Integer requested = __COUNT__;
+String profileId  = '__PROFILE_ID__';
+String suffix     = '__SUFFIX__';
+
+Map<String, Integer> expectedByUsername = new Map<String, Integer>();
+for (Integer i = 1; i <= requested; i++) {
+    expectedByUsername.put('supervisor' + i + '.' + suffix + '@example.com', i);
+}
+
+Set<String> existingUsernames = new Set<String>();
+for (User u : [SELECT Username FROM User WHERE Username IN :expectedByUsername.keySet()]) {
+    existingUsernames.add(u.Username.toLowerCase());
+}
+
+List<User> toInsert = new List<User>();
+
+for (Integer i = 1; i <= requested; i++) {
+    String uname = 'supervisor' + i + '.' + suffix + '@example.com';
+    if (existingUsernames.contains(uname.toLowerCase())) {
+        continue;
+    }
+
+    // Alias must be <= 8 chars - construct as omsu{i}{last-3-of-suffix}
+    // For i=1..9: 'omsu' (4) + i (1) + last-3-suffix (3) = 8 chars. OK.
+    String aliasStr = 'omsu' + i + suffix.substring(suffix.length() - 3);
+
+    User u = new User(
+        FirstName           = 'Omni',
+        LastName            = 'Supervisor' + i,
+        Email               = uname,
+        Username            = uname,
+        Alias               = aliasStr,
+        ProfileId           = profileId,
+        IsActive            = true,
+        // Service Cloud feature license - REQUIRED for the ContactCenterSupervisor permset
+        // (IsContactCenterSupervisor is license-gated). Only allowed on user licenses that
+        // support it (e.g. Salesforce); the try/catch strips it and retries when the profile's
+        // user license rejects it (e.g. the limited "Service Cloud" user license). In that
+        // fallback the supervisor permset assign will later block until the user is moved to a
+        // Salesforce license + Service Cloud feature.
+        UserPermissionsSupportUser = true,
+        TimeZoneSidKey      = 'America/Los_Angeles',
+        LocaleSidKey        = 'en_US',
+        EmailEncodingKey    = 'UTF-8',
+        LanguageLocaleKey   = 'en_US'
+    );
+    toInsert.add(u);
+}
+
+if (toInsert.isEmpty()) {
+    System.debug('SUPERVISORS_ALL_EXIST - no inserts required');
+    return;
+}
+
+try {
+    insert toInsert;
+    System.debug('SUPERVISORS_SERVICE_CLOUD_FEATURE|enabled');
+} catch (DmlException e) {
+    if (e.getMessage() != null && e.getMessage().contains('Service Cloud User')) {
+        for (User u : toInsert) { u.UserPermissionsSupportUser = false; }
+        insert toInsert;
+        System.debug('SUPERVISORS_SERVICE_CLOUD_FEATURE|skipped_license_not_allowed');
+    } else {
+        throw e;
+    }
+}
+
+for (User u : toInsert) {
+    System.debug('SUPERVISOR_CREATED|' + u.Id + '|' + u.Username + '|' + u.Email);
+}