@salesforce/afv-skills 1.47.0 → 1.49.0

package/skills/service-omni-presence-user-config-deploy/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: service-omni-presence-user-config-deploy
+description: "Use to deploy an Omni PresenceUserConfig (presence configuration) as one whole-record Metadata write with the decline/ACW fields set consistently: Auto-Accept off, Decline on, Decline Reason on (with a PresenceDeclineReason deployed in the same package), and an After-Conversation-Work wrap-up timer. Agents are assigned by username. Idempotent via the Metadata API files[].state signal. Triggers: create presence configuration, enable decline + decline reason + ACW wrap-up timer for agents, assign presence config to users. Do not use for ServicePresenceStatus (separate skill), for permission-set access to statuses, or to set the channel-level ACW timer on a ServiceChannel."
+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-base-settings-configure"
+    - "service-omni-channel-setup-coordinate"
+    - "service-omni-presence-status-deploy"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-presence-user-config-deploy
+
+Deploy an Omni **PresenceUserConfig** (the "presence configuration" that governs how work is offered to agents) together with the **PresenceDeclineReason** it references, in one atomic Metadata API package. The decline / auto-accept / decline-reason / ACW fields have cross-field validators — enabling Decline requires Auto-Accept off, Decline Reason requires Decline on, and the ACW timer must be paired with its max time — so they can only be set correctly as a **single whole-record write**, not field-by-field. This skill encodes that consistent record and assigns it to the given agents. It runs after `service-omni-agent-users-create` / `service-omni-presence-status-deploy` and is invoked by `service-omni-channel-setup-coordinate` as a rep-experience step.
+
+## Inputs
+
+```bash
+bash scripts/deploy-and-report.sh <org-alias> [config_developer_name] [agent_usernames_csv]
+```
+
+- `org-alias` (required).
+- `config_developer_name` (optional, default `Omni_Demo_Presence_Config`).
+- `agent_usernames_csv` (optional). Comma-separated Usernames (`…@…`) and/or 15/18-char User Ids (`005…`) to assign; Ids are resolved to usernames (metadata assigns by username). May also be set via `AGENT_USERNAMES_CSV`. Empty → the config deploys with no user assignments.
+
+Env overrides: `DECLINE_REASON_LABEL` (default `Training`), `DECLINE_REASON_DEVELOPER_NAME` (default derived from the label), `CAPACITY` (default `5`, 1–100), `ACW_SECONDS` (default `60`, 10–3600), `PRESENCE_STATUS_ON_DECLINE` (optional ServicePresenceStatus DeveloperName).
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI, Service Cloud license, `sf` CLI ≥ 2.139.6.
+- Omni-Channel base settings enabled (`service-omni-base-settings-configure`).
+- Any `PRESENCE_STATUS_ON_DECLINE` must already exist (`service-omni-presence-status-deploy`).
+- The three-way `safe_to_write` production guard applies.
+
+## Run
+
+`deploy-and-report.sh` materializes two components into a temp DX project and deploys them in one call:
+
+1. `PresenceDeclineReason:<reason>` — the decline reason (label only).
+2. `PresenceUserConfig:<config>` — capacity + label, `enableAutoAccept=false`, `enableDecline=true`, `enableDeclineReason=true`, `declineReasons=<reason>`, `hasAfterConvoWorkTimer=true`, `afterConvoWorkMaxTime=<ACW_SECONDS>`, optional `presenceStatusOnDecline`, and `assignments/users` for the resolved agents.
+
+Elements are emitted in strict XSD order. Idempotency comes from the Metadata API `files[].state` per component (`Unchanged`→reused, `Changed`→updated, `Created`→created); the deploy runs `--async` and polls to a terminal state.
+
+## Behavior
+
+**Whole-record + consistent.** The record is always emitted with the validator-safe combination, so a re-deploy is a clean no-op rather than a field diff that could trip a cross-field rule.
+
+**Non-destructive.** Only the named config and decline reason are written; other presence configs and decline reasons on the org are never touched. Assignments are declared for the resolved agents; the skill does not remove users it did not add (a redeploy declares the full assignment set for this config).
+
+## Output contract
+
+A single JSON object: `status` ∈ `created` | `updated` | `reused` | `blocked`, `config` (`{developer_name, label, capacity, acw_seconds, state}`), `decline_reason` (`{developer_name, label, state}`), `assigned_usernames`, `deploy_id`, `manual_actions`, `blocking_issue`.
+
+## Limitations
+
+- One presence configuration per invocation.
+- Encodes the decline+ACW rep profile from the steel thread; other field combinations require forking the XML template.
+- Does **not** set the channel-level After-Conversation-Work timer on a `ServiceChannel` (a separate concern), deploy `ServicePresenceStatus`, or grant status access via permission set.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | PresenceUserConfig cross-field validators, XSD element order, decline-reason packaging, and ACW field pairing |
+| `scripts/tests/_bootstrap.py` | Test bootstrap loaded by the contract suite to locate the skill root and run its shell entry point |
+| `scripts/tests/test_presence_user_config_contracts.py` | Run after changing the deployment script to verify guard, whole-record, membership, and output contracts |

package/skills/service-omni-presence-user-config-deploy/references/api-notes.md

@@ -0,0 +1,60 @@
+# API notes — service-omni-presence-user-config-deploy
+
+## Why one whole-record Metadata write
+
+`PresenceUserConfig` has **cross-field validators** that make field-by-field editing fragile — the
+correct combination only validates when the whole record is written together:
+
+- `enableAutoAccept` is allowed only when `enableDecline=false`, and vice versa. They are mutually
+  exclusive; this skill sets Auto-Accept **off** and Decline **on**.
+- `enableDeclineReason=true` is permitted only when decline reasons are enabled (Decline on) and at
+  least one `declineReasons` entry is present.
+- `presenceStatusOnDecline` is available only when `enableDecline=true`.
+- The ACW timer is paired: `hasAfterConvoWorkTimer=true` **requires** `afterConvoWorkMaxTime`
+  (10–3600 s). Optional extension uses `hasAcwExtensionEnabled` + `acwExtensionDuration` +
+  `maxExtensions` (not set by this skill).
+
+Deploying the record as a single Metadata component applies all of these atomically.
+
+## Required fields + XSD element order
+
+`capacity` and `label` are required. Metadata API enforces element order; the emitted document
+follows the schema sequence:
+
+```text
+acwExtensionDuration, afterConvoWorkMaxTime, assignments, capacity, declineReasons,
+enableAutoAccept, enableDecline, enableDeclineReason, enableDisconnectSound, enableRequestSound,
+hasAcwExtensionEnabled, hasAfterConvoWorkTimer, interruptibleCapacity, label, maxExtensions,
+presenceStatusOnDecline, presenceStatusOnPushTimeout, userDisplayName
+```
+
+This skill emits: `afterConvoWorkMaxTime → assignments → capacity → declineReasons →
+enableAutoAccept → enableDecline → enableDeclineReason → hasAfterConvoWorkTimer → label →
+[presenceStatusOnDecline]` — all ascending in the sequence above.
+
+## Decline reason packaging
+
+`declineReasons` references a `PresenceDeclineReason` by its DeveloperName (fullName). The two
+components are deployed in the **same package** so the reference resolves in one deploy; a
+standalone config referencing a not-yet-deployed reason would fail. `PresenceDeclineReason` itself
+carries only a `label`.
+
+## Assignments
+
+`assignments/users/user` takes **usernames**, not User Ids — the skill resolves any `005…` Ids to
+usernames first. A redeploy declares the full assignment set for this config; the skill does not
+remove users it did not add. The `<assignments>` block is omitted entirely when no agents are given
+(a valid, unassigned config).
+
+## Idempotency signal
+
+Per-component `files[].state` from the Metadata API is authoritative: `Unchanged` → reused,
+`Changed` → updated, `Created` → created. The deploy runs `--async` and polls
+`sf project deploy report` to a terminal state; a job that never reaches one is reported as blocked
+rather than assumed successful.
+
+## Out of scope: channel-level ACW
+
+The steel thread also mentions an After-Conversation-Work timer on the **Voice `ServiceChannel`**.
+That is a different field on a different object (the channel, not the presence config) and is not set
+here — this skill governs the agent-level presence/wrap-up behavior only.

package/skills/service-omni-presence-user-config-deploy/scripts/deploy-and-report.sh

@@ -0,0 +1,261 @@
+#!/usr/bin/env bash
+# deploy-and-report.sh - deploy a PresenceUserConfig (+ referenced PresenceDeclineReason) as one atomic Metadata package with the validator-safe decline/ACW rep profile; idempotent. Args, env, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo '{"error":"Usage: bash deploy-and-report.sh <org-alias> [config_developer_name] [agent_usernames_csv]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+CONFIG_DN="${2:-Omni_Demo_Presence_Config}"
+AGENTS_CSV="${3:-${AGENT_USERNAMES_CSV:-}}"
+
+DECLINE_REASON_LABEL="${DECLINE_REASON_LABEL:-Training}"
+DECLINE_REASON_DN="${DECLINE_REASON_DEVELOPER_NAME:-$(printf '%s' "$DECLINE_REASON_LABEL" | tr ' ' '_' | tr -cd 'A-Za-z0-9_')}"
+CAPACITY="${CAPACITY:-5}"
+ACW_SECONDS="${ACW_SECONDS:-60}"
+PRESENCE_STATUS_ON_DECLINE="${PRESENCE_STATUS_ON_DECLINE:-}"
+CONFIG_LABEL=$(printf '%s' "$CONFIG_DN" | tr '_' ' ')
+
+# ---- validation ----
+if ! [[ "$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 ! [[ "$DECLINE_REASON_DN" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
+  echo "{\"error\":\"Invalid DECLINE_REASON_DEVELOPER_NAME '$DECLINE_REASON_DN'.\"}" >&2
+  exit 1
+fi
+if ! [[ "$CAPACITY" =~ ^[0-9]+$ ]] || [ "$CAPACITY" -lt 1 ] || [ "$CAPACITY" -gt 100 ]; then
+  echo "{\"error\":\"Invalid CAPACITY '$CAPACITY' - must be an integer 1..100.\"}" >&2
+  exit 1
+fi
+if ! [[ "$ACW_SECONDS" =~ ^[0-9]+$ ]] || [ "$ACW_SECONDS" -lt 10 ] || [ "$ACW_SECONDS" -gt 3600 ]; then
+  echo "{\"error\":\"Invalid ACW_SECONDS '$ACW_SECONDS' - must be an integer 10..3600 (Metadata API bound).\"}" >&2
+  exit 1
+fi
+if [ -n "$PRESENCE_STATUS_ON_DECLINE" ] && ! [[ "$PRESENCE_STATUS_ON_DECLINE" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
+  echo "{\"error\":\"Invalid PRESENCE_STATUS_ON_DECLINE '$PRESENCE_STATUS_ON_DECLINE'.\"}" >&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
+
+# Escape the five XML predefined entities so a label/username with & < > " ' cannot break the
+# hand-built metadata XML (or inject elements) when interpolated into the heredocs below.
+xml_escape() {
+  local s="$1"
+  s="${s//&/&amp;}"; s="${s//</&lt;}"; s="${s//>/&gt;}"; s="${s//\"/&quot;}"; s="${s//\'/&apos;}"
+  printf '%s' "$s"
+}
+
+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
+  jq -n --arg msg "$msg" --arg cdn "$CONFIG_DN" --arg rdn "$DECLINE_REASON_DN" --argjson ma "$manual_actions" \
+    '{skill:"service-omni-presence-user-config-deploy",status:"blocked",
+      config:{developer_name:$cdn,state:"not_deployed"},
+      decline_reason:{developer_name:$rdn,state:"not_deployed"},
+      assigned_usernames:[],deploy_id:null,manual_actions:$ma,blocking_issue:$msg}'
+  exit 1
+}
+
+emit_plan() {
+  local detail="$1"
+  jq -n --arg detail "$detail" --arg cdn "$CONFIG_DN" \
+    '{skill:"service-omni-presence-user-config-deploy",status:"action_needed",plan_mode:true,
+      plan_detail:$detail,config:{developer_name:$cdn},manual_actions:[],blocking_issue:null}'
+  exit 0
+}
+
+# Step 1 - Organization + 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 deploy a presence configuration 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 agent usernames (accept usernames and/or 005... Ids)
+USERNAMES=()
+if [ -n "$AGENTS_CSV" ]; then
+  ID_IN=""; RAW_USERNAMES=()
+  while IFS= read -r tok; do
+    [ -z "$tok" ] && continue
+    if [[ "$tok" =~ ^005[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$ ]]; then
+      ID_IN="${ID_IN:+$ID_IN,}'$tok'"
+    elif [[ "$tok" =~ ^[^,\'\"[:space:]]+@[^,\'\"[:space:]]+$ ]]; then
+      RAW_USERNAMES+=("$tok")
+    else
+      emit_blocked "agent_usernames_csv token is neither a Username (...@...) nor a 15/18-char User Id (005...): '$tok'"
+    fi
+  done <<< "$(printf '%s' "$AGENTS_CSV" | tr ',' '\n' | sed 's/^ *//;s/ *$//')"
+
+  for u in "${RAW_USERNAMES[@]}"; do USERNAMES+=("$u"); done
+  if [ -n "$ID_IN" ]; then
+    # Fail-closed: a swallowed query failure would silently drop the Id-resolved users and deploy a
+    # config bound to fewer agents than requested. Block on both a non-zero query and an unparseable body.
+    IDU_JSON=$(sf data query --target-org "$ORG" --json \
+      --query "SELECT Username FROM User WHERE Id IN ($ID_IN) AND IsActive=true" 2>/dev/null) \
+      || emit_blocked "Could not resolve agent User Ids to usernames (query failed: authentication, network, or API access). Refusing to deploy a presence config bound to an unverified user set."
+    echo "$IDU_JSON" | jq -e '.result.records' >/dev/null 2>&1 \
+      || emit_blocked "Agent User Id resolution returned no parseable records (inconclusive). Refusing to deploy against an unverified user set."
+    while IFS= read -r u; do [ -n "$u" ] && USERNAMES+=("$u"); done \
+      < <(echo "$IDU_JSON" | jq -r '.result.records[].Username // empty')
+  fi
+fi
+
+# PLAN_ONLY - detection is read-only; report intent and stop before any write.
+if [ "${PLAN_ONLY:-}" = "1" ]; then
+  emit_plan "Would deploy PresenceDeclineReason '$DECLINE_REASON_DN' and PresenceUserConfig '$CONFIG_DN' (capacity=$CAPACITY, ACW=${ACW_SECONDS}s, decline+decline-reason on, auto-accept off) assigned to ${#USERNAMES[@]} agent(s)."
+fi
+
+# Step 3 - Materialize the two components in XSD order
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
+cp "$SCRIPT_DIR/../assets/sfdx-project.json" "$WORK/sfdx-project.json" 2>/dev/null \
+  || echo '{"packageDirectories":[{"path":"force-app","default":true}],"sourceApiVersion":"66.0"}' > "$WORK/sfdx-project.json"
+DR_DIR="$WORK/force-app/main/default/presenceDeclineReasons"
+PUC_DIR="$WORK/force-app/main/default/presenceUserConfigs"
+mkdir -p "$DR_DIR" "$PUC_DIR"
+
+# PresenceDeclineReason (label only).
+cat > "$DR_DIR/${DECLINE_REASON_DN}.presenceDeclineReason-meta.xml" <<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<PresenceDeclineReason xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>$(xml_escape "$DECLINE_REASON_LABEL")</label>
+</PresenceDeclineReason>
+XML
+
+# Build the <assignments> block only when we have usernames.
+ASSIGN_BLOCK=""
+if [ ${#USERNAMES[@]} -gt 0 ]; then
+  USER_LINES=""
+  for u in "${USERNAMES[@]}"; do USER_LINES+="            <user>$(xml_escape "$u")</user>
+"; done
+  ASSIGN_BLOCK="    <assignments>
+        <users>
+${USER_LINES}        </users>
+    </assignments>
+"
+fi
+
+# Optional presenceStatusOnDecline (emitted in XSD order, after label).
+PSOD_LINE=""
+[ -n "$PRESENCE_STATUS_ON_DECLINE" ] && PSOD_LINE="    <presenceStatusOnDecline>${PRESENCE_STATUS_ON_DECLINE}</presenceStatusOnDecline>
+"
+
+# PresenceUserConfig - elements in strict XSD order:
+# afterConvoWorkMaxTime, assignments, capacity, declineReasons, enableAutoAccept, enableDecline,
+# enableDeclineReason, hasAfterConvoWorkTimer, label, presenceStatusOnDecline.
+cat > "$PUC_DIR/${CONFIG_DN}.presenceUserConfig-meta.xml" <<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<PresenceUserConfig xmlns="http://soap.sforce.com/2006/04/metadata">
+    <afterConvoWorkMaxTime>${ACW_SECONDS}</afterConvoWorkMaxTime>
+${ASSIGN_BLOCK}    <capacity>${CAPACITY}</capacity>
+    <declineReasons>${DECLINE_REASON_DN}</declineReasons>
+    <enableAutoAccept>false</enableAutoAccept>
+    <enableDecline>true</enableDecline>
+    <enableDeclineReason>true</enableDeclineReason>
+    <hasAfterConvoWorkTimer>true</hasAfterConvoWorkTimer>
+    <label>$(xml_escape "$CONFIG_LABEL")</label>
+${PSOD_LINE}</PresenceUserConfig>
+XML
+
+# Step 4 - Deploy both components (async + poll to terminal state)
+START_JSON=$(cd "$WORK" && sf project deploy start --target-org "$ORG" \
+  --metadata "PresenceDeclineReason:${DECLINE_REASON_DN}" \
+  --metadata "PresenceUserConfig:${CONFIG_DN}" \
+  --async --json 2>/dev/null || true)
+DEPLOY_ID=$(echo "$START_JSON" | jq -r '.result.id // ""' 2>/dev/null)
+DEPLOY_JSON="$START_JSON"
+
+if [ -n "$DEPLOY_ID" ] && [ "$DEPLOY_ID" != "null" ]; then
+  POLL_STATUS=""
+  for _ in $(seq 1 60); do
+    REPORT_JSON=$(cd "$WORK" && sf project deploy report --job-id "$DEPLOY_ID" --target-org "$ORG" --json 2>/dev/null || true)
+    CUR_STATUS=$(echo "$REPORT_JSON" | jq -r '.result.status // ""' 2>/dev/null)
+    case "$CUR_STATUS" in
+      Succeeded|Failed|SucceededPartial|Canceled) DEPLOY_JSON="$REPORT_JSON"; POLL_STATUS="$CUR_STATUS"; break ;;
+    esac
+    sleep 15
+  done
+  [ -n "$POLL_STATUS" ] || emit_blocked "Presence-config deploy job $DEPLOY_ID did not reach a terminal state within the poll budget. Not reporting success."
+fi
+
+DEPLOY_SUCCESS=$(echo "$DEPLOY_JSON" | jq -r '.result.success // false' 2>/dev/null)
+DEPLOY_ID=$(echo "$DEPLOY_JSON"      | jq -r '.result.id      // ""'    2>/dev/null)
+
+if [ "$DEPLOY_SUCCESS" != "true" ]; then
+  FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.result.details.componentFailures // [] | map(.problem) | join("; ")' 2>/dev/null)
+  [ -n "$FAILURES" ] && [ "$FAILURES" != "null" ] || FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.message // .result.errorMessage // "Unknown deploy error"' 2>/dev/null)
+  # The presence-status arm must only fire when PRESENCE_STATUS_ON_DECLINE is set; as a case glob an
+  # empty value becomes `**`, which matches ANY failure and misattributes every error. Check it
+  # explicitly (literal grep -F) after the base-settings arm to preserve the original priority.
+  case "$FAILURES" in
+    *INVALID_TYPE*|*"OmniChannel"*) emit_blocked "Presence-config deploy failed ($FAILURES). Omni-Channel base settings may not be enabled." "service-omni-base-settings-configure" ;;
+    *)
+      if [ -n "$PRESENCE_STATUS_ON_DECLINE" ] && printf '%s' "$FAILURES" | grep -qF -- "$PRESENCE_STATUS_ON_DECLINE"; then
+        emit_blocked "Presence-config deploy failed: presenceStatusOnDecline '$PRESENCE_STATUS_ON_DECLINE' does not exist. Deploy it first." "service-omni-presence-status-deploy"
+      fi
+      emit_blocked "Presence-config deploy failed: $FAILURES"
+      ;;
+  esac
+fi
+
+get_state() {
+  local fn="$1"; local type="$2"
+  echo "$DEPLOY_JSON" | jq -r --arg fn "$fn" --arg t "$type" \
+    '.result.files[] | select(.fullName==$fn and .type==$t) | .state' 2>/dev/null | head -1
+}
+STATE_DR=$(get_state "$DECLINE_REASON_DN" "PresenceDeclineReason"); STATE_DR="${STATE_DR:-unknown}"
+STATE_PUC=$(get_state "$CONFIG_DN" "PresenceUserConfig");           STATE_PUC="${STATE_PUC:-unknown}"
+
+for pair in "DECLINE_REASON:$STATE_DR" "CONFIG:$STATE_PUC"; do
+  st="${pair#*:}"
+  case "$st" in
+    Created|Changed|Unchanged) ;;
+    *) emit_blocked "Deploy reported success overall but component ${pair%%:*} has an unrecognized/absent state \"$st\" (expected Created, Changed, or Unchanged). Not reporting success." ;;
+  esac
+done
+
+# Skill status: created if any Created; else updated if any Changed; else reused.
+STATUS="reused"
+if [ "$STATE_DR" = "Created" ] || [ "$STATE_PUC" = "Created" ]; then
+  STATUS="created"
+elif [ "$STATE_DR" = "Changed" ] || [ "$STATE_PUC" = "Changed" ]; then
+  STATUS="updated"
+fi
+
+ASSIGNED_JSON=$(printf '%s\n' "${USERNAMES[@]:-}" | jq -R . | jq -s 'map(select(length>0))')
+
+jq -n \
+  --arg status "$STATUS" \
+  --arg cdn "$CONFIG_DN" --arg clbl "$CONFIG_LABEL" --argjson cap "$CAPACITY" --argjson acw "$ACW_SECONDS" --arg cstate "$STATE_PUC" \
+  --arg rdn "$DECLINE_REASON_DN" --arg rlbl "$DECLINE_REASON_LABEL" --arg rstate "$STATE_DR" \
+  --argjson assigned "$ASSIGNED_JSON" \
+  --arg deploy_id "$DEPLOY_ID" \
+  '{
+    skill: "service-omni-presence-user-config-deploy",
+    status: $status,
+    config: {developer_name:$cdn, label:$clbl, capacity:$cap, acw_seconds:$acw, state:$cstate},
+    decline_reason: {developer_name:$rdn, label:$rlbl, state:$rstate},
+    assigned_usernames: $assigned,
+    deploy_id: (if $deploy_id=="" then null else $deploy_id end),
+    manual_actions: [],
+    blocking_issue: null
+  }'

package/skills/service-omni-presence-user-config-deploy/scripts/tests/_bootstrap.py

@@ -0,0 +1,106 @@
+"""Shared paths + fake-`sf` harness for the presence-user-config contract suite.
+
+Drives ``deploy-and-report.sh`` via ``subprocess`` and asserts on exit codes + emitted JSON.
+Org-free and network-free. ``jq`` comes from the real PATH.
+"""
+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-presence-user-config-deploy"
+SCRIPT = f"{SKILL_DIR}/scripts/deploy-and-report.sh"
+
+# PRODUCTION org - safe_to_write must refuse before any deploy.
+_FAKE_SF_PROD = r"""#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+case "$sub" in
+  "org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
+  "data query")
+    if printf '%s' "$args" | grep -q "FROM Organization"; then
+      echo '{"status":0,"result":{"records":[{"IsSandbox":false,"TrialExpirationDate":null,"OrganizationType":"Enterprise Edition"}]}}'
+    else
+      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+    fi
+    exit 0;;
+  "project deploy") echo '{"status":1,"result":{"success":false},"message":"FAKE_SF_DEPLOY_SHOULD_NOT_BE_REACHED"}'; exit 1;;
+  *) echo '{"status":0,"result":{}}'; exit 0;;
+esac
+"""
+
+# SANDBOX org. Tunables:
+#   FAKE_STATE_DR / FAKE_STATE_PUC → Created|Changed|Unchanged (default Created).
+#   FAKE_DEPLOY_FAIL=1 → deploy fails with an OmniChannel-shaped problem.
+#   FAKE_CONFIG_DN / FAKE_DR_DN → fullNames echoed in the report (default the script defaults).
+_FAKE_SF_SANDBOX = r"""#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+STATE_DR="${FAKE_STATE_DR:-Created}"
+STATE_PUC="${FAKE_STATE_PUC:-Created}"
+CONFIG_DN="${FAKE_CONFIG_DN:-Omni_Demo_Presence_Config}"
+DR_DN="${FAKE_DR_DN:-Training}"
+if [ -n "${FAKE_SF_CALLLOG:-}" ]; then printf '%s\n' "$args" >> "$FAKE_SF_CALLLOG"; fi
+case "$sub" in
+  "org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
+  "data query")
+    if printf '%s' "$args" | grep -q "FROM Organization"; then
+      echo '{"status":0,"result":{"records":[{"IsSandbox":true,"TrialExpirationDate":null,"OrganizationType":"Developer Edition"}]}}'
+    elif printf '%s' "$args" | grep -q "FROM User"; then
+      echo '{"status":0,"result":{"records":[{"Username":"resolved.byid@example.com"}],"totalSize":1}}'
+    else
+      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+    fi
+    exit 0;;
+  "project deploy")
+    if printf '%s' "$args" | grep -q "report"; then
+      if [ "${FAKE_DEPLOY_FAIL:-0}" = "1" ]; then
+        PROB="${FAKE_DEPLOY_PROBLEM:-INVALID_TYPE: OmniChannel not enabled}"
+        printf '{"status":0,"result":{"success":false,"id":"0AfXX0000000001","status":"Failed","details":{"componentFailures":[{"problem":"%s"}]}}}' "$PROB"
+      else
+        printf '{"status":0,"result":{"success":true,"id":"0AfXX0000000001","status":"Succeeded","files":[{"fullName":"%s","type":"PresenceDeclineReason","state":"%s"},{"fullName":"%s","type":"PresenceUserConfig","state":"%s"}]}}' "$DR_DN" "$STATE_DR" "$CONFIG_DN" "$STATE_PUC"
+      fi
+    else
+      # async start → return a job id so the script polls report.
+      echo '{"status":0,"result":{"id":"0AfXX0000000001","status":"Queued"}}'
+    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_PROD):
+        self._body = body
+        self._tmp = None
+
+    def __enter__(self):
+        self._tmp = tempfile.mkdtemp(prefix="puc-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-presence-user-config-deploy/scripts/tests/test_presence_user_config_contracts.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Contract tests for service-omni-presence-user-config-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 (  # noqa: E402
+    FakeSf,
+    _FAKE_SF_PROD,
+    _FAKE_SF_SANDBOX,
+    run,
+)
+
+
+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
+
+
+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_injection_shaped_config_name_rejected(self):
+        rc, out = run(["org", "Bad Name; DROP"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid config_developer_name", out)
+
+    def test_capacity_out_of_range_rejected(self):
+        rc, out = run(["org", "Omni_Demo_Presence_Config"], scrub_sf=True,
+                      extra_env={"CAPACITY": "0"})
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid CAPACITY", out)
+
+    def test_acw_out_of_range_rejected(self):
+        rc, out = run(["org", "Omni_Demo_Presence_Config"], scrub_sf=True,
+                      extra_env={"ACW_SECONDS": "5"})
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid ACW_SECONDS", out)
+
+
+class ProductionGuardTests(unittest.TestCase):
+    def test_refuses_production_org(self):
+        with FakeSf(_FAKE_SF_PROD) as p:
+            rc, out = run(["prodorg"], path_prefix=p)
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("production", v["blocking_issue"].lower())
+
+
+class DeployTests(unittest.TestCase):
+    def test_created_reports_states_and_assignments(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Omni_Demo_Presence_Config", "agent1@example.com,agent2@example.com"],
+                          path_prefix=p, extra_env={"FAKE_STATE_DR": "Created", "FAKE_STATE_PUC": "Created"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "created", out)
+        self.assertEqual(v["config"]["state"], "Created", out)
+        self.assertEqual(v["decline_reason"]["state"], "Created", out)
+        self.assertEqual(v["config"]["acw_seconds"], 60, out)
+        self.assertIn("agent1@example.com", v["assigned_usernames"], out)
+        self.assertIn("agent2@example.com", v["assigned_usernames"], out)
+
+    def test_reused_when_both_unchanged(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox"], path_prefix=p,
+                          extra_env={"FAKE_STATE_DR": "Unchanged", "FAKE_STATE_PUC": "Unchanged"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "reused", out)
+
+    def test_updated_when_config_changed(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox"], path_prefix=p,
+                          extra_env={"FAKE_STATE_DR": "Unchanged", "FAKE_STATE_PUC": "Changed"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "updated", out)
+
+    def test_deploy_failure_points_at_base_settings(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox"], path_prefix=p, extra_env={"FAKE_DEPLOY_FAIL": "1"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertTrue(any(a.get("target_skill") == "service-omni-base-settings-configure"
+                            for a in v["manual_actions"]), out)
+
+    def test_empty_status_on_decline_does_not_swallow_unrelated_failure(self):
+        # Regression (blocker 3): with PRESENCE_STATUS_ON_DECLINE="" the presence-status case arm was
+        # effectively `*""*`, matching EVERY failure and misreporting an unrelated deploy error as a
+        # missing presence status. An unrelated failure must now surface as the generic message.
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox"], path_prefix=p, extra_env={
+                "FAKE_DEPLOY_FAIL": "1",
+                "FAKE_DEPLOY_PROBLEM": "FIELD_CUSTOM_VALIDATION_EXCEPTION: unrelated failure",
+                "PRESENCE_STATUS_ON_DECLINE": "",
+            })
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("FIELD_CUSTOM_VALIDATION_EXCEPTION", v["blocking_issue"], out)
+        self.assertNotIn("presenceStatusOnDecline", v["blocking_issue"], out)
+        self.assertFalse(any(a.get("target_skill") == "service-omni-presence-status-deploy"
+                             for a in v.get("manual_actions", [])), out)
+
+    def test_plan_only_reports_without_deploying(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            calllog = str(Path(p) / "calls.log")
+            rc, out = run(["sandbox", "Omni_Demo_Presence_Config", "agent1@example.com"],
+                          path_prefix=p, extra_env={"PLAN_ONLY": "1", "FAKE_SF_CALLLOG": calllog})
+            log = Path(calllog).read_text() if Path(calllog).exists() else ""
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertTrue(v.get("plan_mode"), out)
+        self.assertEqual(v["status"], "action_needed", out)
+        self.assertNotIn("project deploy", log, "plan mode must not deploy")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)