Skip to content

forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-agentforce-human-escalation-configure

service-agentforce-human-escalation-configure

Unverified

Use to configure and verify Agentforce agent-to-human escalation, including human handoff, a staffed fallback queue, and failure-threshold directives. Triggers: configure agent escalation, escalate to a human agent, agent handoff to a queue, configure a human escalation queue, set an Agentforce fallback handoff. Do not use to create an agent or configure inbound channel routing; use service-agentforce-channel-configure for inbound routing.

scripts/verify-and-configure.sh

View on GitHub
#!/usr/bin/env bash
# verify-and-configure.sh - configure + verify Agentforce agent → human escalation (queue/QRC/member/flow + doc-driven canEscalate/outboundRoute verify); idempotent, PLAN_ONLY=1 previews. Inputs, ownership, exit codes: SKILL.md + references/.

set -euo pipefail

SKILL_NAME="service-agentforce-human-escalation-configure"
API_VERSION="v66.0"
# Runtime flow developer name (env-overridable); the temp deploy is written as ${FLOW_DEV_NAME}.
FLOW_DEV_NAME="${FLOW_DEVELOPER_NAME:-Human_Escalation_Outbound_Flow}"
# Human-readable Flow label; defaults to the developer name with underscores as spaces.
FLOW_LABEL="${FLOW_LABEL:-${FLOW_DEV_NAME//_/ }}"
# Work object routed to the queue (default MessagingSession; Case/VoiceCall pair with SERVICE_CHANNEL_*).
CONTEXT_OBJECT="${CONTEXT_OBJECT:-MessagingSession}"
SERVICE_CHANNEL_DEV_NAME="${SERVICE_CHANNEL_DEV_NAME:-sfdc_livemessage}"
SERVICE_CHANNEL_LABEL="${SERVICE_CHANNEL_LABEL:-Messaging}"

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Bundled flow is a tokenized template; rendered into ${FLOW_DEV_NAME}.flow-meta.xml at deploy time.
ASSET_FLOW="$SCRIPT_DIR/../assets/force-app/main/default/flows/Human_Escalation_Outbound_Flow.flow-meta.xml"

# Escape the five XML predefined entities, then sed replacement metacharacters, so a caller-supplied
# FLOW_LABEL / SERVICE_CHANNEL_LABEL with & < > " ' | cannot corrupt the rendered flow XML.
xml_escape() {
  local s="$1"
  s="${s//&/&amp;}"; s="${s//</&lt;}"; s="${s//>/&gt;}"; s="${s//\"/&quot;}"; s="${s//\'/&apos;}"
  printf '%s' "$s"
}
sed_repl_escape() { printf '%s' "$1" | sed -e 's/[\\&|]/\\&/g'; }

# Cleanup trap: remove temp working dirs on exit.
TWORK=""
_cleanup() { [ -n "$TWORK" ] && rm -rf "$TWORK" 2>/dev/null || true; }
trap _cleanup EXIT

# Args
if [ $# -lt 1 ]; then
  echo '{"error":"Usage: bash verify-and-configure.sh <org-alias> [<agent-developer-name>] [<queue-developer-name>] [<escalation-topic-api-name>] [<planner-bundle-api-name>]"}' >&2
  exit 1
fi

ORG="$1"
AGENT_DN="${2:-${AGENT_DEVELOPER_NAME:-Support_Agent}}"
QUEUE_DN="${3:-${QUEUE_DEVELOPER_NAME:-Human_Support_Queue}}"
ESCALATION_TOPIC="${4:-${ESCALATION_TOPIC_API_NAME:-}}"
PLANNER_BUNDLE="${5:-${PLANNER_BUNDLE_API_NAME:-}}"
THRESHOLD_AUTHORED="${THRESHOLD_AUTHORED:-0}"
# Consecutive failed attempts before hand-off (default 2); rendered into the directive + verdict.
DEFAULT_FAILURE_THRESHOLD="${DEFAULT_FAILURE_THRESHOLD:-2}"

# Input contract - validate BEFORE any sf call. DeveloperName grammar: leading letter, then
# letters/digits/underscore, max 80.
DN_RE='^[A-Za-z][A-Za-z0-9_]{0,79}$'
if ! [[ "$AGENT_DN" =~ $DN_RE ]]; then
  echo "{\"error\":\"Invalid agent_developer_name '$AGENT_DN'. Must start with a letter and contain only letters, digits, and underscores (max 80 chars).\"}" >&2
  exit 1
fi
if ! [[ "$QUEUE_DN" =~ $DN_RE ]]; then
  echo "{\"error\":\"Invalid queue_developer_name '$QUEUE_DN'. Must start with a letter and contain only letters, digits, and underscores (max 80 chars).\"}" >&2
  exit 1
fi
if [ -n "$ESCALATION_TOPIC" ] && ! [[ "$ESCALATION_TOPIC" =~ $DN_RE ]]; then
  echo "{\"error\":\"Invalid escalation_topic_api_name '$ESCALATION_TOPIC'. Must match the DeveloperName grammar.\"}" >&2
  exit 1
fi
if [ -n "$PLANNER_BUNDLE" ] && ! [[ "$PLANNER_BUNDLE" =~ $DN_RE ]]; then
  echo "{\"error\":\"Invalid planner_bundle_api_name '$PLANNER_BUNDLE'. Must match the DeveloperName grammar.\"}" >&2
  exit 1
fi
# CONTEXT_OBJECT is an sObject API name; validate with the same grammar (safe for SOQL/XML interpolation).
if ! [[ "$CONTEXT_OBJECT" =~ $DN_RE ]]; then
  echo "{\"error\":\"Invalid context_object '$CONTEXT_OBJECT'. Must be an sObject API name (leading letter, then letters, digits, and underscores).\"}" >&2
  exit 1
fi
if ! [[ "$FLOW_DEV_NAME" =~ $DN_RE ]]; then
  echo "{\"error\":\"Invalid flow_developer_name '$FLOW_DEV_NAME'. Must match the DeveloperName grammar.\"}" >&2
  exit 1
fi
# SERVICE_CHANNEL_DEV_NAME is substituted unescaped into the flow XML via sed; the grammar excludes
# the sed (| & \) and XML (< > & " ') metacharacters that could rewrite the deployed RoutingFlow.
if ! [[ "$SERVICE_CHANNEL_DEV_NAME" =~ $DN_RE ]]; then
  echo "{\"error\":\"Invalid service_channel_developer_name '$SERVICE_CHANNEL_DEV_NAME'. Must match the DeveloperName grammar.\"}" >&2
  exit 1
fi
# DEFAULT_FAILURE_THRESHOLD must be a small positive integer (1-99).
if ! [[ "$DEFAULT_FAILURE_THRESHOLD" =~ ^[1-9][0-9]?$ ]]; then
  echo "{\"error\":\"Invalid DEFAULT_FAILURE_THRESHOLD '$DEFAULT_FAILURE_THRESHOLD'. Must be a positive integer between 1 and 99.\"}" >&2
  exit 1
fi

# QUEUE_MEMBER_USERNAMES (optional): parse/trim/validate the full list before any sf call, so bad
# input never mutates the org first. The cleaned, comma-joined list is what the members step consumes.
UNAME_RE='^[A-Za-z0-9._%+@-]+$'
QUEUE_MEMBER_USERNAMES_CLEAN=""
if [ -n "${QUEUE_MEMBER_USERNAMES:-}" ]; then
  IFS=',' read -ra _UNAMES <<< "$QUEUE_MEMBER_USERNAMES"
  for _raw in "${_UNAMES[@]}"; do
    uname="${_raw#"${_raw%%[![:space:]]*}"}"; uname="${uname%"${uname##*[![:space:]]}"}"
    [ -z "$uname" ] && continue
    if ! [[ "$uname" =~ $UNAME_RE ]]; then
      echo "{\"error\":\"Invalid QUEUE_MEMBER_USERNAMES entry '$uname'. Usernames may contain only letters, digits, and . _ % + @ - characters.\"}" >&2
      exit 1
    fi
    if [ -z "$QUEUE_MEMBER_USERNAMES_CLEAN" ]; then
      QUEUE_MEMBER_USERNAMES_CLEAN="$uname"
    else
      QUEUE_MEMBER_USERNAMES_CLEAN="$QUEUE_MEMBER_USERNAMES_CLEAN,$uname"
    fi
  done
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

# Helpers
emit_blocked() {
  local msg="$1"; local click_path="${2:-}"
  local manual_actions='[]'
  if [ -n "$click_path" ]; then
    manual_actions=$(jq -n --arg cp "$click_path" '[{id:"MANUAL_FIX", title:"Manual fix required", click_path:$cp}]')
  fi
  jq -n \
    --arg skill "$SKILL_NAME" --arg msg "$msg" --arg agent "$AGENT_DN" --arg queue "$QUEUE_DN" \
    --argjson ma "$manual_actions" \
    '{skill:$skill, status:"BLOCKED", agent:{developer_name:$agent}, queue:{developer_name:$queue},
      manual_actions:$ma, blocking_issue:$msg}'
  exit 1
}

emit_plan() {
  local detail="$1"
  jq -n --arg skill "$SKILL_NAME" --arg detail "$detail" --arg agent "$AGENT_DN" --arg queue "$QUEUE_DN" \
    '{skill:$skill, status:"PLAN", plan_mode:true, plan_detail:$detail,
      agent:{developer_name:$agent}, queue:{developer_name:$queue}, manual_actions:[], blocking_issue:null}'
  exit 0
}

# Rollback after the agent was deactivated for authoring: try to reactivate, then block with the
# original failure AND the recovery outcome, so a failed reactivation never hides an inactive agent.
block_after_recovery() {
  local msg="$1" rec_out
  if rec_out=$(echo "Y" | sf agent activate --api-name "$AGENT_DN" --target-org "$ORG" --json 2>&1); then
    emit_blocked "$msg Recovery: agent '$AGENT_DN' was reactivated."
  else
    emit_blocked "$msg Recovery FAILED: agent '$AGENT_DN' is left INACTIVE. Raw: $(echo "$rec_out" | head -c 400)" \
      "Setup → Agentforce → Agents → '$AGENT_DN' → activate the latest version"
  fi
}

# Step 1 - Organization + safe_to_write guard
ORG_JSON=$(sf data query --target-org "$ORG" \
  --query "SELECT Id, IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" \
  --json 2>/dev/null)

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" ]; then
  SAFE_TO_WRITE=true
elif [ "$TRIAL_EXP" != "null" ]; then
  SAFE_TO_WRITE=true
elif [ "$ORG_TYPE" = "Developer Edition" ] || [ "$ORG_TYPE" = "Base Edition" ]; then
  SAFE_TO_WRITE=true
fi

if [ "$SAFE_TO_WRITE" != "true" ]; then
  emit_blocked "Refusing to configure escalation on a real production customer org (IsSandbox=$IS_SANDBOX, TrialExpirationDate=$TRIAL_EXP, OrganizationType=$ORG_TYPE). Target a sandbox, trial CDO, or Developer Edition org."
fi

# Step 2 - Precondition: agent exists AND latest version Active
BOT_JSON=$(sf data query --target-org "$ORG" \
  --query "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE DeveloperName='$AGENT_DN'" \
  --json 2>/dev/null)

TWORK=$(mktemp -d)
echo "$BOT_JSON" > "$TWORK/bot.json"
AGENT_VERDICT=$(node "$SCRIPT_DIR/classify-agent-active.mjs" "$TWORK/bot.json" "$AGENT_DN") || {
  emit_blocked "Could not read BotDefinition for '$AGENT_DN' - surface the raw sf error and retry. Raw: $BOT_JSON"
}
AGENT_READY=$(echo "$AGENT_VERDICT" | jq -r '.ready')
if [ "$AGENT_READY" != "true" ]; then
  AGENT_REASON=$(echo "$AGENT_VERDICT" | jq -r '.reason')
  emit_blocked "Agent precondition failed ($AGENT_REASON). Create and activate the agent '$AGENT_DN' before wiring escalation." \
    "Setup → Agentforce → Agents → '$AGENT_DN' → activate the latest version"
fi
AGENT_ACTIVE=true

# Step 3 - Precondition: for MessagingSession handoff, an active Enhanced Chat / MIAW MessagingChannel
# must exist. Other context objects use a different transport and aren't gated here.
if [ "$CONTEXT_OBJECT" = "MessagingSession" ]; then
  MC_JSON=$(sf data query --target-org "$ORG" \
    --query "SELECT Id, DeveloperName FROM MessagingChannel WHERE IsActive=true LIMIT 1" \
    --json 2>/dev/null)
  MC_COUNT=$(echo "$MC_JSON" | jq -r '.result.totalSize // 0' 2>/dev/null || echo "0")
  if [ "$MC_COUNT" -eq 0 ]; then
    emit_blocked "No active MessagingChannel (Enhanced Chat / MIAW) found. Provision the messaging channel first, then re-run." \
      "Setup → Messaging Settings → New Channel (Messaging for In-App and Web)"
  fi
fi

# Step 3b - Preflight: determine which Agentforce authoring model the org exposes. classic =
# GenAiPlugin + GenAiPlannerBundle (canEscalate + outboundRouteConfigs surfaces). nga = AiAuthoringBundle
# (Agent Script; escalation via @utils.escalate/create-record, routed through channel Omni to the queue).
# none = neither -> fail closed. Model rationale: references/nga-escalation.md.
MDT_JSON=$(sf org list metadata-types --target-org "$ORG" --json 2>/dev/null || echo '{}')
HAS_PLUGIN=$(echo "$MDT_JSON" | jq -r '[.result.metadataObjects[]?.xmlName] | index("GenAiPlugin") // empty' 2>/dev/null || echo "")
HAS_BUNDLE=$(echo "$MDT_JSON" | jq -r '[.result.metadataObjects[]?.xmlName] | index("GenAiPlannerBundle") // empty' 2>/dev/null || echo "")
HAS_AIAUTHORING=$(echo "$MDT_JSON" | jq -r '[.result.metadataObjects[]?.xmlName] | index("AiAuthoringBundle") // empty' 2>/dev/null || echo "")

AUTHORING_MODEL="none"
HAS_CLASSIC_SURFACE=false
HAS_NGA_SURFACE=false
[ -n "$HAS_BUNDLE" ] && [ -n "$HAS_PLUGIN" ] && HAS_CLASSIC_SURFACE=true
[ -n "$HAS_AIAUTHORING" ] && HAS_NGA_SURFACE=true

# When an org exposes both authoring generations, classify the selected target rather
# than defaulting the whole org to classic. A target-specific retrieve is read-only and
# prevents an NGA agent from being verified against unrelated classic metadata.
TARGET_CLASSIC=false
TARGET_NGA=false
if [ "$HAS_NGA_SURFACE" = "true" ]; then
  MODEL_DIR="$TWORK/model-nga"
  mkdir -p "$MODEL_DIR"
  if sf project retrieve start --target-org "$ORG" --metadata "AiAuthoringBundle:$AGENT_DN" \
      --target-metadata-dir "$MODEL_DIR" --unzip --json >/dev/null 2>&1 \
     && find "$MODEL_DIR" -type f -print -quit | grep -q .; then
    TARGET_NGA=true
  fi
fi
if [ "$HAS_CLASSIC_SURFACE" = "true" ]; then
  MODEL_DIR="$TWORK/model-classic"
  mkdir -p "$MODEL_DIR"
  CLASSIC_TARGET="${PLANNER_BUNDLE:-$AGENT_DN}"
  if sf project retrieve start --target-org "$ORG" --metadata "GenAiPlannerBundle:$CLASSIC_TARGET" \
      --target-metadata-dir "$MODEL_DIR" --unzip --json >/dev/null 2>&1 \
     && find "$MODEL_DIR" -type f -print -quit | grep -q .; then
    TARGET_CLASSIC=true
  fi
fi

if [ "$TARGET_NGA" = "true" ] && [ "$TARGET_CLASSIC" != "true" ]; then
  AUTHORING_MODEL="nga"
elif [ "$TARGET_CLASSIC" = "true" ] && [ "$TARGET_NGA" != "true" ]; then
  AUTHORING_MODEL="classic"
elif [ "$TARGET_CLASSIC" = "true" ] && [ "$TARGET_NGA" = "true" ]; then
  if [ -z "${AUTHORING_MODEL_OVERRIDE:-}" ]; then
    emit_blocked "The selected agent resolves in both classic and next-gen Agentforce authoring metadata. Set AUTHORING_MODEL_OVERRIDE=classic or nga after confirming the intended target model."
  fi
elif [ "$HAS_CLASSIC_SURFACE" = "true" ] && [ "$HAS_NGA_SURFACE" != "true" ]; then
  AUTHORING_MODEL="classic"
elif [ "$HAS_NGA_SURFACE" = "true" ] && [ "$HAS_CLASSIC_SURFACE" != "true" ]; then
  AUTHORING_MODEL="nga"
elif [ "$HAS_CLASSIC_SURFACE" = "true" ] && [ "$HAS_NGA_SURFACE" = "true" ]; then
  if [ -z "${AUTHORING_MODEL_OVERRIDE:-}" ]; then
    emit_blocked "This org exposes both Agentforce authoring models, but the selected target could not be classified. Set AUTHORING_MODEL_OVERRIDE=classic or nga after confirming the target metadata."
  fi
fi
# AUTHORING_MODEL_OVERRIDE (classic|nga) lets a caller pin the branch when both surfaces coexist.
case "${AUTHORING_MODEL_OVERRIDE:-}" in
  classic) [ "$HAS_CLASSIC_SURFACE" = "true" ] && AUTHORING_MODEL="classic" ;;
  nga)     [ "$HAS_NGA_SURFACE" = "true" ] && AUTHORING_MODEL="nga" ;;
esac

if [ "$AUTHORING_MODEL" = "none" ]; then
  emit_blocked "This org exposes neither the classic Agentforce authoring metadata (GenAiPlugin + GenAiPlannerBundle) nor the next-gen AiAuthoringBundle, so no agent escalation surface can be authored or verified here. Enable Agentforce, then re-run. To provision only the deterministic routing infrastructure (queue, members, QueueRoutingConfig, outbound RoutingFlow) on this org, use the service-omni-* leaf skills directly." \
    "Setup → Einstein / Agentforce → enable Agentforce so the authoring metadata (GenAiPlannerBundle or AiAuthoringBundle) is exposed"
fi

# Step 4 - Create-or-adopt the human queue (+ QueueSobject for the context object)
Q_JSON=$(sf data query --target-org "$ORG" \
  --query "SELECT Id FROM Group WHERE DeveloperName='$QUEUE_DN' AND Type='Queue'" \
  --json 2>/dev/null)
QUEUE_ID=$(echo "$Q_JSON" | jq -r '.result.records[0].Id // ""')

if [ "${PLAN_ONLY:-}" = "1" ]; then
  if [ -n "$QUEUE_ID" ]; then
    emit_plan "Agent '$AGENT_DN' active; queue '$QUEUE_DN' exists. Would ensure the $CONTEXT_OBJECT QueueSobject and at least one active direct-user member (adding from QUEUE_MEMBER_USERNAMES if empty); ONLY if the queue has an eligible member would it then create/adopt+bind the QueueRoutingConfig and deploy outbound flow '$FLOW_DEV_NAME'; finally round-trip escalation config."
  else
    emit_plan "Agent '$AGENT_DN' active; queue '$QUEUE_DN' missing. Would create the queue ($CONTEXT_OBJECT QueueSobject) and ensure at least one active direct-user member (adding from QUEUE_MEMBER_USERNAMES if empty); ONLY if the queue has an eligible member would it then create+bind the QueueRoutingConfig and deploy outbound flow '$FLOW_DEV_NAME'; finally round-trip escalation config."
  fi
fi

if [ -z "$QUEUE_ID" ]; then
  # Create the queue + context-object QueueSobject via Metadata API.
  TQ="$TWORK/queue/force-app/main/default/queues"
  mkdir -p "$TQ"
  cat > "$TWORK/queue/sfdx-project.json" <<'JSON'
{ "packageDirectories": [{ "path": "force-app", "default": true }], "namespace": "", "sourceApiVersion": "67.0" }
JSON
  # Queue XSD order: doesSendEmailToMembers, name, queueSobject (Metadata API rejects other orders).
  cat > "$TQ/${QUEUE_DN}.queue-meta.xml" <<XML
<?xml version="1.0" encoding="UTF-8"?>
<Queue xmlns="http://soap.sforce.com/2006/04/metadata">
    <doesSendEmailToMembers>false</doesSendEmailToMembers>
    <name>${QUEUE_DN}</name>
    <queueSobject>
        <sobjectType>${CONTEXT_OBJECT}</sobjectType>
    </queueSobject>
</Queue>
XML
  if ! DEPLOY_OUT=$(sf project deploy start --target-org "$ORG" --source-dir "$TWORK/queue/force-app" --json 2>/dev/null); then
    emit_blocked "Failed to create queue '$QUEUE_DN'. Raw: $(echo "$DEPLOY_OUT" | head -c 600)"
  fi
  Q_JSON=$(sf data query --target-org "$ORG" \
    --query "SELECT Id FROM Group WHERE DeveloperName='$QUEUE_DN' AND Type='Queue'" --json 2>/dev/null)
  QUEUE_ID=$(echo "$Q_JSON" | jq -r '.result.records[0].Id // ""')
  [ -z "$QUEUE_ID" ] && emit_blocked "Queue '$QUEUE_DN' not found after create attempt."
fi

# Ensure the context-object QueueSobject exists; an adopted queue may lack it - bind additively via Data API.
QS_JSON=$(sf data query --target-org "$ORG" \
  --query "SELECT Id FROM QueueSobject WHERE QueueId='$QUEUE_ID' AND SobjectType='$CONTEXT_OBJECT'" \
  --json 2>/dev/null)
QUEUE_SOBJECT_PRESENT=false
[ "$(echo "$QS_JSON" | jq -r '.result.totalSize // 0')" -gt 0 ] && QUEUE_SOBJECT_PRESENT=true

if [ "$QUEUE_SOBJECT_PRESENT" != "true" ]; then
  QS_STDERR="$(mktemp)"
  QS_POST=$(sf api request rest --target-org "$ORG" \
    "/services/data/$API_VERSION/sobjects/QueueSobject" \
    --method POST \
    --body "$(jq -n --arg q "$QUEUE_ID" --arg so "$CONTEXT_OBJECT" '{QueueId:$q, SobjectType:$so}')" 2>"$QS_STDERR" || true)
  rm -f "$QS_STDERR"
  if [ "$(echo "$QS_POST" | jq -r '.success // false' 2>/dev/null)" = "true" ]; then
    QUEUE_SOBJECT_PRESENT=true
  else
    QS_ERR=$(echo "$QS_POST" | jq -r '.[0].message // .message // "unknown error"' 2>/dev/null)
    emit_blocked "Queue '$QUEUE_DN' exists but is not bound to $CONTEXT_OBJECT, and the QueueSobject bind failed: $QS_ERR" \
      "Setup → Queues → '$QUEUE_DN' → Supported Objects → add the context object → Save"
  fi
fi

# Step 4b - Ensure the queue has >=1 active direct-user member (Id prefix 005); an empty queue can't
# receive escalations, so routing (Steps 5/6) is refused without one. Necessary but not sufficient for
# routability (Omni perms/presence proven only at runtime) - hence the honest evidence key
# queueHasActiveDirectUserMember. Members come from the pre-validated QUEUE_MEMBER_USERNAMES_CLEAN list.
count_active_user_members() {
  local gm ids uq
  gm=$(sf data query --target-org "$ORG" \
    --query "SELECT UserOrGroupId FROM GroupMember WHERE GroupId='$QUEUE_ID'" --json 2>/dev/null)
  # Only direct User members (Id prefix 005) can be resolved to IsActive deterministically.
  ids=$(echo "$gm" | jq -r '[.result.records[]?.UserOrGroupId | select(type=="string" and startswith("005"))] | join("\u0027,\u0027")' 2>/dev/null || echo "")
  if [ -z "$ids" ]; then echo 0; return; fi
  uq=$(sf data query --target-org "$ORG" \
    --query "SELECT COUNT(Id) c FROM User WHERE IsActive=true AND Id IN ('$ids')" --json 2>/dev/null)
  echo "$uq" | jq -r '.result.records[0].c // (.result.totalSize // 0)' 2>/dev/null || echo 0
}

MEMBER_COUNT=$(count_active_user_members)
[ -z "$MEMBER_COUNT" ] && MEMBER_COUNT=0

if [ "$MEMBER_COUNT" -eq 0 ] && [ -n "$QUEUE_MEMBER_USERNAMES_CLEAN" ]; then
  IFS=',' read -ra _UNAMES <<< "$QUEUE_MEMBER_USERNAMES_CLEAN"
  for uname in "${_UNAMES[@]}"; do
    [ -z "$uname" ] && continue
    U_JSON=$(sf data query --target-org "$ORG" \
      --query "SELECT Id FROM User WHERE Username='$uname' AND IsActive=true LIMIT 1" --json 2>/dev/null)
    U_ID=$(echo "$U_JSON" | jq -r '.result.records[0].Id // ""')
    if [ -z "$U_ID" ]; then
      emit_blocked "QUEUE_MEMBER_USERNAMES user '$uname' was not found as an active User on '$ORG'. Create or reactivate the user, or correct the username, then rerun."
    fi
    GM_STDERR="$(mktemp)"
    GM_POST=$(sf api request rest --target-org "$ORG" \
      "/services/data/$API_VERSION/sobjects/GroupMember" \
      --method POST \
      --body "$(jq -n --arg g "$QUEUE_ID" --arg u "$U_ID" '{GroupId:$g, UserOrGroupId:$u}')" 2>"$GM_STDERR" || true)
    rm -f "$GM_STDERR"
    if [ "$(echo "$GM_POST" | jq -r '.success // false' 2>/dev/null)" != "true" ]; then
      # A duplicate membership (already a member) is benign; anything else is fatal.
      if ! echo "$GM_POST" | jq -e '((.[0].errorCode // "") | test("DUPLICATE"))' >/dev/null 2>&1; then
        GM_ERR=$(echo "$GM_POST" | jq -r '.[0].message // .message // "unknown error"' 2>/dev/null)
        emit_blocked "Failed to add '$uname' to queue '$QUEUE_DN' as a member: $GM_ERR"
      fi
    fi
  done
  MEMBER_COUNT=$(count_active_user_members)
  [ -z "$MEMBER_COUNT" ] && MEMBER_COUNT=0
fi

QUEUE_HAS_ACTIVE_DIRECT_USER_MEMBER=false
[ "$MEMBER_COUNT" -gt 0 ] && QUEUE_HAS_ACTIVE_DIRECT_USER_MEMBER=true

# Membership gate: Steps 5 (QRC bind) + 6 (Flow) run only with an eligible member; else left
# unconfigured and the verdict is INCOMPLETE (never a flow routing to nobody).
QUEUE_ROUTING_CONFIG_PRESENT=false
QUEUE_ROUTING_CONFIG_BOUND=false
RC_ID=""
FLOW_ACTIVE_ID=""
if [ "$QUEUE_HAS_ACTIVE_DIRECT_USER_MEMBER" = "true" ]; then

# Step 5 - Ensure a QueueRoutingConfig, then bind it to the queue (Group.QueueRoutingConfigId)
RC_DN="${QUEUE_DN}_RC"
RC_JSON=$(sf data query --target-org "$ORG" \
  --query "SELECT Id FROM QueueRoutingConfig WHERE DeveloperName='$RC_DN'" --json 2>/dev/null)
RC_ID=$(echo "$RC_JSON" | jq -r '.result.records[0].Id // ""')

if [ -z "$RC_ID" ]; then
  # Create QRC via Data API. RoutingPriority is required (REQUIRED_FIELD_MISSING if omitted).
  RC_STDERR="$(mktemp)"
  RC_POST=$(sf api request rest --target-org "$ORG" \
    "/services/data/$API_VERSION/sobjects/QueueRoutingConfig" \
    --method POST \
    --body "$(jq -n --arg dn "$RC_DN" --arg ml "${QUEUE_DN} Routing Config" \
              '{DeveloperName:$dn, MasterLabel:$ml, RoutingModel:"MostAvailable", CapacityWeight:5, RoutingPriority:1, IsAttributeBased:false}')" 2>"$RC_STDERR" || true)
  rm -f "$RC_STDERR"
  if [ "$(echo "$RC_POST" | jq -r '.success // false' 2>/dev/null)" = "true" ]; then
    RC_ID=$(echo "$RC_POST" | jq -r '.id')
  else
    if echo "$RC_POST" | jq -e '(.name // "") == "INVALID_TYPE" or ((.[0].errorCode // "") == "INVALID_TYPE")' >/dev/null 2>&1; then
      emit_blocked "QueueRoutingConfig is not available because Omni-Channel is not enabled on this org. Enable Omni-Channel in Setup, then rerun."
    fi
    RC_ERR=$(echo "$RC_POST" | jq -r '.[0].message // .message // "unknown error"' 2>/dev/null)
    emit_blocked "Failed to create QueueRoutingConfig '$RC_DN': $RC_ERR"
  fi
fi
QUEUE_ROUTING_CONFIG_PRESENT=false
[ -n "$RC_ID" ] && QUEUE_ROUTING_CONFIG_PRESENT=true

# Bind the QRC to the queue (Group.QueueRoutingConfigId) if not already linked.
QUEUE_ROUTING_CONFIG_BOUND=false
if [ -n "$RC_ID" ]; then
  G_JSON=$(sf data query --target-org "$ORG" \
    --query "SELECT Id, QueueRoutingConfigId FROM Group WHERE Id='$QUEUE_ID'" --json 2>/dev/null)
  CUR_RC=$(echo "$G_JSON" | jq -r '.result.records[0].QueueRoutingConfigId // ""')
  if [ "$CUR_RC" = "$RC_ID" ]; then
    QUEUE_ROUTING_CONFIG_BOUND=true
  else
    G_STDERR="$(mktemp)"
    sf api request rest --target-org "$ORG" \
      "/services/data/$API_VERSION/sobjects/Group/$QUEUE_ID" \
      --method PATCH \
      --body "$(jq -n --arg rc "$RC_ID" '{QueueRoutingConfigId:$rc}')" >/dev/null 2>"$G_STDERR" || true
    G_ERR=$(head -c 400 "$G_STDERR" 2>/dev/null || true)
    rm -f "$G_STDERR"
    # PATCH returns 204 (empty body) on success - re-query to CONFIRM the binding persisted.
    G_JSON=$(sf data query --target-org "$ORG" \
      --query "SELECT Id, QueueRoutingConfigId FROM Group WHERE Id='$QUEUE_ID'" --json 2>/dev/null)
    [ "$(echo "$G_JSON" | jq -r '.result.records[0].QueueRoutingConfigId // ""')" = "$RC_ID" ] && QUEUE_ROUTING_CONFIG_BOUND=true
    if [ "$QUEUE_ROUTING_CONFIG_BOUND" != "true" ]; then
      emit_blocked "Created/adopted QueueRoutingConfig '$RC_DN' but failed to bind it to queue '$QUEUE_DN' (Group.QueueRoutingConfigId did not persist).${G_ERR:+ Raw: $G_ERR}"
    fi
  fi
fi

# Step 6 - Deploy the bundled outbound QueueBased RoutingFlow (tokens substituted)
FLOW_JSON=$(sf data query --target-org "$ORG" \
  --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='$FLOW_DEV_NAME' AND ProcessType='RoutingFlow'" \
  --json 2>/dev/null)
FLOW_ACTIVE_ID=$(echo "$FLOW_JSON" | jq -r '.result.records[0].ActiveVersionId // ""')

if [ -z "$FLOW_ACTIVE_ID" ]; then
  [ -f "$ASSET_FLOW" ] || emit_blocked "Bundled outbound flow asset not found at $ASSET_FLOW"
  TF="$TWORK/flow/force-app/main/default/flows"
  mkdir -p "$TF"
  cat > "$TWORK/flow/sfdx-project.json" <<'JSON'
{ "packageDirectories": [{ "path": "force-app", "default": true }], "namespace": "", "sourceApiVersion": "67.0" }
JSON
  SC_LABEL_SED="$(sed_repl_escape "$(xml_escape "$SERVICE_CHANNEL_LABEL")")"
  FLOW_LABEL_SED="$(sed_repl_escape "$(xml_escape "$FLOW_LABEL")")"
  sed -e "s|__QUEUE_DEVELOPER_NAME__|${QUEUE_DN}|g" \
      -e "s|__SERVICE_CHANNEL_DEV_NAME__|${SERVICE_CHANNEL_DEV_NAME}|g" \
      -e "s|__SERVICE_CHANNEL_LABEL__|${SC_LABEL_SED}|g" \
      -e "s|__FLOW_DEVELOPER_NAME__|${FLOW_DEV_NAME}|g" \
      -e "s|__FLOW_LABEL__|${FLOW_LABEL_SED}|g" \
      "$ASSET_FLOW" > "$TF/${FLOW_DEV_NAME}.flow-meta.xml"
  # Deploy from inside the temp project so sf uses its sourceApiVersion (67.0), not an ancestor's.
  if ! DEPLOY_OUT=$(cd "$TWORK/flow" && sf project deploy start --target-org "$ORG" --source-dir force-app --json 2>/dev/null); then
    emit_blocked "Failed to deploy outbound flow '$FLOW_DEV_NAME'. Raw: $(echo "$DEPLOY_OUT" | head -c 600)"
  fi
  FLOW_JSON=$(sf data query --target-org "$ORG" \
    --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='$FLOW_DEV_NAME' AND ProcessType='RoutingFlow'" \
    --json 2>/dev/null)
  FLOW_ACTIVE_ID=$(echo "$FLOW_JSON" | jq -r '.result.records[0].ActiveVersionId // ""')
fi

fi  # end membership gate - QRC bind + Flow activation skipped when the queue has no eligible member

# Step 6b - Optional deterministic authoring of the doc-driven surfaces (AUTHOR_SURFACES=1). Default is
# verify-only; with the topic/bundle names supplied this authors canEscalate + outboundRouteConfigs
# (retrieve → patch → deploy → reactivate). Runs only after the membership gate. See references/.
if [ "${AUTHOR_SURFACES:-0}" = "1" ] && [ "$QUEUE_HAS_ACTIVE_DIRECT_USER_MEMBER" = "true" ] && [ "$AUTHORING_MODEL" = "classic" ]; then
  if [ -z "$ESCALATION_TOPIC" ] && [ -z "$PLANNER_BUNDLE" ]; then
    emit_blocked "AUTHOR_SURFACES=1 requires escalation_topic_api_name and/or planner_bundle_api_name so the skill knows which topic/bundle to author. Re-run with those identifiers or omit AUTHOR_SURFACES."
  fi

  # Authoring lifecycle: publish → retrieve (metadata --unzip) → deactivate → XSD-ordered patch →
  # deploy (--metadata-dir) → activate (fail closed) → re-read latest BotVersion. See references/classifier-contracts.md.

  # 1) Publish so the compiled planner bundle exists/refreshed.
  if ! sf agent publish authoring-bundle --api-name "$AGENT_DN" --target-org "$ORG" --json >/dev/null 2>&1; then
    emit_blocked "AUTHOR_SURFACES: 'sf agent publish authoring-bundle' failed for '$AGENT_DN'; cannot author escalation surfaces."
  fi

  # 2) Retrieve in metadata format + --unzip (else --target-metadata-dir yields a ZIP); find the XML + package.xml root.
  APLUGIN=""; ABUNDLE=""; AROOT_PLUGIN=""; AROOT_BUNDLE=""
  if [ -n "$ESCALATION_TOPIC" ]; then
    ARET="$TWORK/author-plugin"; mkdir -p "$ARET"
    if ! sf project retrieve start --target-org "$ORG" --metadata "GenAiPlugin:$ESCALATION_TOPIC" \
         --target-metadata-dir "$ARET" --unzip >/dev/null 2>&1; then
      emit_blocked "AUTHOR_SURFACES: failed to retrieve GenAiPlugin '$ESCALATION_TOPIC' (metadata format)."
    fi
    APLUGIN=$(find "$ARET" -type f \( -name '*.genAiPlugin' -o -name '*.genAiPlugin-meta.xml' \) 2>/dev/null | head -1)
    AROOT_PLUGIN=$(dirname "$(find "$ARET" -type f -name package.xml 2>/dev/null | head -1)" 2>/dev/null || echo "")
    if [ -z "$APLUGIN" ] || [ -z "$AROOT_PLUGIN" ] || [ ! -d "$AROOT_PLUGIN" ]; then
      emit_blocked "AUTHOR_SURFACES: retrieved GenAiPlugin '$ESCALATION_TOPIC' but found no metadata-format file/package.xml to patch."
    fi
  fi
  if [ -n "$PLANNER_BUNDLE" ]; then
    ARETB="$TWORK/author-bundle"; mkdir -p "$ARETB"
    if ! sf project retrieve start --target-org "$ORG" --metadata "GenAiPlannerBundle:$PLANNER_BUNDLE" \
         --target-metadata-dir "$ARETB" --unzip >/dev/null 2>&1; then
      emit_blocked "AUTHOR_SURFACES: failed to retrieve GenAiPlannerBundle '$PLANNER_BUNDLE' (metadata format)."
    fi
    ABUNDLE=$(find "$ARETB" -type f \( -name '*.genAiPlannerBundle' -o -name '*.genAiPlannerBundle-meta.xml' \) 2>/dev/null | head -1)
    AROOT_BUNDLE=$(dirname "$(find "$ARETB" -type f -name package.xml 2>/dev/null | head -1)" 2>/dev/null || echo "")
    if [ -z "$ABUNDLE" ] || [ -z "$AROOT_BUNDLE" ] || [ ! -d "$AROOT_BUNDLE" ]; then
      emit_blocked "AUTHOR_SURFACES: retrieved GenAiPlannerBundle '$PLANNER_BUNDLE' but found no metadata-format file/package.xml to patch."
    fi
  fi

  # 3) Deactivate (deploys fail while active).
  if ! { echo "Y" | sf agent deactivate --api-name "$AGENT_DN" --target-org "$ORG" --json >/dev/null 2>&1; }; then
    emit_blocked "AUTHOR_SURFACES: 'sf agent deactivate' failed for '$AGENT_DN'; refusing to deploy while the agent is active."
  fi
  AGENT_ACTIVE=false

  # 4) Patch (XSD-ordered) + deploy (--metadata-dir); on failure, reactivate and report both outcomes.
  if [ -n "$APLUGIN" ]; then
    if ! node "$SCRIPT_DIR/patch-escalation-surfaces.mjs" canEscalate "$APLUGIN" >/dev/null 2>&1; then
      block_after_recovery "AUTHOR_SURFACES: could not safely set canEscalate=true on GenAiPlugin '$ESCALATION_TOPIC' (no safe XSD-ordered insertion point)."
    fi
    if ! DEPLOY_OUT=$(sf project deploy start --target-org "$ORG" --metadata-dir "$AROOT_PLUGIN" --json 2>/dev/null); then
      block_after_recovery "AUTHOR_SURFACES: failed to deploy canEscalate patch for '$ESCALATION_TOPIC'. Raw: $(echo "$DEPLOY_OUT" | head -c 400)"
    fi
  fi
  if [ -n "$ABUNDLE" ]; then
    if ! node "$SCRIPT_DIR/patch-escalation-surfaces.mjs" outboundRoute "$ABUNDLE" "$FLOW_DEV_NAME" >/dev/null 2>&1; then
      block_after_recovery "AUTHOR_SURFACES: could not safely wire outboundRouteConfigs on a Messaging surface of '$PLANNER_BUNDLE' (no Messaging-class planner surface / <surface> anchor found)."
    fi
    if ! DEPLOY_OUT=$(sf project deploy start --target-org "$ORG" --metadata-dir "$AROOT_BUNDLE" --json 2>/dev/null); then
      block_after_recovery "AUTHOR_SURFACES: failed to deploy outboundRouteConfigs patch for '$PLANNER_BUNDLE'. Raw: $(echo "$DEPLOY_OUT" | head -c 400)"
    fi
  fi

  # 5) Reactivate - FAIL CLOSED (never swallow with || true; an inactive agent cannot serve).
  if ! { echo "Y" | sf agent activate --api-name "$AGENT_DN" --target-org "$ORG" --json >/dev/null 2>&1; }; then
    emit_blocked "AUTHOR_SURFACES: 'sf agent activate' failed for '$AGENT_DN' after deploying the escalation surfaces; the agent is left INACTIVE." \
      "Setup → Agentforce → Agents → '$AGENT_DN' → activate the latest version"
  fi

  # 6) Re-verify the LATEST BotVersion is Active (never trust the pre-authoring AGENT_ACTIVE value).
  BOT_JSON_AFTER=$(sf data query --target-org "$ORG" \
    --query "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE DeveloperName='$AGENT_DN'" \
    --json 2>/dev/null)
  echo "$BOT_JSON_AFTER" > "$TWORK/bot-after.json"
  AGENT_VERDICT_AFTER=$(node "$SCRIPT_DIR/classify-agent-active.mjs" "$TWORK/bot-after.json" "$AGENT_DN" 2>/dev/null || echo '{"ready":false}')
  if [ "$(echo "$AGENT_VERDICT_AFTER" | jq -r '.ready')" = "true" ]; then
    AGENT_ACTIVE=true
  else
    AGENT_ACTIVE=false
    emit_blocked "AUTHOR_SURFACES: after authoring + reactivation the latest BotVersion for '$AGENT_DN' is not Active; refusing to report CONFIGURED against a stale/inactive version." \
      "Setup → Agentforce → Agents → '$AGENT_DN' → activate the latest version"
  fi
fi

# Step 7 - Verify doc-driven surfaces when their identifiers were provided
CAN_ESCALATE=false
if [ -n "$ESCALATION_TOPIC" ]; then
  RET="$TWORK/plugin"
  mkdir -p "$RET"
  # --unzip: without it --target-metadata-dir yields a ZIP and the grep below scans binary, so a
  # correctly configured topic is misreported as incomplete (mirrors the authoring path at Step 6).
  if sf project retrieve start --target-org "$ORG" --metadata "GenAiPlugin:$ESCALATION_TOPIC" \
       --target-metadata-dir "$RET" --unzip >/dev/null 2>&1; then
    if grep -Rql "<canEscalate>true</canEscalate>" "$RET" 2>/dev/null; then
      CAN_ESCALATE=true
    fi
  fi
fi

OUTBOUND_ROUTE_NAME=""
OUTBOUND_ROUTE_TYPE=""
OUTBOUND_ROUTE_SURFACE=""
OUTBOUND_ROUTE_SAME_BLOCK=false
OUTBOUND_ROUTE_MESSAGING_SURFACE=false
if [ -n "$PLANNER_BUNDLE" ]; then
  RETB="$TWORK/bundle"
  mkdir -p "$RETB"
  # --unzip: else --target-metadata-dir yields a ZIP and the find/cat below reads binary, so a wired
  # outbound route is misreported as missing.
  if sf project retrieve start --target-org "$ORG" --metadata "GenAiPlannerBundle:$PLANNER_BUNDLE" \
       --target-metadata-dir "$RETB" --unzip >/dev/null 2>&1; then
    # Couple outboundRouteName + outboundRouteType within the same planner-surface block.
    BUNDLE_CAT="$TWORK/bundle-cat.xml"
    find "$RETB" -type f -name '*.xml' -exec cat {} \; > "$BUNDLE_CAT" 2>/dev/null || true
    ROUTE_JSON=$(node "$SCRIPT_DIR/extract-outbound-route.mjs" "$BUNDLE_CAT" "$FLOW_DEV_NAME" 2>/dev/null || echo '{}')
    OUTBOUND_ROUTE_NAME=$(echo "$ROUTE_JSON" | jq -r '.name // ""')
    OUTBOUND_ROUTE_TYPE=$(echo "$ROUTE_JSON" | jq -r '.type // ""')
    OUTBOUND_ROUTE_SURFACE=$(echo "$ROUTE_JSON" | jq -r '.surface // ""')
    OUTBOUND_ROUTE_SAME_BLOCK=$(echo "$ROUTE_JSON" | jq -r '.sameBlock // false')
    OUTBOUND_ROUTE_MESSAGING_SURFACE=$(echo "$ROUTE_JSON" | jq -r '.messagingSurface // false')
  fi
fi

# Step 7b (NGA) - Verify the next-gen escalation surface by retrieving the agent's AiAuthoringBundle and
# scanning its Agent Script: a Service agent needs a reachable @utils.escalate (with connection messaging);
# an Employee agent (no messaging) needs a create-record action. Authoring the surface itself is delegated
# to agentforce-generate (see next_steps); this skill verifies + reports. Details: references/nga-escalation.md.
NGA_SURFACE_PRESENT=false
NGA_AGENT_TYPE="unknown"
if [ "$AUTHORING_MODEL" = "nga" ]; then
  NRET="$TWORK/nga-bundle"
  mkdir -p "$NRET"
  # --unzip: else --target-metadata-dir yields a ZIP and the NGA classifier scans binary, so a present
  # escalation surface is misreported as missing.
  if sf project retrieve start --target-org "$ORG" --metadata "AiAuthoringBundle:$AGENT_DN" \
       --target-metadata-dir "$NRET" --unzip >/dev/null 2>&1; then
    NGA_JSON=$(node "$SCRIPT_DIR/classify-nga-escalation.mjs" "$NRET" 2>/dev/null || echo '{}')
    NGA_SURFACE_PRESENT=$(echo "$NGA_JSON" | jq -r '.escalationSurfacePresent // false')
    NGA_AGENT_TYPE=$(echo "$NGA_JSON" | jq -r '.agentType // "unknown"')
  fi
fi

THRESHOLD_FLAG=false
[ "$THRESHOLD_AUTHORED" = "1" ] && THRESHOLD_FLAG=true

# Render the numeric threshold into the directive template (echoed in the verdict as evidence).
THRESHOLD_TEMPLATE="$SCRIPT_DIR/../assets/escalation-thresholds.instructions.md"
DIRECTIVE_RENDERED=false
if [ -f "$THRESHOLD_TEMPLATE" ]; then
  RENDERED_DIRECTIVE="$TWORK/escalation-thresholds.rendered.md"
  sed "s/__DEFAULT_FAILURES__/${DEFAULT_FAILURE_THRESHOLD}/g" "$THRESHOLD_TEMPLATE" > "$RENDERED_DIRECTIVE" 2>/dev/null \
    && DIRECTIVE_RENDERED=true
fi

# Step 8 - Assemble evidence + render the deterministic verdict
EVID="$TWORK/evidence.json"
jq -n \
  --argjson canEscalate "$CAN_ESCALATE" \
  --arg outboundRouteName "$OUTBOUND_ROUTE_NAME" \
  --arg outboundRouteType "$OUTBOUND_ROUTE_TYPE" \
  --arg outboundRouteSurface "$OUTBOUND_ROUTE_SURFACE" \
  --argjson outboundRouteSameBlock "$OUTBOUND_ROUTE_SAME_BLOCK" \
  --argjson outboundRouteMessagingSurface "$OUTBOUND_ROUTE_MESSAGING_SURFACE" \
  --arg expectedFlowName "$FLOW_DEV_NAME" \
  --arg flowActiveVersionId "$FLOW_ACTIVE_ID" \
  --arg queueId "$QUEUE_ID" \
  --argjson queueSobjectPresent "$QUEUE_SOBJECT_PRESENT" \
  --argjson queueHasActiveDirectUserMember "$QUEUE_HAS_ACTIVE_DIRECT_USER_MEMBER" \
  --argjson queueMemberCount "$MEMBER_COUNT" \
  --argjson queueRoutingConfigPresent "$QUEUE_ROUTING_CONFIG_PRESENT" \
  --argjson queueRoutingConfigBound "$QUEUE_ROUTING_CONFIG_BOUND" \
  --argjson agentActive "$AGENT_ACTIVE" \
  --argjson thresholdAuthored "$THRESHOLD_FLAG" \
  --argjson defaultFailureThreshold "$DEFAULT_FAILURE_THRESHOLD" \
  --arg authoringModel "$AUTHORING_MODEL" \
  --argjson ngaEscalationSurfacePresent "$NGA_SURFACE_PRESENT" \
  --arg ngaAgentType "$NGA_AGENT_TYPE" \
  '{canEscalate:$canEscalate, outboundRouteName:$outboundRouteName, outboundRouteType:$outboundRouteType,
    outboundRouteSurface:$outboundRouteSurface, outboundRouteSameBlock:$outboundRouteSameBlock,
    outboundRouteMessagingSurface:$outboundRouteMessagingSurface, expectedFlowName:$expectedFlowName,
    flowActiveVersionId:$flowActiveVersionId, queueId:$queueId, queueSobjectPresent:$queueSobjectPresent,
    queueHasActiveDirectUserMember:$queueHasActiveDirectUserMember, queueMemberCount:$queueMemberCount,
    queueRoutingConfigPresent:$queueRoutingConfigPresent, queueRoutingConfigBound:$queueRoutingConfigBound,
    agentActive:$agentActive, thresholdAuthored:$thresholdAuthored,
    defaultFailureThreshold:$defaultFailureThreshold, authoringModel:$authoringModel,
    ngaEscalationSurfacePresent:$ngaEscalationSurfacePresent, ngaAgentType:$ngaAgentType}' > "$EVID"

CONFIG_VERDICT=$(node "$SCRIPT_DIR/verify-escalation-config.mjs" "$EVID")
# Status mirrors the deterministic three-state verdict: CONFIGURED (routing + surface + policy),
# ROUTING_CONFIGURED_POLICY_PENDING (routing/surface done but failure-threshold directive missing),
# or INCOMPLETE. A missing policy can no longer masquerade as fully CONFIGURED.
STATUS=$(echo "$CONFIG_VERDICT" | jq -r '.verdict')
case "$STATUS" in
  CONFIGURED|ROUTING_CONFIGURED_POLICY_PENDING|INCOMPLETE) ;;
  *) STATUS="INCOMPLETE" ;;
esac

jq -n \
  --arg skill "$SKILL_NAME" \
  --arg status "$STATUS" \
  --arg agent "$AGENT_DN" \
  --arg queue "$QUEUE_DN" \
  --arg qid "$QUEUE_ID" \
  --argjson qmembers "$MEMBER_COUNT" \
  --arg flow "$FLOW_DEV_NAME" \
  --arg flowActive "$FLOW_ACTIVE_ID" \
  --arg topic "$ESCALATION_TOPIC" \
  --arg bundle "$PLANNER_BUNDLE" \
  --argjson config "$CONFIG_VERDICT" \
  --argjson thresholdValue "$DEFAULT_FAILURE_THRESHOLD" \
  --argjson thresholdAuthored "$THRESHOLD_FLAG" \
  --argjson directiveRendered "$DIRECTIVE_RENDERED" \
  --arg authoringModel "$AUTHORING_MODEL" \
  --argjson ngaSurface "$NGA_SURFACE_PRESENT" \
  --arg ngaAgentType "$NGA_AGENT_TYPE" \
  '{
    skill: $skill,
    status: $status,
    authoring_model: $authoringModel,
    agent: ({developer_name:$agent, active:true} + (if $authoringModel=="nga" then {type:$ngaAgentType, escalation_surface_present:$ngaSurface} else {} end)),
    queue: {developer_name:$queue, id:$qid, active_direct_user_member_count:$qmembers},
    outbound_flow: {api_name:$flow, active_version_id:(if $flowActive=="" then null else $flowActive end)},
    escalation_topic: (if $topic=="" then null else $topic end),
    planner_bundle: (if $bundle=="" then null else $bundle end),
    threshold: {default_failures:$thresholdValue, authored:$thresholdAuthored, directive_rendered:$directiveRendered},
    config_verification: $config,
    next_steps: (if $status=="CONFIGURED" then []
      elif $status=="ROUTING_CONFIGURED_POLICY_PENDING" then
      (["Routing and the agent escalation surface are verified, but the failure-threshold escalation policy (default two-failure / password-reset override) is not yet authored or confirmed. Author the threshold directive (AUTHOR_SURFACES=1) or confirm it in the topic instructions, then re-run to reach CONFIGURED. See references/failure-policy.md."])
      elif $authoringModel=="nga" then
      (["Deterministic routing infra is verified. Author the NGA escalation surface with agentforce-generate: for a Service agent add a reachable {!@utils.escalate} action (needs connection messaging:); for an Employee agent add a create-record (Case/Incident) action that Omni-routes to the queue. See references/nga-escalation.md, then re-run to reach CONFIGURED."]) else
      (["Author the doc-driven surfaces listed in config_verification.missing (see references/escalation-mechanism.md and failure-policy.md), then re-run to reach CONFIGURED."]) end),
    manual_actions: [],
    blocking_issue: null
  }'
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall