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/tests/_bootstrap.py

View on GitHub
"""Shared paths + fake-`sf` harness for the escalation-configure contract suite (org-free, network-free; drives the bash+Node skill via subprocess, asserting exit codes + emitted JSON)."""
from __future__ import annotations

import os
import subprocess
import tempfile
from pathlib import Path

# skills/ root is three levels up (.../<skill>/scripts/tests/_bootstrap.py). In the flat copy
# this is the repo's skills/ directory; in a plugin mirror it is that plugin's own bundled
# skills/ directory, which only contains its own roster.
SKILLS_ROOT = Path(__file__).resolve().parents[3]


_COORDINATOR = "service-itsm-agentic-setup-agentforce-coordinate"


def _find_flat_skills_root(start: Path) -> Path | None:
    """Walk up from this file to the directory holding the ITSM coordinator skill: the repo's
    flat skills/ root, or its team directory under contributed-skills/. Cross-skill references
    that aren't part of this skill's own plugin roster (like the coordinator's verdict script
    below) must resolve here, not under SKILLS_ROOT, since a plugin mirror's SKILLS_ROOT only
    contains its own bundled skills. The walk stops at the repo root so a stray skills/ tree in
    a parent directory is never executed; None means the coordinator isn't in this checkout."""
    for parent in start.parents:
        if (parent / "skills" / _COORDINATOR).is_dir():
            return parent / "skills"
        for team_copy in sorted((parent / "contributed-skills").glob(f"*/{_COORDINATOR}")):
            if team_copy.is_dir():
                return team_copy.parent
        if (parent / ".git").exists():
            break
    return None


FLAT_SKILLS_ROOT = _find_flat_skills_root(Path(__file__).resolve())

SKILL_DIR = "service-agentforce-human-escalation-configure"
SCRIPT = f"{SKILL_DIR}/scripts/verify-and-configure.sh"
# The ITSM coordinator's advancement gate - exercised for the escalation verdict mapping. Not
# bundled per-plugin, so resolved against FLAT_SKILLS_ROOT (see run_node's root parameter).
VERDICT_SCRIPT = "service-itsm-agentic-setup-agentforce-coordinate/scripts/verify-child-verdict.mjs"

# A fake `sf` that reports a PRODUCTION customer org so the safe_to_write guard must refuse.
# A fake `project deploy` returns a sentinel so a guard bypass would surface loudly.
_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":[{"Id":"00Dxx0000000000EAA","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
"""

# A fake `sf` for a SANDBOX org where every deterministic surface already resolves (active agent,
# MessagingChannel, queue + QueueSobject + QRC, active RoutingFlow) and `project retrieve` writes
# canEscalate=true / an outboundRouteName so the doc-driven surfaces verify true. The FAKE_* env vars
# below toggle each surface off to exercise the block/create paths; a GroupMember POST flips membership
# via a marker file (stateful convergence); canonical QRC id 0RC000000000001AAA makes create+adopt converge.
_FAKE_SF_SANDBOX = r"""#!/usr/bin/env bash
sub="${1:-} ${2:-}"; args="$*"
SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
AGENT_ACTIVE="${FAKE_AGENT_ACTIVE:-1}"
MC_PRESENT="${FAKE_MC_PRESENT:-1}"
QS_PRESENT="${FAKE_QS_PRESENT:-1}"
QRC_PRESENT="${FAKE_QRC_PRESENT:-1}"
QUEUE_PRESENT="${FAKE_QUEUE_PRESENT:-1}"
QUEUE_BOUND="${FAKE_QUEUE_BOUND:-1}"
QUEUE_MEMBERS="${FAKE_QUEUE_MEMBERS:-1}"
ROUTE_TYPE="${FAKE_ROUTE_TYPE:-OmniChannelFlow}"
ROUTE_SURFACE="${FAKE_ROUTE_SURFACE:-Messaging}"
# FAKE_GENAI_MD=0 → org exposes no GenAiPlugin/GenAiPlannerBundle metadata types (the escalation
# preflight must then BLOCK before any write). Default 1 → the authoring metadata is exposed.
GENAI_MD="${FAKE_GENAI_MD:-1}"
# FAKE_MODEL pins the authoring model the org advertises: classic (GenAiPlugin+GenAiPlannerBundle),
# nga (AiAuthoringBundle, no GenAiPlannerBundle), or none. Empty => derive from GENAI_MD (1=classic,0=none).
MODEL="${FAKE_MODEL:-}"
if [ -z "$MODEL" ]; then [ "$GENAI_MD" = "1" ] && MODEL="classic" || MODEL="none"; fi
TARGET_MODEL="${FAKE_TARGET_MODEL:-$MODEL}"
# FAKE_NGA_SURFACE=1 => retrieved AiAuthoringBundle contains connection messaging: + @utils.escalate
# (Service escalation surface present). 0 => neither (surface missing => INCOMPLETE on nga).
NGA_SURFACE="${FAKE_NGA_SURFACE:-1}"
RC_ID="0RC000000000001AAA"
# Opt-in call log: when FAKE_SF_CALLLOG points at a file, append every invocation's args so a
# test can prove which mutations did (or did NOT) happen - e.g. idempotent re-runs create nothing.
if [ -n "${FAKE_SF_CALLLOG:-}" ]; then printf '%s\n' "$args" >> "$FAKE_SF_CALLLOG"; fi
_has_members() { [ "$QUEUE_MEMBERS" = "1" ] || [ -f "$SELF_DIR/.gm_added" ]; }
case "$sub" in
  "org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
  "org list")
    if printf '%s' "$args" | grep -q "metadata-types"; then
      case "$MODEL" in
        classic) echo '{"status":0,"result":{"metadataObjects":[{"xmlName":"Bot"},{"xmlName":"GenAiPlugin"},{"xmlName":"GenAiPlannerBundle"}]}}';;
        nga)     echo '{"status":0,"result":{"metadataObjects":[{"xmlName":"Bot"},{"xmlName":"AiAuthoringBundle"},{"xmlName":"GenAiPlugin"}]}}';;
        both)    echo '{"status":0,"result":{"metadataObjects":[{"xmlName":"Bot"},{"xmlName":"AiAuthoringBundle"},{"xmlName":"GenAiPlugin"},{"xmlName":"GenAiPlannerBundle"}]}}';;
        *)       echo '{"status":0,"result":{"metadataObjects":[{"xmlName":"Bot"},{"xmlName":"BotTemplate"},{"xmlName":"BotBlock"}]}}';;
      esac
    else
      echo '{"status":0,"result":{}}'
    fi
    exit 0;;
  "data query")
    if printf '%s' "$args" | grep -q "FROM Organization"; then
      echo '{"status":0,"result":{"records":[{"Id":"00Dxx0000000000EAA","IsSandbox":true,"TrialExpirationDate":null,"OrganizationType":"Developer Edition"}]}}'
    elif printf '%s' "$args" | grep -q "FROM BotDefinition"; then
      if [ "$AGENT_ACTIVE" = "1" ]; then
        echo '{"status":0,"result":{"records":[{"Id":"0Xx000000000001AAA","DeveloperName":"Support_Agent","MasterLabel":"Support Agent","BotVersions":{"records":[{"Id":"04V000000000001AAA","Status":"Active"}]}}],"totalSize":1}}'
      else
        echo '{"status":0,"result":{"records":[{"Id":"0Xx000000000001AAA","DeveloperName":"Support_Agent","MasterLabel":"Support Agent","BotVersions":{"records":[{"Id":"04V000000000001AAA","Status":"Inactive"}]}}],"totalSize":1}}'
      fi
    elif printf '%s' "$args" | grep -q "FROM MessagingChannel"; then
      if [ "$MC_PRESENT" = "1" ]; then
        echo '{"status":0,"result":{"records":[{"Id":"0M9000000000001AAA","DeveloperName":"Support_Chat"}],"totalSize":1}}'
      else
        echo '{"status":0,"result":{"records":[],"totalSize":0}}'
      fi
    elif printf '%s' "$args" | grep -q "FROM QueueSobject"; then
      if [ "$QS_PRESENT" = "1" ]; then
        echo '{"status":0,"result":{"records":[{"Id":"0Q9000000000001AAA"}],"totalSize":1}}'
      else
        echo '{"status":0,"result":{"records":[],"totalSize":0}}'
      fi
    elif printf '%s' "$args" | grep -q "FROM QueueRoutingConfig"; then
      if [ "$QRC_PRESENT" = "1" ]; then
        echo '{"status":0,"result":{"records":[{"Id":"'"$RC_ID"'","DeveloperName":"Human_Support_Queue_RC"}],"totalSize":1}}'
      else
        echo '{"status":0,"result":{"records":[],"totalSize":0}}'
      fi
    elif printf '%s' "$args" | grep -q "FROM FlowDefinitionView"; then
      echo '{"status":0,"result":{"records":[{"ApiName":"Human_Escalation_Outbound_Flow","ActiveVersionId":"301000000000001AAA"}],"totalSize":1}}'
    elif printf '%s' "$args" | grep -q "FROM GroupMember"; then
      if _has_members; then
        echo '{"status":0,"result":{"records":[{"UserOrGroupId":"005000000000001AAA"}],"totalSize":1}}'
      else
        echo '{"status":0,"result":{"records":[],"totalSize":0}}'
      fi
    elif printf '%s' "$args" | grep -q "FROM User"; then
      if printf '%s' "$args" | grep -q "COUNT(Id)"; then
        if _has_members; then
          echo '{"status":0,"result":{"records":[{"c":1}],"totalSize":1}}'
        else
          echo '{"status":0,"result":{"records":[{"c":0}],"totalSize":1}}'
        fi
      else
        # Id-by-username (assignment path) → an active user row.
        echo '{"status":0,"result":{"records":[{"Id":"005000000000002AAA"}],"totalSize":1}}'
      fi
    elif printf '%s' "$args" | grep -q "FROM Group"; then
      if [ "$QUEUE_PRESENT" = "1" ]; then
        if [ "$QUEUE_BOUND" = "1" ]; then
          echo '{"status":0,"result":{"records":[{"Id":"00G000000000001AAA","QueueRoutingConfigId":"'"$RC_ID"'"}],"totalSize":1}}'
        else
          echo '{"status":0,"result":{"records":[{"Id":"00G000000000001AAA","QueueRoutingConfigId":null}],"totalSize":1}}'
        fi
      else
        echo '{"status":0,"result":{"records":[],"totalSize":0}}'
      fi
    else
      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
    fi
    exit 0;;
  "api request")
    # Data API POST/PATCH (QueueSobject bind, QueueRoutingConfig create, Group.QueueRoutingConfigId bind).
    if printf '%s' "$args" | grep -q "sobjects/QueueRoutingConfig"; then
      echo '{"success":true,"id":"'"$RC_ID"'"}'
    elif printf '%s' "$args" | grep -q "sobjects/QueueSobject"; then
      echo '{"success":true,"id":"0Q9000000000009AAA"}'
    elif printf '%s' "$args" | grep -q "sobjects/GroupMember"; then
      touch "$SELF_DIR/.gm_added"
      echo '{"success":true,"id":"0GM00000000001AAA"}'
    else
      # Group PATCH → 204 empty body on success.
      echo ''
    fi
    exit 0;;
  "project retrieve")
    dir=$(printf '%s' "$args" | sed -n 's/.*--target-metadata-dir[ =]\([^ ]*\).*/\1/p'); dir="${dir:-.}"
    mkdir -p "$dir"
    if printf '%s' "$args" | grep -q "AiAuthoringBundle:"; then
      [ "$TARGET_MODEL" = "nga" ] || [ "$TARGET_MODEL" = "both" ] || exit 1
      if [ "$NGA_SURFACE" = "1" ]; then
        cat > "$dir/Support_Agent.agent" <<'AGENT'
start_agent support_agent:
    connection messaging:
        end_user_client: customer_web_client
    reasoning:
        actions:
            human_handoff: @utils.escalate
                description: "Transfer the user to a human agent."
AGENT
      else
        cat > "$dir/Support_Agent.agent" <<'AGENT'
start_agent support_agent:
    reasoning:
        actions:
            answer: @actions.AnswerQuestionWithKnowledge
AGENT
      fi
    elif printf '%s' "$args" | grep -q "GenAiPlugin:"; then
      if [ "${FAKE_AUTHORING_FIXTURE:-0}" = "1" ]; then
        # Metadata-format bundle whose GenAiPlugin has no XSD anchor, so the canEscalate patcher
        # refuses after the deactivate and the rollback path runs.
        mkdir -p "$dir/genAiPlugins"
        echo '<?xml version="1.0"?><Package xmlns="x"></Package>' > "$dir/package.xml"
        printf '<?xml version="1.0"?>\n<GenAiPlugin xmlns="x"></GenAiPlugin>\n' > "$dir/genAiPlugins/Escalate_Topic.genAiPlugin"
      else
        echo '<canEscalate>true</canEscalate>' > "$dir/plugin.xml"
      fi
    elif printf '%s' "$args" | grep -q "GenAiPlannerBundle:"; then
      [ "$TARGET_MODEL" = "classic" ] || [ "$TARGET_MODEL" = "both" ] || exit 1
      cat > "$dir/bundle.xml" <<BXML
<GenAiPlannerBundle>
  <plannerSurfaces>
    <surfaceType>${ROUTE_SURFACE}</surfaceType>
    <outboundRouteConfigs>
      <escalationMessage>Transferring you to a live support agent.</escalationMessage>
      <outboundRouteName>Human_Escalation_Outbound_Flow</outboundRouteName>
      <outboundRouteType>${ROUTE_TYPE}</outboundRouteType>
    </outboundRouteConfigs>
  </plannerSurfaces>
</GenAiPlannerBundle>
BXML
    fi
    echo '{"status":0,"result":{"success":true}}'; exit 0;;
  "project deploy")
    echo '{"status":0,"result":{"success":true,"files":[{"fullName":"Human_Escalation_Outbound_Flow","type":"Flow","state":"Created"}]}}'; exit 0;;
  "agent activate")
    # FAKE_ACTIVATE_FAIL=1 → reactivation fails, so a rollback must report the agent left inactive.
    if [ "${FAKE_ACTIVATE_FAIL:-0}" = "1" ]; then
      echo '{"status":1,"message":"FAKE_ACTIVATE_FAILED"}'; exit 1
    fi
    echo '{"status":0,"result":{}}'; exit 0;;
  *) echo '{"status":0,"result":{}}'; exit 0;;
esac
"""

# Only what bash, node, and version-manager shims need, so tokens, SF_* overrides, and
# NODE_OPTIONS from the developer's shell never reach the scripts under test.
_ENV_PASSTHROUGH = ("PATH", "HOME", "TERM", "TMPDIR", "LANG", "LC_ALL", "USER", "SHELL")


def _base_env():
    return {k: os.environ[k] for k in _ENV_PASSTHROUGH if k in os.environ}


def run(args, path_prefix=None, scrub_sf=False, extra_env=None):
    """Run the orchestrator; return (returncode, merged stdout+stderr)."""
    env = _base_env()
    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 "")


def run_node(script_rel, args, root=None):
    """Run a bundled Node helper; return (returncode, stdout). Pass `root=FLAT_SKILLS_ROOT`
    for cross-skill scripts not bundled in this skill's own plugin roster."""
    base = root if root is not None else SKILLS_ROOT
    proc = subprocess.run(
        ["node", str(base / script_rel), *args],
        capture_output=True, text=True, cwd=str(base), env=_base_env(),
    )
    return proc.returncode, (proc.stdout or "")


class FakeSf:
    """Context manager: a temp dir holding an executable fake `sf` first on PATH."""

    def __init__(self, body=_FAKE_SF_PROD):
        self._body = body
        self._tmp = None

    def __enter__(self):
        self._tmp = tempfile.mkdtemp(prefix="esc-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)
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 CodeCodexVerifiedInstall
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