@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-omni-agent-users-create/references/apex-patterns.md

@@ -0,0 +1,135 @@
+# Apex patterns for agent user creation
+
+Load this reference **only when the Apex block is actually going to run** (i.e., after `detect-existing.sh` returned `missing_count > 0`). It covers the Apex structure, `User` sObject required fields, password policy, profile-localization gotcha, and the emitted-log contract.
+
+**Apex version verified:** v66 (Summer '26 baseline).
+**Runtime:** Anonymous Apex via `sf apex run --target-org <alias> --file <resolved>.apex`.
+
+---
+
+## The Apex template shape
+
+The template at `assets/create-users.apex.template` uses three tokens:
+
+| Token | Type | Resolved by |
+|---|---|---|
+| `__COUNT__` | integer 1..10 | `run-create.sh` argument 2 (from operator input, default 3) |
+| `__PROFILE_ID__` | 18-char Profile Id | `detect-existing.sh` from `SELECT Id FROM Profile WHERE Name = ?` |
+| `__SUFFIX__` | 8-char lowercase hex | `detect-existing.sh` from `Organization.Id.substring(10, 18).toLowerCase()` |
+
+Token substitution uses `sed` with **pipe (`|`) as the delimiter**, not `/`. This is not because Ids or names contain `/` (they do not) but because pipe is universally not-a-metacharacter in `sed`, avoiding future foot-guns if a token value ever contains a `/`.
+
+---
+
+## `User` sObject required fields
+
+Salesforce enforces the following as required (non-nullable) when inserting a `User`:
+
+| Field | Value used | Notes |
+|---|---|---|
+| `Username` | `agent{i}.{suffix}@example.com` | Must be globally unique across all Salesforce orgs. Our suffix strategy makes this per-org-unique; `@example.com` domain avoids sending real email |
+| `Email` | same as `Username` | Salesforce enforces per-org email uniqueness (not global) — same suffix works |
+| `LastName` | `Agent{i}` | Required, no default |
+| `Alias` | `omag{i}{last-3-of-suffix}` (or `last-2` for i≥10) | Max 8 chars. Cross-org uniqueness NOT required |
+| `ProfileId` | resolved from `Profile.Name` | See profile-localization note below |
+| `TimeZoneSidKey` | `America/Los_Angeles` | Safe default for CDOs |
+| `LocaleSidKey` | `en_US` | Safe default |
+| `EmailEncodingKey` | `UTF-8` | Safe default |
+| `LanguageLocaleKey` | `en_US` | Safe default; not all orgs enable all languages, but `en_US` is always available |
+
+Optional but set for clarity: `FirstName = 'Omni'`, `IsActive = true`.
+
+---
+
+## Password policy & `System.setPassword`
+
+Default org password policy on Enterprise Edition CDOs: min 8 chars, must contain at least 1 letter and 1 number. Our password format `AgntV1<10-hex>` satisfies this (contains `A`, `V` (upper), `g`, `n`, `t` (lower), `1` (digit), plus hex chars which contribute more letters+digits).
+
+**`System.setPassword(Id, String)` requirements:**
+- Executing user must have `PermissionsManagePasswordPolicies=true` (standard on System Administrator)
+- Password must satisfy the org's password policy (`Setup → Password Policies`)
+- On success, the user's password is set immediately; the user does NOT receive a verification email and is immediately usable
+- On failure (policy violation), throws `System.NoAccessException` or a `System.InvalidPasswordException` — the skill's Apex catches these per-user and emits a `AGENT_USERS_PASSWORD_ERRORS` line without failing the whole run
+
+**Note:** the skill's Apex sets passwords AFTER inserting users, not as a single atomic transaction. If a password-set fails for user N, the user still exists but has no password (Salesforce assigns a random one internally). The operator can then use "Reset Password" in Setup.
+
+---
+
+## Idempotency (belt + suspenders)
+
+Two independent guards:
+
+1. **Pre-check (in `detect-existing.sh`):** query `User` by username pattern → return `missing_indexes` array. If empty, skip Apex entirely.
+2. **In-Apex re-check:** the Apex block queries `User WHERE Username IN :expectedByUsername.keySet()` inside its transaction, then builds `toInsert` from only the truly missing indexes. This handles two edge cases:
+   - Concurrent skill runs (rare): two agents run this skill against the same org at nearly the same time
+   - State drift between pre-check and Apex execution (very rare): another skill or manual UI action creates a matching user between the two SOQL queries
+
+The in-Apex re-check makes the skill safe even if the pre-check is stale. In the concurrent-race case, the second run will find all users existing and emit `AGENT_USERS_ALL_EXIST` with no inserts.
+
+---
+
+## Profile-localization gotcha
+
+`Profile.Name` is **not localized** for standard profiles (`Standard User`, `System Administrator`, `Marketing User`, etc.) as of v66 — verified on EPIC CDOs (English). But other Salesforce edition variants may localize these names (`Utilisateur standard` on French orgs?). Empirically we have not seen this, but the skill accepts the risk with a hardcoded default of `Standard User`.
+
+**If a user overrides `--profile` to a custom profile**, they own the risk that the profile name is spelled correctly and matches exactly (case-sensitive). Custom profiles have a `DeveloperName` field (API-stable) but standard profiles do not — so this skill uses `Name` as the only universal lookup key.
+
+A fallback query that also matches `DeveloperName` is possible:
+```sql
+SELECT Id FROM Profile WHERE Name = :profileName OR DeveloperName = :profileName LIMIT 1
+```
+The skill uses `Name` only, to keep the query simple and the error message clear.
+
+---
+
+## The emitted-log contract (parsed by `run-create.sh`)
+
+The Apex block emits three kinds of `System.debug` lines that the shell script parses:
+
+| Line prefix | When | Format |
+|---|---|---|
+| `AGENT_USER_CREATED` | One per newly-created user (never for reused users) | `AGENT_USER_CREATED\|<userId>\|<username>\|<password>\|<email>` |
+| `AGENT_USERS_ALL_EXIST` | When `toInsert` is empty (all N users already existed at Apex transaction time) | Exactly the string `AGENT_USERS_ALL_EXIST — no inserts required` |
+| `AGENT_USERS_PASSWORD_ERRORS` | When one or more `System.setPassword` calls failed | `AGENT_USERS_PASSWORD_ERRORS: <JSON-array of "username: error-message">` |
+
+`run-create.sh` greps for these lines (they are the only lines starting with `AGENT_`), parses them, and constructs the return JSON.
+
+---
+
+## Failure modes
+
+| Symptom in Apex output | Root cause | Skill behavior |
+|---|---|---|
+| `DUPLICATE_USERNAME` | Global-uniqueness violation — another org somewhere in Salesforce owns this username | Should not happen with the org-id suffix strategy. If it does, run detect again — likely a race with a concurrent run. Fail if it persists |
+| `INVALID_EMAIL_ADDRESS` | Should not happen with `@example.com`. Would indicate a bug in username construction | Fail and escalate — skill logic error |
+| `LICENSE_LIMIT_EXCEEDED` | Org's Salesforce license count is at max | Fail with an operator-friendly message: "Org has reached its user license limit — free up a license slot or ask Salesforce for more" |
+| `System.NoAccessException` on `System.setPassword` | Executing user lacks `ManagePasswordPolicies` perm | Skill continues (per-user catch), emits `AGENT_USERS_PASSWORD_ERRORS`, operator uses Setup → Reset Password |
+| `System.InvalidPasswordException` on `System.setPassword` | Org has a stricter password policy than our `AgntV1<10-hex>` satisfies | Should not happen with default policies. Skill continues, emits `AGENT_USERS_PASSWORD_ERRORS`, escalate to update the password generator |
+| `UNABLE_TO_LOCK_ROW` | Concurrent transaction locked the `User` table | Retry the skill once. Rare on CDOs |
+
+---
+
+## Production-safety signal (three-way check)
+
+**Discovery during on-org testing:** `IsSandbox` alone is insufficient to distinguish "safe to write demo data" from "real customer production". CDOs (Customer Demo Orgs, our primary target shape) have `IsSandbox=false` because they are not derived from a production org — they are standalone Enterprise Edition orgs with a trial expiration.
+
+The correct three-way check:
+
+```sql
+SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1
+```
+
+`safe_to_write = true` if **any** of the following is true:
+
+| Signal | Meaning |
+|---|---|
+| `IsSandbox = true` | Real sandbox — safe by construction |
+| `TrialExpirationDate != null` | Trial org, CDO, or similar time-limited org — safe |
+| `OrganizationType = 'Developer Edition'` | Dev org — safe |
+| `OrganizationType = 'Base Edition'` | Scratch org — safe |
+
+`safe_to_write = false` only when **all four** signals fail — i.e., `IsSandbox=false` AND `TrialExpirationDate=null` AND `OrganizationType NOT IN ('Developer Edition', 'Base Edition')`. That combination is definitionally a real customer production org.
+
+**Example:** a CDO reporting `IsSandbox=false`, a non-null `TrialExpirationDate`, and `OrganizationType=Enterprise Edition` resolves to `safe_to_write=true` — the correct behavior for a demo/trial org.
+
+**Other write-capable skills reuse this same three-way check.** A naive `IsSandbox=true` check would incorrectly block all CDOs, which are the primary target shape for these skills.

package/skills/service-omni-agent-users-create/references/apex-template-notes.md

@@ -0,0 +1,40 @@
+# `create-users.apex.template` notes
+
+Anonymous Apex template for creating agent demo users. `run-create.sh` resolves the tokens
+before execution and submits the rendered Apex.
+
+## Tokens
+
+| token | meaning |
+| --- | --- |
+| `__COUNT__` | integer 1..10 — number of user slots |
+| `__PROFILE_ID__` | 18-char Profile Id (e.g. `00eRZ00000012tKYAQ`) |
+| `__SUFFIX__` | 8-char lowercase hex string derived from `Organization.Id` |
+
+## Idempotency
+
+The block re-queries existing users inside the transaction and inserts only the truly
+missing indexes. Two concurrent runs can both pass the pre-query before either commits;
+Salesforce's `DUPLICATE_USERNAME` constraint is the authoritative deduplicator, and
+`run-create.sh` treats `DUPLICATE_USERNAME` as "another agent won the race" and retries a
+re-detect.
+
+## Security note (password / TraceFlag)
+
+This block only creates the `User` rows and never emits a password via `System.debug`. The
+caller (`run-create.sh`) sets each password with a SEPARATE Anonymous Apex
+`System.setPassword(id, pw)` submission per newly-created user. That plaintext lives in the
+submitted Apex source, which appears in the inline `executeAnonymous` debug log and — ONLY
+when a debug-log TraceFlag is active for the running user — in a queryable `ApexLog` row.
+`run-create.sh` proves no active TraceFlag exists before calling `System.setPassword` and
+otherwise fails closed (no password set), so plaintext never reaches a queryable log.
+
+## Output contract
+
+For every user created this run, `System.debug` emits one line:
+
+```text
+AGENT_USER_CREATED|<userId>|<username>|<email>
+```
+
+which `run-create.sh` greps from the log to build the skill's JSON return value.

package/skills/service-omni-agent-users-create/scripts/detect-and-create.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+# detect-and-create.sh - canonical entry point: chains detect-existing.sh → run-create.sh (plan|run), idempotent, production-guarded. Args, JSON status contract, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo '{"status":"blocked","blocking_issue":"Missing required args","usage":"bash detect-and-create.sh <plan|run> <org-alias> [count=3] [profile-name=\"Standard User\"]"}' >&2
+  exit 1
+fi
+
+MODE="$1"
+ORG="$2"
+COUNT="${3:-3}"
+PROFILE_NAME="${4:-Standard User}"
+
+case "$MODE" in
+  plan|run) ;;
+  *)
+    echo "{\"status\":\"blocked\",\"blocking_issue\":\"Invalid mode '$MODE'. Expected 'plan' or 'run'.\"}" >&2
+    exit 1
+    ;;
+esac
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DETECT_SCRIPT="$SCRIPT_DIR/detect-existing.sh"
+CREATE_SCRIPT="$SCRIPT_DIR/run-create.sh"
+
+if [ ! -f "$DETECT_SCRIPT" ]; then
+  echo "{\"status\":\"blocked\",\"blocking_issue\":\"Sibling script not found: $DETECT_SCRIPT\"}" >&2
+  exit 1
+fi
+if [ "$MODE" = "run" ] && [ ! -f "$CREATE_SCRIPT" ]; then
+  echo "{\"status\":\"blocked\",\"blocking_issue\":\"Sibling script not found: $CREATE_SCRIPT\"}" >&2
+  exit 1
+fi
+
+# Step 1: detect
+DETECT_EXIT=0
+DETECT_JSON=$(bash "$DETECT_SCRIPT" "$ORG" "$COUNT" "$PROFILE_NAME" 2>&1) || DETECT_EXIT=$?
+
+if [ "$DETECT_EXIT" -ne 0 ]; then
+  jq -n --arg raw "$DETECT_JSON" --argjson exit "$DETECT_EXIT" \
+    '{status:"blocked",blocking_issue:("detect-existing.sh exited " + ($exit|tostring)),detect_raw:$raw,create:null}'
+  exit 1
+fi
+
+if ! echo "$DETECT_JSON" | jq -e . >/dev/null 2>&1; then
+  jq -n --arg raw "$DETECT_JSON" \
+    '{status:"blocked",blocking_issue:"detect-existing.sh produced non-JSON output",detect_raw:$raw,create:null}'
+  exit 1
+fi
+
+MISSING_COUNT=$(echo "$DETECT_JSON" | jq -r '.missing_count // 0')
+SAFE_TO_WRITE=$(echo "$DETECT_JSON" | jq -r '.safe_to_write // false')
+PROFILE_ID=$(echo "$DETECT_JSON" | jq -r '.profile_id // ""')
+ORG_SUFFIX=$(echo "$DETECT_JSON" | jq -r '.org_suffix // ""')
+EXISTING_COUNT=$(echo "$DETECT_JSON" | jq -r '.existing_users | length')
+REUSED_USERS=$(echo "$DETECT_JSON" | jq -c '.existing_users // []')
+# A deactivated user in a slot is neither reusable nor recreatable (globally-unique username);
+# surface it as a manual action so a dead slot never passes as clean.
+INACTIVE_COUNT=$(echo "$DETECT_JSON" | jq -r '.inactive_count // 0')
+INACTIVE_ACTION=""
+if [ "$INACTIVE_COUNT" -gt 0 ]; then
+  INACTIVE_ACTION="$INACTIVE_COUNT agent slot(s) are occupied by DEACTIVATED users (see inactive_users). Their usernames are globally unique so they cannot be recreated - reactivate them in Setup → Users, or free the usernames, before those slots can be used."
+fi
+
+# Step 2: early returns. Nothing missing => "reused" (or action_needed if a dead slot is present).
+if [ "$MISSING_COUNT" = "0" ]; then
+  if [ "$INACTIVE_COUNT" -gt 0 ]; then
+    jq -n \
+      --argjson detect "$DETECT_JSON" \
+      --argjson reused_users "$REUSED_USERS" \
+      --argjson reused_count "$EXISTING_COUNT" \
+      --arg action "$INACTIVE_ACTION" \
+      '{
+        status: "action_needed",
+        action_required: $action,
+        detect: $detect,
+        reused_users: $reused_users,
+        create: null,
+        created_count: 0,
+        reused_count: $reused_count,
+        total_present_after: $reused_count,
+        safe_to_write: $detect.safe_to_write
+      }'
+    exit 0
+  fi
+  jq -n \
+    --argjson detect "$DETECT_JSON" \
+    --argjson reused_users "$REUSED_USERS" \
+    --argjson reused_count "$EXISTING_COUNT" \
+    '{
+      status: "reused",
+      detect: $detect,
+      reused_users: $reused_users,
+      create: null,
+      created_count: 0,
+      reused_count: $reused_count,
+      total_present_after: $reused_count,
+      safe_to_write: $detect.safe_to_write
+    }'
+  exit 0
+fi
+
+# --plan mode: never create. Report action_needed with the missing indexes (and any dead slots).
+if [ "$MODE" = "plan" ]; then
+  jq -n \
+    --argjson detect "$DETECT_JSON" \
+    --argjson reused_users "$REUSED_USERS" \
+    --argjson reused_count "$EXISTING_COUNT" \
+    --argjson missing_count "$MISSING_COUNT" \
+    --arg inactive_action "$INACTIVE_ACTION" \
+    '{
+      status: "action_needed",
+      action_required: (
+        "Missing " + ($missing_count|tostring) + " user(s) at indexes " + ($detect.missing_indexes | map(tostring) | join(",")) + ". Re-run in --run mode to create."
+        + (if $inactive_action == "" then "" else " ALSO: " + $inactive_action end)
+      ),
+      detect: $detect,
+      reused_users: $reused_users,
+      create: null,
+      created_count: 0,
+      reused_count: $reused_count,
+      total_present_after: $reused_count,
+      safe_to_write: $detect.safe_to_write
+    }'
+  exit 0
+fi
+
+# Step 3: --run mode with missing users - safe_to_write guard, then create.
+if [ "$SAFE_TO_WRITE" != "true" ]; then
+  jq -n --argjson detect "$DETECT_JSON" \
+    '{status:"blocked",blocking_issue:"safe_to_write=false - refusing to create users on a production customer org.",detect:$detect,create:null,created_count:0,reused_count:0,total_present_after:0,safe_to_write:false}'
+  exit 1
+fi
+
+if [ -z "$PROFILE_ID" ] || [ -z "$ORG_SUFFIX" ]; then
+  jq -n --argjson detect "$DETECT_JSON" \
+    '{status:"blocked",blocking_issue:"detect-existing.sh did not resolve profile_id or org_suffix - cannot invoke create.",detect:$detect,create:null,created_count:0,reused_count:0,total_present_after:0,safe_to_write:$detect.safe_to_write}'
+  exit 1
+fi
+
+CREATE_EXIT=0
+CREATE_JSON=$(bash "$CREATE_SCRIPT" "$ORG" "$COUNT" "$PROFILE_ID" "$ORG_SUFFIX" 2>&1) || CREATE_EXIT=$?
+
+if [ "$CREATE_EXIT" -ne 0 ]; then
+  jq -n --argjson detect "$DETECT_JSON" --arg raw "$CREATE_JSON" --argjson exit "$CREATE_EXIT" \
+    '{status:"blocked",blocking_issue:("run-create.sh exited " + ($exit|tostring)),detect:$detect,create:null,create_raw:$raw,created_count:0,reused_count:0,total_present_after:0,safe_to_write:$detect.safe_to_write}'
+  exit 1
+fi
+
+if ! echo "$CREATE_JSON" | jq -e . >/dev/null 2>&1; then
+  jq -n --argjson detect "$DETECT_JSON" --arg raw "$CREATE_JSON" \
+    '{status:"blocked",blocking_issue:"run-create.sh produced non-JSON output",detect:$detect,create:null,create_raw:$raw,created_count:0,reused_count:0,total_present_after:0,safe_to_write:$detect.safe_to_write}'
+  exit 1
+fi
+
+CREATED_COUNT=$(echo "$CREATE_JSON" | jq -r '.created_count // 0')
+ROLLED_BACK_COUNT=$(echo "$CREATE_JSON" | jq -r '.rolled_back_users | length')
+# A created user without a working password (setPassword failed, non-destructive: stays active +
+# reset_required) is not login-ready; any pending reset forces "partial" with a manual action.
+PW_RESET_COUNT=$(echo "$CREATE_JSON" | jq -r '(.users_needing_password_reset // []) | length')
+
+# Classify: created (all landed with a password) / partial (some landed, rollbacks, or pending
+# password resets) / blocked (nothing landed).
+if [ "$CREATED_COUNT" = "0" ]; then
+  STATUS="blocked"
+elif [ "$ROLLED_BACK_COUNT" -gt 0 ] || [ "$CREATED_COUNT" -lt "$MISSING_COUNT" ] || [ "$PW_RESET_COUNT" -gt 0 ] || [ "$INACTIVE_COUNT" -gt 0 ]; then
+  STATUS="partial"
+else
+  STATUS="created"
+fi
+
+jq -n \
+  --argjson detect "$DETECT_JSON" \
+  --argjson create "$CREATE_JSON" \
+  --argjson reused_users "$REUSED_USERS" \
+  --argjson created_count "$CREATED_COUNT" \
+  --argjson reused_count "$EXISTING_COUNT" \
+  --argjson pw_reset_count "$PW_RESET_COUNT" \
+  --arg inactive_action "$INACTIVE_ACTION" \
+  --arg status "$STATUS" \
+  '{
+    status: $status,
+    detect: $detect,
+    create: $create,
+    reused_users: $reused_users,
+    created_count: $created_count,
+    reused_count: $reused_count,
+    total_present_after: ($created_count + $reused_count),
+    users_needing_password_reset: ($create.users_needing_password_reset // []),
+    action_required: (
+      [
+        (if $pw_reset_count > 0 then
+          ($pw_reset_count | tostring) + " user(s) were created but could NOT have a password set automatically and cannot log in yet. Manually reset their passwords (Setup → Users → Reset Password, or `sf org open` → user record) before use. See users_needing_password_reset and CREDENTIALS.json."
+        else empty end),
+        (if $inactive_action == "" then empty else $inactive_action end)
+      ] | if length == 0 then null else join(" ") end
+    ),
+    safe_to_write: $detect.safe_to_write
+  }'
+
+case "$STATUS" in
+  created|partial) exit 0 ;;
+  blocked) exit 1 ;;
+esac

package/skills/service-omni-agent-users-create/scripts/detect-existing.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# detect-existing.sh - read-only probe for existing agent users (org/profile/existing/missing indexes); deterministic, no side effects. Args + JSON output: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo '{"error":"Missing required argument: org-alias","usage":"bash detect-existing.sh <org-alias> [count=3] [profile-name=\"Standard User\"]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+COUNT="${2:-3}"
+PROFILE_NAME="${3:-Standard User}"
+
+if ! [[ "$COUNT" =~ ^[1-9]$|^10$ ]]; then
+  echo "{\"error\":\"Count must be an integer in range 1..10, got: $COUNT\"}" >&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
+
+# 1. Query Organization: a production org fails all of IsSandbox / TrialExpirationDate!=null /
+#    OrganizationType in (Developer Edition, Base Edition).
+ORG_JSON=$(sf data query --target-org "$ORG" --query "SELECT Id, IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" --json 2>/dev/null || true)
+ORG_ID=$(echo "$ORG_JSON" | jq -r '.result.records[0].Id // empty')
+IS_SANDBOX=$(echo "$ORG_JSON" | jq -r '.result.records[0].IsSandbox // false')
+TRIAL_EXP=$(echo "$ORG_JSON" | jq -r '.result.records[0].TrialExpirationDate // "null"')
+ORG_TYPE=$(echo "$ORG_JSON" | jq -r '.result.records[0].OrganizationType // "Unknown"')
+
+if [ -z "$ORG_ID" ]; then
+  echo '{"error":"Failed to query Organization.Id - check org auth and API permissions."}' >&2
+  exit 1
+fi
+
+# Compute safe-to-write flag: true if the org is definitively NOT a production customer org.
+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
+
+# Derive suffix: last 8 chars of Organization.Id, lowercased. Deterministic per org.
+SUFFIX=$(echo -n "${ORG_ID:10:8}" | tr '[:upper:]' '[:lower:]')
+
+# 2. Query Profile. Profile.Name is a display name; escape ' for the SOQL literal (apostrophe safety + no injection).
+PROFILE_NAME_SOQL=${PROFILE_NAME//\'/\\\'}
+PROFILE_JSON=$(sf data query --target-org "$ORG" --query "SELECT Id, Name FROM Profile WHERE Name = '$PROFILE_NAME_SOQL' LIMIT 1" --json 2>/dev/null || true)
+PROFILE_ID=$(echo "$PROFILE_JSON" | jq -r '.result.records[0].Id // empty')
+
+if [ -z "$PROFILE_ID" ]; then
+  echo "{\"error\":\"Profile '$PROFILE_NAME' not found on org '$ORG'. Check spelling - profile names are case-sensitive on some orgs and may be localized.\"}" >&2
+  exit 1
+fi
+
+# 3. Query existing agent users matching the pattern
+USER_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id, Username, IsActive FROM User WHERE Username LIKE 'agent%.${SUFFIX}@example.com'" \
+  --json 2>/dev/null || true)
+
+# Build existing_users array + missing_indexes array via jq
+# For each i in 1..COUNT, check if agent{i}.<suffix>@example.com exists.
+EXPECTED_USERNAMES=$(seq 1 "$COUNT" | awk -v s="$SUFFIX" '{ printf "\"agent%s.%s@example.com\"\n", $1, s }' | jq -s '.')
+
+FULL_JSON=$(jq -n \
+  --arg org_id "$ORG_ID" \
+  --arg org_suffix "$SUFFIX" \
+  --argjson is_sandbox "$IS_SANDBOX" \
+  --arg trial_expiration_date "$TRIAL_EXP" \
+  --arg organization_type "$ORG_TYPE" \
+  --argjson safe_to_write "$SAFE_TO_WRITE" \
+  --arg profile_id "$PROFILE_ID" \
+  --arg profile_name "$PROFILE_NAME" \
+  --argjson count "$COUNT" \
+  --argjson expected "$EXPECTED_USERNAMES" \
+  --argjson user_records "$(echo "$USER_JSON" | jq '.result.records // []')" \
+  '
+  # Build a map: username -> {id, is_active}
+  ($user_records | map({ (.Username | ascii_downcase): {id: .Id, is_active: .IsActive} }) | add // {}) as $by_uname
+  |
+  # For each expected index, determine if user exists
+  [range(1; $count + 1) as $i
+   | ($expected[$i - 1] | ascii_downcase) as $uname
+   | if $by_uname[$uname] then
+       {index: $i, id: $by_uname[$uname].id, username: $uname, is_active: $by_uname[$uname].is_active}
+     else
+       null
+     end
+  ] as $slots
+  |
+  # occupied slots (any user present, active or not)
+  ($slots | map(select(. != null))) as $occupied
+  |
+  # existing_users: only active occupants are reusable; inactive users are surfaced separately
+  # (globally-unique username, not recreatable).
+  ($occupied | map(select(.is_active == true))) as $existing
+  |
+  ($occupied | map(select(.is_active != true))) as $inactive
+  |
+  # missing_indexes: indexes where the slot is empty (no user at all - safe to create)
+  ([range(1; $count + 1) as $i | if $slots[$i - 1] == null then $i else null end] | map(select(. != null))) as $missing
+  |
+  {
+    org_id: $org_id,
+    org_suffix: $org_suffix,
+    is_sandbox: $is_sandbox,
+    trial_expiration_date: (if $trial_expiration_date == "null" then null else $trial_expiration_date end),
+    organization_type: $organization_type,
+    safe_to_write: $safe_to_write,
+    profile_id: $profile_id,
+    profile_name: $profile_name,
+    requested_count: $count,
+    existing_users: $existing,
+    inactive_users: $inactive,
+    inactive_count: ($inactive | length),
+    missing_indexes: $missing,
+    missing_count: ($missing | length)
+  }
+  ')
+
+echo "$FULL_JSON"