@salesforce/afv-skills 1.47.0 → 1.49.0

package/skills/service-agentforce-human-escalation-configure/scripts/verify-escalation-config.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Deterministic verdict from an evidence.json → { verdict, deterministicPass, directivePass, checks[], missing[] }; exit 3 on unparseable. evidence.json contract: references/classifier-contracts.md.
+
+import { readFileSync } from 'node:fs';
+
+const [evidencePath] = process.argv.slice(2);
+if (!evidencePath) {
+  process.stderr.write('usage: node verify-escalation-config.mjs <evidence.json>\n');
+  process.exit(2);
+}
+
+let e;
+try {
+  const text = readFileSync(evidencePath, 'utf8').trim();
+  e = text ? JSON.parse(text) : {};
+} catch {
+  process.stderr.write(`error: could not read/parse ${evidencePath}\n`);
+  process.exit(3);
+}
+
+const nonEmpty = (v) => typeof v === 'string' && v.trim() !== '';
+const flowNamesMatch =
+  nonEmpty(e.outboundRouteName) &&
+  nonEmpty(e.expectedFlowName) &&
+  e.outboundRouteName === e.expectedFlowName;
+
+// The outbound route is only real when the SAME planner-surface block carries a matching
+// route name AND an OmniChannelFlow route type, on a Messaging-class surface. A bundle that
+// has the right name and an OmniChannelFlow type in unrelated blocks must NOT pass.
+const outboundRouteWired =
+  flowNamesMatch &&
+  e.outboundRouteType === 'OmniChannelFlow' &&
+  e.outboundRouteSameBlock === true &&
+  e.outboundRouteMessagingSurface === true;
+
+// The routing-infrastructure half is authoring-model-agnostic - it is deterministic in both models.
+const routingChecks = [
+  { key: 'outboundFlowActive', ok: nonEmpty(e.flowActiveVersionId), kind: 'deterministic' },
+  { key: 'humanQueue', ok: nonEmpty(e.queueId), kind: 'deterministic' },
+  { key: 'queueSobject', ok: e.queueSobjectPresent === true, kind: 'deterministic' },
+  { key: 'queueHasActiveDirectUserMember', ok: e.queueHasActiveDirectUserMember === true, kind: 'deterministic' },
+  { key: 'queueRoutingConfig', ok: e.queueRoutingConfigPresent === true, kind: 'deterministic' },
+  { key: 'queueRoutingConfigBound', ok: e.queueRoutingConfigBound === true, kind: 'deterministic' },
+  { key: 'agentActive', ok: e.agentActive === true, kind: 'deterministic' },
+];
+
+// Model-specific agent surface: classic authors canEscalate + a same-block Messaging outboundRoute;
+// NGA verifies a reachable @utils.escalate (Service) or create-record (Employee) in the AiAuthoringBundle.
+const authoringModel = e.authoringModel === 'nga' ? 'nga' : 'classic';
+const surfaceChecks =
+  authoringModel === 'nga'
+    ? [{ key: 'ngaEscalationSurface', ok: e.ngaEscalationSurfacePresent === true, kind: 'deterministic' }]
+    : [
+        { key: 'canEscalate', ok: e.canEscalate === true, kind: 'deterministic' },
+        { key: 'outboundRouteConfigs', ok: outboundRouteWired, kind: 'deterministic' },
+      ];
+
+const checks = [
+  ...surfaceChecks,
+  ...routingChecks,
+  { key: 'thresholdDirective', ok: e.thresholdAuthored === true, kind: 'directive' },
+];
+
+const deterministic = checks.filter((c) => c.kind === 'deterministic');
+const deterministicPass = deterministic.every((c) => c.ok);
+const directivePass = checks.find((c) => c.key === 'thresholdDirective').ok;
+const missing = checks.filter((c) => !c.ok).map((c) => c.key);
+
+const defaultFailureThreshold =
+  Number.isInteger(e.defaultFailureThreshold) ? e.defaultFailureThreshold : null;
+
+// A missing failure-threshold directive must NOT read as fully CONFIGURED: routing can be complete
+// while the escalation policy (default two-failure / password-reset override) is not yet guaranteed.
+// Distinguish the three cases so a policy gap is never hidden behind a green verdict.
+const verdict = !deterministicPass
+  ? 'INCOMPLETE'
+  : directivePass
+    ? 'CONFIGURED'
+    : 'ROUTING_CONFIGURED_POLICY_PENDING';
+
+process.stdout.write(JSON.stringify({
+  verdict,
+  authoringModel,
+  deterministicPass,
+  directivePass,
+  defaultFailureThreshold,
+  checks,
+  missing,
+}, null, 2) + '\n');

package/skills/service-de-channel-routing-configure/SKILL.md

@@ -8,6 +8,8 @@ metadata:
   cliTools:
     - tool: ["node"]
       semver: ">=20.0.0"
+    - tool: ["python3"]
+      semver: ">=3.9"
     - tool: ["sf"]
       semver: ">=2.0.0"
   relatedSkills:
@@ -53,7 +55,7 @@ Provisioning behavior:
 
 ## When NOT to use this skill
 
-- **The channel already has `SessionHandlerId` or `FallbackQueueId` set.** This skill no-ops and tells you — nothing to do. Proceed to activation.
+- **The channel already has `SessionHandlerId` or `FallbackQueueId` set.** This skill revalidates the existing target before no-op. An ASA must still have a BotUser and an Active BotVersion; otherwise it reports `asa-target-inactive` and does not claim readiness.
 - **The channel doesn't exist yet.** Run the insertion skill first; this skill expects a real `MessagingChannel.Id`.
 - **You want to replace existing routing.** Safer to clear `SessionHandlerId` manually in the UI, then re-run this skill. The no-op check is a guardrail, not a limitation worth bypassing automatically.
 
@@ -127,13 +129,13 @@ sf data query --target-org '{ORG_ALIAS}' \
 
 Parse with `node -e` or `jq`. If the record is missing — halt with `Error: Channel {CHANNEL_ID} not found — check the id, or run the insertion skill first.`
 
-If `SessionHandlerId` is non-null, branch on the Id prefix to figure out what the existing routing target is, then no-op with the right envelope. The prefix maps 1:1 to the SessionHandler domain (verified against `MessagingChannel.entity.xml`):
+If `SessionHandlerId` is non-null, branch on the Id prefix to figure out what the existing routing target is, then no-op with the right envelope. The prefix maps 1:1 to the SessionHandler domain (verified against `MessagingChannel.entity.xml`). Existing routing is not automatically healthy: the target lookup must return exactly one eligible row before reporting a successful no-op.
 
 | Prefix | Domain / Target | Lookup query | routingType |
 | --- | --- | --- | --- |
 | `00G` | `Group` (Type=Queue) | `SELECT Id, Name, DeveloperName FROM Group WHERE Id='<sh>' AND Type='Queue'` | `queue` |
 | `300` | `FlowDefinition` | `SELECT DurableId, Label, ApiName FROM FlowDefinitionView WHERE DurableId='<sh>'` | `flow` |
-| `0Xx` | `BotDefinition` (ASA) | `SELECT Id, DeveloperName, MasterLabel, AgentType FROM BotDefinition WHERE Id='<sh>'` | `asa` |
+| `0Xx` | `BotDefinition` (ASA) | `SELECT Id, DeveloperName, MasterLabel, AgentType, BotUserId, (SELECT Id, Status FROM BotVersions WHERE Status='Active' LIMIT 1) FROM BotDefinition WHERE Id='<sh>'` | `asa` |
 | `1iE` | `AgenticCtxtDecorDefinition` (Digital Worker) | `SELECT Id, DeveloperName, MasterLabel FROM AgenticCtxtDecorDefinition WHERE Id='<sh>'` | `digital_worker` |
 | `005` | `User` | `SELECT Id, Name FROM User WHERE Id='<sh>'` | `user` |
 
@@ -143,14 +145,20 @@ PREFIX="${SESSION_HANDLER_ID:0:3}"
 case "$PREFIX" in
   00G) sf data query --target-org '{ORG_ALIAS}' --query "SELECT Id, Name, DeveloperName FROM Group WHERE Id = '$SESSION_HANDLER_ID' AND Type = 'Queue'" --json > /tmp/ccr-noop-target.json ;;
   300) sf data query --target-org '{ORG_ALIAS}' --query "SELECT DurableId, Label, ApiName FROM FlowDefinitionView WHERE DurableId = '$SESSION_HANDLER_ID'" --json > /tmp/ccr-noop-target.json ;;
-  0Xx) sf data query --target-org '{ORG_ALIAS}' --query "SELECT Id, DeveloperName, MasterLabel, AgentType FROM BotDefinition WHERE Id = '$SESSION_HANDLER_ID'" --json > /tmp/ccr-noop-target.json ;;
+  0Xx) sf data query --target-org '{ORG_ALIAS}' --query "SELECT Id, DeveloperName, MasterLabel, AgentType, BotUserId, (SELECT Id, Status FROM BotVersions WHERE Status='Active' LIMIT 1) FROM BotDefinition WHERE Id = '$SESSION_HANDLER_ID'" --json > /tmp/ccr-noop-target.json ;;
   1iE) sf data query --target-org '{ORG_ALIAS}' --query "SELECT Id, DeveloperName, MasterLabel FROM AgenticCtxtDecorDefinition WHERE Id = '$SESSION_HANDLER_ID'" --json > /tmp/ccr-noop-target.json ;;
   005) sf data query --target-org '{ORG_ALIAS}' --query "SELECT Id, Name FROM User WHERE Id = '$SESSION_HANDLER_ID'" --json > /tmp/ccr-noop-target.json ;;
   *)   echo "{\"records\":[{\"Id\":\"$SESSION_HANDLER_ID\"}]}" > /tmp/ccr-noop-target.json ;;
 esac
 ```
 
-Report the success-noop envelope (include the existing `FallbackQueueId` from the Stage 1 read) and return.
+For an existing ASA (`0Xx`), require a non-null `BotUserId` and one returned `BotVersions` row with `Status='Active'`. If either is missing, return the following failure instead of a successful no-op. Do not clear or replace the channel routing automatically:
+
+```json
+{"ok":false,"kind":"asa-target-inactive","routingType":"asa","sessionHandlerId":"0Xx...","hint":"The configured Agentforce Service Agent has no BotUser or active BotVersion. Activate the agent in Setup, then re-run routing validation."}
+```
+
+For other prefixes, require exactly one target lookup row. Report the success-noop envelope (include the existing `FallbackQueueId` from the Stage 1 read) only after the target-specific eligibility check succeeds, then return.
 
 If `FallbackQueueId` is non-null but `SessionHandlerId` is null — still no-op. That's a partially-configured Flow/ASA state; don't touch it, but flag it in the envelope `message` (`"FallbackQueue set but SessionHandler null — incomplete routing, review in Setup"`) since activation will still fail readiness without a SessionHandler.
 

package/skills/service-de-channel-routing-configure/scripts/tests/test_skill_contract.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+import unittest
+from pathlib import Path
+
+
+class ExistingAsaRouteTests(unittest.TestCase):
+    def test_noop_revalidates_bot_user_and_active_version(self):
+        skill = Path(__file__).resolve().parents[2] / "SKILL.md"
+        source = skill.read_text()
+        noop_contract = source.split(
+            "If `SessionHandlerId` is non-null", 1
+        )[1].split("For other prefixes", 1)[0]
+
+        self.assertIn("0Xx) sf data query", noop_contract)
+        self.assertIn("BotUserId", noop_contract)
+        self.assertIn("WHERE Status='Active'", noop_contract)
+        self.assertIn("require a non-null `BotUserId`", noop_contract)
+        self.assertIn(
+            '{"ok":false,"kind":"asa-target-inactive"',
+            noop_contract,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/service-itsm-agentic-setup-agentforce-coordinate/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: service-itsm-agentic-setup-agentforce-coordinate
-description: "Orchestrator for setting up Agentforce in Salesforce Service Cloud ITSM — Agentforce Studio enablement, the IT Service Fulfiller agent, the IT Service Employee agent, and specialized employee agents. Use when the user asks to set up Agentforce for ITSM, enable Studio and the Fulfiller/Employee agents together, wants a guided Agentforce ITSM walkthrough, or asks what Agentforce features are available for IT Service. Presents available Agentforce capabilities and delegates each selection to a specialized child skill while tracking progress. Triggers on: set up agentforce for itsm, configure agentforce studio and fulfiller, agentforce itsm walkthrough, what agentforce features for it service. DO NOT TRIGGER when: the user asks to enable Agentforce Studio alone, asks to create or activate the Fulfiller or Employee agent alone, or asks about CMDB, Incident Management, Teams, or general ITSM setup without Agentforce intent."
+description: "Orchestrator for setting up Agentforce in Salesforce Service Cloud ITSM — Agentforce Studio enablement, the IT Service Fulfiller agent, the IT Service Employee agent, specialized employee agents, and human escalation. Use when the user asks to set up Agentforce for ITSM, enable Studio and the Fulfiller/Employee agents together, configure employee-agent escalation, wants a guided Agentforce ITSM walkthrough, or asks what Agentforce features are available for IT Service. Presents available Agentforce capabilities and delegates each selection to a specialized child skill while tracking progress. Triggers on: set up agentforce for itsm, configure agentforce studio and fulfiller, agentforce itsm walkthrough, what agentforce features for it service. DO NOT TRIGGER when: the user asks to enable Agentforce Studio alone, asks to create or activate the Fulfiller or Employee agent alone, asks to configure escalation alone, or asks about CMDB, Incident Management, Teams, or general ITSM setup without Agentforce intent."
 metadata:
-  version: "1.7"
+  version: "1.8"
   domains: ["Service", "Agentforce"]
   relatedSkills:
+    - "service-agentforce-human-escalation-configure"
     - "service-itsm-agentic-setup-agentforce-studio-configure"
     - "service-itsm-agentic-setup-agentforce-studio-validate"
     - "service-itsm-agentic-setup-employee-agent-configure"
@@ -20,7 +21,7 @@ allowed-tools: Read Bash Write AskUserQuestion
 
 # Agentforce for ITSM Setup Orchestrator
 
-Guide the user through setting up Agentforce Studio, the IT Service Fulfiller agent, the IT Service Employee agent, and specialized employee agents in Salesforce Service Cloud ITSM by presenting the available capabilities, delegating to specialized child skills, and tracking progress.
+Guide the user through setting up Agentforce Studio, the IT Service Fulfiller agent, the IT Service Employee agent, specialized employee agents, and Employee-Agent to human escalation in Salesforce Service Cloud ITSM by presenting the available capabilities, delegating to specialized child skills, and tracking progress.
 
 ## Goal
 
@@ -52,22 +53,25 @@ activate agent templates** (the Fulfiller and Employee agents). This separation
 Stage 1 *enables* org-level platform toggles/preferences, while Stage 2 *installs and activates*
 agents from a template — they are distinct kinds of action and must read as distinct stages, not one
 undifferentiated list. Only features with a working child skill appear in the menu — use the
-**Feature menu** template in `examples/output-templates.md`. Collect the user's selections through a single multi-select prompt (use `AskUserQuestion` with `multiSelect: true` when tooling permits, otherwise ask the user to reply with a list of numbers such as `1, 2`). Use the **exact Item names from the Feature menu table** as the multi-select option labels — verbatim, including each item's parenthetical note and the word "Agent" and its capitalization (`Agentforce Studio enablement (Foundation for all agents)`, `IT Service Fulfiller Agent`, `IT Service Employee Agent`, `Specialized Agents for Employee`) — so the picker options and the table never diverge. Each item's **Description column matches the wording on the Salesforce Setup → Agentforce for IT Service page** (the Fulfiller and Employee agent-template descriptions and the Specialized Agents for Employee text are used verbatim) so a user evaluating which template to install reads the same purpose/scope here as they would in Setup — do not paraphrase or shorten that product copy. For the three Stage 2 agent items, follow the verbatim product copy with one short trailing `Setup:` line stating what installing does (`Setup: creates the agent from this template and activates a version.` for the Fulfiller and Employee agents; `Setup: pick one specialized template (e.g. Password Manager, Onboarding), then create and activate that standalone agent. Re-run this item to add more.` for Specialized Agents for Employee, for which you first ask the user which specialized template they want and pass that name to the child skill) so a single row carries purpose, scope, and the install action together. The Stage 1 row (Agentforce Studio enablement) is a platform-enablement toggle, not a template install, so it carries no `Setup:` line. When raising `AskUserQuestion`, put that same Description text (product copy + the `Setup:` line) in each option's `description` field so the picker carries the detail too. Do NOT show placeholder features that cannot be executed.
+**Feature menu** template in `examples/output-templates.md`. Collect the user's selections through a single multi-select prompt (use `AskUserQuestion` with `multiSelect: true` when tooling permits, otherwise ask the user to reply with a list of numbers such as `1, 2`). Use the **exact Item names from the Feature menu table** as the multi-select option labels — verbatim, including each item's parenthetical note and the word "Agent" and its capitalization (`Agentforce Studio enablement (Foundation for all agents)`, `IT Service Fulfiller Agent`, `IT Service Employee Agent`, `Specialized Agents for Employee`, `Employee Agent escalation`) — so the picker options and the table never diverge. Each item's **Description column matches the wording on the Salesforce Setup → Agentforce for IT Service page** (the Fulfiller and Employee agent-template descriptions and the Specialized Agents for Employee text are used verbatim) so a user evaluating which template to install reads the same purpose/scope here as they would in Setup — do not paraphrase or shorten that product copy. For the three Stage 2 agent items, follow the verbatim product copy with one short trailing `Setup:` line stating what installing does (`Setup: creates the agent from this template and activates a version.` for the Fulfiller and Employee agents; `Setup: pick one specialized template (e.g. Password Manager, Onboarding), then create and activate that standalone agent. Re-run this item to add more.` for Specialized Agents for Employee, for which you first ask the user which specialized template they want and pass that name to the child skill) so a single row carries purpose, scope, and the install action together. The Stage 1 row (Agentforce Studio enablement) is a platform-enablement toggle, not a template install, so it carries no `Setup:` line. When raising `AskUserQuestion`, put that same Description text (product copy + the `Setup:` line) in each option's `description` field so the picker carries the detail too. Do NOT show placeholder features that cannot be executed.
 
 **Report file (harness / non-interactive runs).** If a `${outputDir}` is provided (via the harness's generated-file location directive), write the menu emission (attribution header + feature table with status + delegation targets + dependency signal + the multi-select prompt itself) to `${outputDir}/report.md` **before** raising `AskUserQuestion` — so the report file always exists even when the harness parks at the confirmation gate. Overwrite the same file after each feature completes with the updated status table. Skip these writes when running interactively for a user in a chat surface — write only when `${outputDir}` was passed as an explicit destination.
 
 ### 4. Delegate to child skills in dependency order
 
-**Studio-first rule (unconditional).** If Agentforce Studio enablement (#1) is in the user's selection and not already done, run it **first**, always — regardless of the order the user listed their numbers in. The Fulfiller Agent (#2), Employee Agent (#3), and Specialized Agents for Employee (#4) all depend on Studio being enabled and will fail if attempted first. Reorder the queue silently so Studio runs before any agent. This rule is non-negotiable and applies whether the user selected two features (Studio + one agent) or everything.
+**Studio-first rule (unconditional).** If Agentforce Studio enablement (#1) is in the user's selection and not already done, run it **first**, always — regardless of the order the user listed their numbers in. The Fulfiller Agent (#2), Employee Agent (#3), and Specialized Agents for Employee (#4) all depend on Studio being enabled and will fail if attempted first. Reorder the queue silently so Studio runs before any agent. This rule is non-negotiable and applies whether the user selected two features (Studio + one agent) or everything. Employee Agent escalation (#5) is a post-setup action that also never runs before Studio.
 
 **User-order rule (among #2, #3, and #4 only).** The Fulfiller Agent (#2), Employee Agent (#3), and Specialized Agents for Employee (#4) are independent of each other — none depends on the others. If more than one is selected, run them in the order the user listed them (default 2 → 3 → 4 when unspecified). This rule applies **only** to the ordering among #2, #3, and #4; it never overrides the Studio-first rule above.
 
+**Escalation-after-Employee rule (#5 depends on #3).** Employee Agent escalation (#5) configures the Employee agent's hand-off to a human, so it **requires the Employee Agent (#3) to exist and be Active** first. If #5 is selected, ensure #3 has completed successfully in this run (or was already done) before delegating to it; otherwise queue #3 ahead of #5. #5 never runs before Studio (#1) either.
+
 | # | Feature | Stage | Child Skill |
 |---|---------|-------|-------------|
 | 1 | Agentforce Studio enablement (Foundation for all agents) | 1 | `service-itsm-agentic-setup-agentforce-studio-configure` |
 | 2 | IT Service Fulfiller Agent | 2 | `service-itsm-agentic-setup-fulfiller-agent-configure` |
 | 3 | IT Service Employee Agent | 2 | `service-itsm-agentic-setup-employee-agent-configure` |
 | 4 | Specialized Agents for Employee | 2 | `service-itsm-agentic-setup-employee-agent-configure` |
+| 5 | Employee Agent escalation | Post | `service-agentforce-human-escalation-configure` (pass the IT scenario inputs: agent `IT_Service_Employee_Agent`, queue `General_IT_Queue`, `CONTEXT_OBJECT=MessagingSession`) |
 
 **How #3 and #4 relate.** Both #3 and #4 delegate to the same child skill,
 `service-itsm-agentic-setup-employee-agent-configure` — the difference is which template it installs.
@@ -95,9 +99,10 @@ to call it as part of the delegation flow above.
 Once a child skill finishes:
 
 1. **Verify** the child skill's own deterministic verdict by running
-   `node "<skill_dir>/scripts/verify-child-verdict.mjs" <studio|fulfiller|employee> <verdict>` — never
+   `node "<skill_dir>/scripts/verify-child-verdict.mjs" <studio|fulfiller|employee|escalation> <verdict>` — never
    re-derive the success/failure comparison in prose. Pass Studio's `overall` field from
-   `classify-final-report.mjs`, or Fulfiller/Employee Agent's Phase 8 aggregate verdict, as
+   `classify-final-report.mjs`, Fulfiller/Employee Agent's Phase 8 aggregate verdict, or the escalation
+   leaf's `status` (`CONFIGURED`/`ALREADY-CONFIGURED`), as
    `<verdict>`. Exit code `0` means advance; exit code `1` means **stop and surface the failure in
    plain language — do not advance to the next feature in the queue.** A partially-enabled Studio
    (e.g. Einstein GenAI on but the parent umbrella still blocked, `overall: PARTIAL`) will make
@@ -115,8 +120,9 @@ When the user says they're done (or all available features are configured), pres
 
 ## Setup Stages & Recommended Order
 
-Setup runs in **two sequential stages**. Stage 1 (enable platform features) must complete before
-Stage 2 (install & activate agent templates).
+Setup runs in **two sequential setup stages**, followed by optional post-setup escalation. Stage 1
+(enable platform features) must complete before Stage 2 (install & activate agent templates).
+Escalation runs only after the Employee agent is active.
 
 ```text
 Stage 1 — Foundation: enable platform features
@@ -126,6 +132,9 @@ Stage 2 — Agent templates: install & activate   (only after Stage 1)
   2. IT Service Fulfiller Agent          (install from template, commit, and activate the agent)
   3. IT Service Employee Agent           (install the broad employee agent from its template and activate it)
   4. Specialized Agents for Employee     (install a specialized employee agent — user picks the template — and activate it)
+
+Post-setup — Human escalation   (only after item 3 is active)
+  5. Employee Agent escalation           (configure canEscalate, outbound routing, a staffed General IT queue, and failure-threshold directives)
 ```
 
 Stage 1 (Agentforce Studio enablement) is the **foundation**: it turns on the org-level Agentforce
@@ -135,7 +144,9 @@ before this foundation is enabled will fail. The three Stage 2 items (Fulfiller,
 Specialized Agents for Employee) are independent siblings (none depends on the others) — they can be
 selected together and installed in any order once Stage 1 is done. Specialized Agents for Employee
 is listed right after the IT Service Employee Agent because both build employee agents from the same
-child skill: #3 the broad default, #4 a specialized template the user chooses.
+child skill: #3 the broad default, #4 a specialized template the user chooses. Employee Agent
+escalation (#5) is a post-setup action that builds on a live Employee agent, so it runs only after
+item 3 has succeeded.
 
 ---
 
@@ -149,6 +160,7 @@ child skill: #3 the broad default, #4 a specialized template the user chooses.
 - If the user says "set up everything" or "all", walk through each available feature sequentially in the recommended order, confirming between each step
 - Track progress across the conversation — do not re-present completed features as "Not done"
 - Specialized Agents for Employee (#4) is **re-selectable** — each run builds a *different* specialized employee agent from a template the user picks. Mark the agent just built as `Done`, but keep #4 available to run again for additional specialized agents; do not treat a completed #4 as permanently finished the way #1–#3 are. If the user picks #4 again, ask which specialized template to use next
+- Employee Agent escalation (#5) is a **post-setup** action that requires the IT Service Employee Agent (#3) to be Active first — never delegate #5 before #3 has succeeded in this run (or was already done)
 - NEVER advance to the next feature in the queue if the current one failed or only partially
   succeeded — stop and surface the failure in plain language instead
 - If Agentforce Studio enablement reports the org lacks the Agentforce license (`accessCheck`), STOP
@@ -176,6 +188,7 @@ Before emitting any menu or summary in this skill, mentally confirm each of the
 - [ ] Each feature row's `Status` column reflects the actual tracked state from the conversation (`Not done`, `In progress`, or `Done`) — not a hard-coded default
 - [ ] Each feature row's `Description` matches the Salesforce Setup → Agentforce for IT Service page wording (Fulfiller and Employee agent-template descriptions verbatim, not paraphrased), the three Stage 2 rows each end with a short `Setup:` install line, and the `AskUserQuestion` option descriptions carry the same text
 - [ ] The Specialized Agents for Employee row is present as a Stage 2 item shown right after the IT Service Employee Agent, and #4 is never delegated to `service-itsm-agentic-setup-employee-agent-configure` without first asking the user which specialized template they want (handed no name, the child skill defaults to the broad agent and duplicates #3), and it carries its `Setup:` install line
+- [ ] The Employee Agent escalation row is present as a post-setup item shown after the Stage 2 agents, and #5 is never delegated to `service-agentforce-human-escalation-configure` before the IT Service Employee Agent (#3) is Active
 - [ ] For a completion summary, the header line and closing line are chosen by the rubric in `examples/output-templates.md` (all `Done` → *Complete*; any `Not done`/`In progress` → *Finished*)
 - [ ] A feature is being configured only because the user explicitly selected it (or is being walked through sequentially with confirmation under an "all" / "everything" request)
 - [ ] Studio enablement is verified done before delegating to any Stage 2 agent (Fulfiller, Employee, or Specialized Agents for Employee)

package/skills/service-itsm-agentic-setup-agentforce-coordinate/examples/output-templates.md

@@ -1,39 +1,43 @@
 # Output Templates — service-itsm-agentic-setup-agentforce-coordinate
 
 Emit one of these text blocks at the corresponding step in the workflow. Setup is presented as
-**two sequential stages** — Stage 1 (enable platform features) must finish before Stage 2 (install
-& activate agent templates). Only items with a working child skill appear — hide placeholder rows.
+**two sequential setup stages** — Stage 1 (enable platform features) must finish before Stage 2
+(install & activate agent templates). Optional Employee Agent escalation follows Stage 2 and runs
+only after the Employee agent is active. Only items with a working child skill appear — hide
+placeholder rows.
 
 ## Feature menu (Behavior step 3)
 
 ```text
 Agentforce for ITSM Setup (via service-itsm-agentic-setup-agentforce-coordinate)
 
-Here are the features available for Agentforce ITSM. Set them up in two stages —
-Stage 1 (enable) must finish before Stage 2 (install & activate):
-
-┌───┬─────────┬──────────────────────────────┬────────────────────────────────────────────────────────┬──────────┐
-│ # │ Stage   │ Item                         │ Description                                            │ Status   │
-├───┼─────────┼──────────────────────────────┼────────────────────────────────────────────────────────┼──────────┤
-│ 1 │ Stage 1 │ Agentforce Studio enablement │ Turn on org-level Agentforce, Einstein GenAI, and IT   │ Not done │
-│   │         │ (Foundation for all agents)  │ Service agent features                                 │          │
-│ 2 │ Stage 2 │ IT Service Fulfiller Agent   │ Automate actions and simplify critical asks for IT     │ Not done │
-│   │         │                              │ service fulfillers who work with incidents, problems,  │          │
-│   │         │                              │ change requests and more to resolve issues and         │          │
-│   │         │                              │ requests.                                              │          │
-│   │         │                              │ Setup: creates the agent from this template and        │          │
-│   │         │                              │ activates a version.                                   │          │
-│ 3 │ Stage 2 │ IT Service Employee Agent    │ Help employees quickly troubleshoot IT issues, raise   │ Not done │
-│   │         │                              │ service requests, and track their incidents with ease. │          │
-│   │         │                              │ Setup: creates the agent from this template and        │          │
-│   │         │                              │ activates a version.                                   │          │
-│ 4 │ Stage 2 │ Specialized Agents           │ Use the specialized templates and build agents that    │ Not done │
-│   │         │ for Employee                 │ power your employee agent. Refine the agent logic, as  │          │
-│   │         │                              │ necessary, and then activate them.                     │          │
-│   │         │                              │ Setup: pick one specialized template (e.g. Password    │          │
-│   │         │                              │ Manager, Onboarding), then create and activate that    │          │
-│   │         │                              │ standalone agent. Re-run this item to add more.        │          │
-└───┴─────────┴──────────────────────────────┴────────────────────────────────────────────────────────┴──────────┘
+Here are the features available for Agentforce ITSM. Stage 1 (enable) must finish before
+Stage 2 (install & activate). Employee Agent escalation is available after the Employee agent is active:
+
+┌───┬─────────┬──────────────────────────────┬────────────────────────────────────────────────────────┬────────────────────┬──────────┐
+│ # │ Stage   │ Item                         │ Description                                            │ Action             │ Status   │
+├───┼─────────┼──────────────────────────────┼────────────────────────────────────────────────────────┼────────────────────┼──────────┤
+│ 1 │ Stage 1 │ Agentforce Studio enablement │ Turn on org-level Agentforce, Einstein GenAI, and IT   │ Enable features    │ Not done │
+│   │         │ (Foundation for all agents)  │ Service agent features                                 │                    │          │
+│ 2 │ Stage 2 │ IT Service Fulfiller Agent   │ Automate actions and simplify critical asks for IT     │ Install + activate │ Not done │
+│   │         │                              │ service fulfillers who work with incidents, problems,  │                    │          │
+│   │         │                              │ change requests and more to resolve issues and         │                    │          │
+│   │         │                              │ requests.                                              │                    │          │
+│   │         │                              │ Setup: creates the agent from this template and        │                    │          │
+│   │         │                              │ activates a version.                                   │                    │          │
+│ 3 │ Stage 2 │ IT Service Employee Agent    │ Help employees quickly troubleshoot IT issues, raise   │ Install + activate │ Not done │
+│   │         │                              │ service requests, and track their incidents with ease. │                    │          │
+│   │         │                              │ Setup: creates the agent from this template and        │                    │          │
+│   │         │                              │ activates a version.                                   │                    │          │
+│ 4 │ Stage 2 │ Specialized Agents           │ Use the specialized templates and build agents that    │ Install + activate │ Not done │
+│   │         │ for Employee                 │ power your employee agent. Refine the agent logic, as  │                    │          │
+│   │         │                              │ necessary, and then activate them.                     │                    │          │
+│   │         │                              │ Setup: pick one specialized template (e.g. Password    │                    │          │
+│   │         │                              │ Manager, Onboarding), then create and activate that    │                    │          │
+│   │         │                              │ standalone agent. Re-run this item to add more.        │                    │          │
+│ 5 │ Post    │ Employee Agent escalation    │ Configure human handoff to the General IT queue with   │ Configure handoff  │ Not done │
+│   │ setup   │                              │ failure-threshold directives.                          │                    │          │
+└───┴─────────┴──────────────────────────────┴────────────────────────────────────────────────────────┴────────────────────┴──────────┘
 
 Reply with the numbers of the features you want to set up (one or more, e.g. `1` or `1, 2`).
 If you pick a Stage 2 template without Stage 1, I'll enable the Stage 1 foundation first.
@@ -42,7 +46,8 @@ If you pick a Stage 2 template without Stage 1, I'll enable the Stage 1 foundati
 Stage 1 (Agentforce Studio enablement) is the **foundation** — it enables the org-level platform
 features every agent is built on. Stage 2 items (the Fulfiller agent, the Employee agent, and
 Specialized Agents for Employee) are **installed from a template and activated**; they can be set up
-in any order once Stage 1 is done.
+in any order once Stage 1 is done. The post-setup Employee Agent escalation item requires the
+Employee agent to be active.
 
 **Specialized Agents for Employee** is a third Stage 2 item, shown right after the IT Service
 Employee Agent to keep the two employee options together. Both use the same child skill
@@ -55,6 +60,12 @@ Service Employee Agent), and once given a name it disambiguates a partial or amb
 chosen template names the agent it creates. The specialized templates themselves are turned on in
 Stage 1; this item is where you build and activate an agent from them.
 
+**Employee Agent escalation** is a post-setup item, shown after the Stage 2 agents. It delegates to
+`service-agentforce-human-escalation-configure` and configures the Employee agent's hand-off to a
+human — `canEscalate`, outbound routing, a staffed General IT queue, and failure-threshold
+directives. It requires the IT Service Employee Agent to be Active first, so run it only after item 3
+has succeeded.
+
 ## Post-feature progress (Behavior step 5)
 
 Example after Stage 1 (Agentforce Studio enablement) completes:
@@ -63,16 +74,18 @@ Example after Stage 1 (Agentforce Studio enablement) completes:
 Agentforce Studio — enabled successfully
 (via service-itsm-agentic-setup-agentforce-studio-configure)
 
-┌───┬─────────┬──────────────────────────────┬─────────────┐
-│ # │ Stage   │ Item                         │ Status      │
-├───┼─────────┼──────────────────────────────┼─────────────┤
-│ 1 │ Stage 1 │ Agentforce Studio enablement │ Done        │
-│   │         │ (Foundation for all agents)  │             │
-│ 2 │ Stage 2 │ IT Service Fulfiller Agent   │ Not done    │
-│ 3 │ Stage 2 │ IT Service Employee Agent    │ Not done    │
-│ 4 │ Stage 2 │ Specialized Agents           │ Not done    │
-│   │         │ for Employee                 │             │
-└───┴─────────┴──────────────────────────────┴─────────────┘
+┌───┬─────────┬───────────────────────────────┬─────────────┐
+│ # │ Stage   │ Item                          │ Status      │
+├───┼─────────┼───────────────────────────────┼─────────────┤
+│ 1 │ Stage 1 │ Agentforce Studio enablement  │ Done        │
+│   │         │ (Foundation for all agents)   │             │
+│ 2 │ Stage 2 │ IT Service Fulfiller Agent    │ Not done    │
+│ 3 │ Stage 2 │ IT Service Employee Agent     │ Not done    │
+│ 4 │ Stage 2 │ Specialized Agents            │ Not done    │
+│   │         │ for Employee                  │             │
+│ 5 │ Post    │ Employee Agent escalation     │ Not done    │
+│   │ setup   │                               │             │
+└───┴─────────┴───────────────────────────────┴─────────────┘
 
 Stage 1 (foundation) is enabled. On to Stage 2 — install and activate the IT
 Service Fulfiller agent, the IT Service Employee agent, and/or a specialized
@@ -103,16 +116,18 @@ Example — user finished after only enabling Agentforce Studio (the Stage 2 age
 Agentforce for ITSM Setup — Finished
 (via service-itsm-agentic-setup-agentforce-coordinate)
 
-┌───┬─────────┬──────────────────────────────┬─────────────┐
-│ # │ Stage   │ Item                         │ Status      │
-├───┼─────────┼──────────────────────────────┼─────────────┤
-│ 1 │ Stage 1 │ Agentforce Studio enablement │ Done        │
-│   │         │ (Foundation for all agents)  │             │
-│ 2 │ Stage 2 │ IT Service Fulfiller Agent   │ Not done    │
-│ 3 │ Stage 2 │ IT Service Employee Agent    │ Not done    │
-│ 4 │ Stage 2 │ Specialized Agents           │ Not done    │
-│   │         │ for Employee                 │             │
-└───┴─────────┴──────────────────────────────┴─────────────┘
+┌───┬─────────┬───────────────────────────────┬─────────────┐
+│ # │ Stage   │ Item                          │ Status      │
+├───┼─────────┼───────────────────────────────┼─────────────┤
+│ 1 │ Stage 1 │ Agentforce Studio enablement  │ Done        │
+│   │         │ (Foundation for all agents)   │             │
+│ 2 │ Stage 2 │ IT Service Fulfiller Agent    │ Not done    │
+│ 3 │ Stage 2 │ IT Service Employee Agent     │ Not done    │
+│ 4 │ Stage 2 │ Specialized Agents            │ Not done    │
+│   │         │ for Employee                  │             │
+│ 5 │ Post    │ Employee Agent escalation     │ Not done    │
+│   │ setup   │                               │             │
+└───┴─────────┴───────────────────────────────┴─────────────┘
 
 You have finished the items you selected. The remaining items can be
 resumed later by re-invoking this orchestrator.

package/skills/service-itsm-agentic-setup-agentforce-coordinate/scripts/verify-child-verdict.mjs

@@ -7,7 +7,7 @@
 // exit code.
 //
 // Usage:
-//   node verify-child-verdict.mjs <studio|fulfiller|employee> <verdict>
+//   node verify-child-verdict.mjs <studio|fulfiller|employee|escalation> <verdict>
 //
 // Exit 0  -> child succeeded, safe to advance the queue.
 // Exit 1  -> child failed or only partially succeeded, stop the queue.
@@ -17,12 +17,16 @@ const SUCCESS_VALUES = {
   studio: new Set(['SUCCESS']),
   fulfiller: new Set(['CREATED', 'ALREADY-CREATED', 'ACTIVATED']),
   employee: new Set(['CREATED', 'ALREADY-CREATED', 'ACTIVATED']),
+  // Employee-agent escalation leaf (service-agentforce-human-escalation-configure, IT scenario inputs)
+  // emits CONFIGURED when every deterministic surface is satisfied; a re-run is an
+  // idempotent CONFIGURED. INCOMPLETE/BLOCKED stop the queue.
+  escalation: new Set(['CONFIGURED', 'ALREADY-CONFIGURED']),
 };
 
 const [child, verdict] = process.argv.slice(2);
 
 if (!child || !verdict || !SUCCESS_VALUES[child]) {
-  process.stderr.write('usage: node verify-child-verdict.mjs <studio|fulfiller|employee> <verdict>\n');
+  process.stderr.write('usage: node verify-child-verdict.mjs <studio|fulfiller|employee|escalation> <verdict>\n');
   process.exit(2);
 }
 

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

@@ -0,0 +1,96 @@
+---
+name: service-omni-agent-users-create
+description: "Create reusable agent users for Omni-Channel setup and routing validation. TRIGGER when users ask to create Omni agents, provision Omni test users, seed sandbox users for routing, create Omni-Channel routing agents, or repair missing demo agents. DO NOT TRIGGER for queue membership, permission-set assignment, or supervisor-user creation."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-base-settings-configure"
+    - "service-omni-channel-setup-coordinate"
+    - "service-omni-permission-set-assign"
+    - "service-omni-queue-members-assign"
+    - "service-omni-supervisor-users-create"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.9"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-agent-users-create
+
+Create N agent users on a Salesforce org via Anonymous Apex so Omni-Channel has agents to route work to. Usernames follow a deterministic per-org pattern, detection is SOQL-based, and the skill inserts only the users that are missing — so it is safe to re-run. It is invoked by `service-omni-channel-setup-coordinate` after `service-omni-base-settings-configure` enables Omni-Channel; assigning permission sets (`service-omni-permission-set-assign`) and adding users to queues (`service-omni-queue-members-assign`) are separate leaves. Supervisor users come from `service-omni-supervisor-users-create`.
+
+## Inputs
+
+Confirm once, up front:
+
+- `org-alias` (required, no default) — must resolve via `sf org display`.
+- User count (optional, default `3`, range `1..10`).
+- Profile name (optional, default `Standard User` for portability). The coordinator overrides this to a Service Cloud profile so agents consume Service Cloud licenses; on many CDOs the Salesforce license pool is saturated while Service Cloud has free slots.
+
+Usernames and passwords are never accepted from the operator — both are generated (usernames from the org suffix, passwords via Anonymous Apex). Operator-supplied credentials would break re-run detection and risk weak or leaked secrets.
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI (My Domain URL, not `.lightning.force.com`), Service Cloud license present, `sf` CLI ≥ 2.139.6.
+- The executing user has `PermissionsModifyAllData` and `PermissionsManagePasswordPolicies` (standard on System Administrator).
+- **Production guardrail:** the detect script computes `safe_to_write` as `IsSandbox` OR `TrialExpirationDate != null` OR `OrganizationType` in {Developer Edition, Base Edition}, and the skill blocks with no override when it is false. CDOs, scratch orgs, and dev orgs are permitted.
+
+**Password handling (fail-closed).** Passwords are set by Anonymous Apex `System.setPassword` (`sf user password generate` cannot target Apex-inserted users — it fails with `NamedOrgNotFoundError`). The password literal appears in the inline executeAnonymous debug log and, only when a debug-log TraceFlag is active for the running user, in a queryable `ApexLog`. The wrapper therefore fails closed *before* the first `System.setPassword`: it proves via a SOQL-filtered Tooling API query (`ExpirationDate > now`) that no active TraceFlag exists. If safety cannot be positively proven — the running user is unresolved, the query fails or is unparseable, or any active TraceFlag exists — it generates no password at all; the user is left ACTIVE, flagged `password_status:"reset_required"`, and a `security_warning` explains why. It never deletes logs, so no plaintext can reach an `ApexLog` and unrelated audit logs are untouched. If `System.setPassword` itself fails for a user, that user is kept ACTIVE and flagged for reset.
+
+## Run
+
+```bash
+# read-only preview (never writes)
+bash scripts/detect-and-create.sh plan <org-alias> [count] [profile-name]
+# detect, enforce safe_to_write, then insert only the missing users
+bash scripts/detect-and-create.sh run  <org-alias> [count=3] [profile-name="Standard User"]
+```
+
+`detect-and-create.sh` is the canonical entry point: it re-runs detection, enforces the production guard, and only then inserts. Do not call `scripts/run-create.sh` directly — it is internal and does not enforce the guard on its own.
+
+## Behavior
+
+**Detection.** The detector derives an 8-char suffix from `Organization.Id` (`substring(10,18)`, lowercased), resolves the profile by name, and queries `User` for `agent{i}.<suffix>@example.com` to find which of the `count` slot indexes are occupied. A stable, deterministic pattern is what makes re-runs idempotent — the suffix is never a timestamp or UUID.
+
+**Insertion.** The Apex loads `assets/create-users.apex.template`, substitutes `__COUNT__`/`__PROFILE_ID__`/`__SUFFIX__`, and inserts only the missing indexes. It re-checks existing users inside the transaction, which prevents a single run from double-inserting; across *concurrent* runs the in-transaction check is not a guarantee (both can pass their pre-query before either commits), so duplicate protection there relies on the global username-uniqueness constraint plus the `DUPLICATE_USERNAME` retry (see references/apex-template-notes.md). It enables the Service Cloud feature (`UserPermissionsSupportUser=true`) so users can go online in Omni; if the profile's license does not allow it, the Apex strips the flag and retries (users are still created, but need a Service-Cloud-license profile for full Omni). Each created user is reported via `AGENT_USER_CREATED|<id>|<username>|<email>` (no password in the marker — passwords are set by the separate `System.setPassword` submission).
+
+**Verification.** After insertion the detector re-runs and must show `missing_count == 0`; otherwise the skill fails (the Apex reported success but the users did not persist).
+
+## Output contract
+
+`detect-and-create.sh` emits a single JSON object with `status` ∈ `created` | `partial` | `reused` | `action_needed` | `blocked`, plus `detect` (mirrors the detector), `create` (mirrors the inserter, `null` when nothing was created), top-level `reused_users`, `created_count`, `reused_count`, `total_present_after`, `users_needing_password_reset`, `action_required`, and `safe_to_write`. The coordinator combines `reused_users` with newly created users so mixed runs configure presence and skills for the complete requested agent set.
+
+- `created` — every missing index landed with a working password.
+- `partial` — some landed but not all, or any user needs a manual password reset, or inactive occupants were found.
+- `reused` — all requested users already existed; nothing created.
+- `action_needed` — plan mode only; reports missing indexes without writing.
+- `blocked` — precondition failed (`safe_to_write=false`, unresolved profile/suffix, or nothing inserted).
+
+`create.created_users[].password` is populated only for users created this run whose `System.setPassword` succeeded; `password_status:"reset_required"` means the user is ACTIVE but has no working password yet. Exit code is 0 for `created`/`partial`/`action_needed`/`reused`, 1 for `blocked`.
+
+Generated passwords are a secret: the returned JSON is the only place they appear. Any caller that persists stdout must write it only to a restricted `CREDENTIALS.json` (mode 0600), redact it from every other artifact, and delete it after distribution — the coordinator does this automatically; standalone callers own it. Reused users' passwords are not retrievable; recover via Setup → Users → Reset Password.
+
+## Limitations
+
+- Username pattern and org suffix are fixed and never operator-configurable — that determinism is what enables idempotent re-runs.
+- Creates only agent users on the given profile; it never deletes, deactivates, or mutates existing users.
+- Common User errors (`DUPLICATE_USERNAME`, `INVALID_EMAIL`, `LICENSE_LIMIT_EXCEEDED`) are translated into operator-friendly messages rather than surfaced raw.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/apex-patterns.md` | Before running the Apex — Apex structure, User field defaults, password policy, and the profile-localization risk |
+| `references/apex-template-notes.md` | When user creation returns a duplicate, license, or password error — explains template substitutions and retry behavior |
+| `assets/create-users.apex.template` | Loaded by `scripts/run-create.sh` when missing agent users must be inserted |
+| `scripts/detect-existing.sh` | Loaded by the canonical entry point for the read-only org, profile, safety, and existing-user checks |
+| `scripts/tests/test_user_create_security.py` | Run after changing the user-creation scripts to verify production refusal and password-handling contracts |