@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-agentforce-human-escalation-configure/references/classifier-contracts.md

@@ -0,0 +1,103 @@
+# Escalation classifier contracts
+
+Reference material for the deterministic Node classifiers under `scripts/`. Keeping the
+pass/fail logic in these scripts (not in bash or model prose) satisfies authoring standard
+A9 and makes each verdict unit-testable org-free.
+
+## `classify-agent-active.mjs`
+
+Gates the write: escalation can only be wired onto an agent that exists AND whose latest
+`BotVersion` is `Active`.
+
+Input is the file path to the JSON stdout of:
+
+```bash
+sf data query -q "SELECT Id,DeveloperName,MasterLabel,
+  (SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1)
+  FROM BotDefinition WHERE DeveloperName='<developerName>'" --target-org <org> --json
+```
+
+Emits: `{ exists, active, agentId, developerName, latestVersionId, latestVersionStatus, ready, reason }`
+— `ready` is true only when `exists && active`. Exit 0 on a parseable body (verdict is in
+the payload); exit 3 on an unparseable/failed query so the workflow surfaces the raw error
+rather than assuming NOT-READY.
+
+## `extract-outbound-route.mjs`
+
+Couples `outboundRouteName` + `outboundRouteType` from WITHIN the same
+`outboundRouteConfigs` block so a bundle cannot pass by carrying an unrelated name and type
+in different blocks. The compiled `GenAiPlannerBundle` nests the route in a planner surface:
+
+```xml
+<plannerSurfaces>
+    <surfaceType>Messaging</surfaceType>        <!-- or CustomerWebClient for MIAW -->
+    <outboundRouteConfigs>
+        <escalationMessage>…</escalationMessage>
+        <outboundRouteName>Human_Escalation_Outbound_Flow</outboundRouteName>
+        <outboundRouteType>OmniChannelFlow</outboundRouteType>
+    </outboundRouteConfigs>
+</plannerSurfaces>
+```
+
+Emits `{ name, type, surface, sameBlock, messagingSurface }` for the block matched by the
+expected flow name (or the first block if none matches). `sameBlock=true` means name+type
+came from the same block; `messagingSurface=true` means it sits on a Messaging-class
+surface. Exit 0 on any parseable input (missing file => empty result); exit 2 on bad usage.
+
+## `patch-escalation-surfaces.mjs`
+
+Schema-aware, loss-less, idempotent in-place patcher for the two doc-driven surfaces. It
+only ever touches the two target elements, never reorders surrounding metadata, and
+refuses (exit 4) rather than guess when no safe insertion point exists.
+
+**XSD order (authoritative — `GenAiPlannerBundle.json` wsdl_segment):**
+
+- `AiPlannerSurfaceDef` (`<plannerSurfaces>`): `adaptiveResponseAllowed?`,
+  `callRecordingAllowed?`, `outboundRouteConfigs*`, `surface`, `surfaceType` — a NEW
+  `<outboundRouteConfigs>` MUST be inserted BEFORE `<surface>` (never appended after it).
+- `AiPlannerSurfOtbdRouteDef` (`<outboundRouteConfigs>`): `escalationMessage?`,
+  `outboundRouteName`, `outboundRouteType`.
+- `GenAiPlugin` / `GenAiLocalPlugin`: `aiPluginUtterances*`, `canEscalate?`,
+  `description?`, `developerName`, … — `<canEscalate>` MUST be inserted AFTER the last
+  `<aiPluginUtterances>` and BEFORE `<description>` (or, if absent, before the first
+  following required sibling — `developerName`/`masterLabel`/…).
+
+Modes:
+
+```bash
+node patch-escalation-surfaces.mjs canEscalate   <genAiPlugin-xml-file>
+node patch-escalation-surfaces.mjs outboundRoute <genAiPlannerBundle-xml-file> <flowApiName> [escalationMessage]
+```
+
+Patched IN PLACE. Exit 0 on success (prints a short JSON summary), 2 on bad usage, 4 when
+no safe patch point is found (nothing written).
+
+## `verify-escalation-config.mjs`
+
+Renders the single deterministic verdict from an evidence object assembled by
+`verify-and-configure.sh` (retrieved XML greps + SOQL reads).
+
+`evidence.json` shape (all keys optional; missing => treated as not-satisfied):
+
+| key | meaning |
+| --- | --- |
+| `canEscalate` | escalation topic flag set |
+| `outboundRouteName` | route name on the bundle |
+| `outboundRouteType` | must equal `OmniChannelFlow` |
+| `outboundRouteSameBlock` | name+type from the SAME config block |
+| `outboundRouteMessagingSurface` | block sits on a Messaging planner surface |
+| `expectedFlowName` | expected outbound flow name |
+| `flowActiveVersionId` | non-empty => flow active |
+| `queueId` | non-empty => queue exists |
+| `queueSobjectPresent` | context object bound to the queue |
+| `queueHasActiveDirectUserMember` | ≥1 active DIRECT User member (necessary, not sufficient — Omni perm + presence access are proven only at runtime) |
+| `queueRoutingConfigPresent` | QRC exists |
+| `queueRoutingConfigBound` | `Group.QueueRoutingConfigId` points at the QRC |
+| `agentActive` | latest BotVersion active |
+| `thresholdAuthored` | directive policy authored (not a counter) |
+| `defaultFailureThreshold` | numeric consecutive-failure threshold rendered into the directive (evidence only, never a gate) |
+
+Emits `{ verdict, deterministicPass, directivePass, checks[], missing[] }` where `verdict`
+is `CONFIGURED` | `INCOMPLETE`. The deterministic surfaces gate `CONFIGURED`; the threshold
+directive is reported separately (never blocks the headless verdict — it is eval-verified,
+not metadata-verified). Exit 0 on a parseable body; exit 3 on unparseable input.

package/skills/service-agentforce-human-escalation-configure/references/escalation-mechanism.md

@@ -0,0 +1,63 @@
+# Escalation mechanism reference
+
+Agent → human escalation in Agentforce is assembled from three declarative surfaces plus
+one instruction surface. Only the first three are deterministically writable and verifiable
+via the Metadata/Data API; the fourth (threshold policy) is directive text verified by
+eval, and the actual conversational trigger is manual/runtime.
+
+## 1. `canEscalate` on the escalation topic (`GenAiPlugin`)
+
+The agent topic that represents "hand off to a human" must have `<canEscalate>true</canEscalate>`.
+Retrieve the topic, set the flag, redeploy.
+
+```bash
+sf project retrieve start --target-org "$ORG" \
+  --metadata "GenAiPlugin:${ESCALATION_TOPIC_API_NAME}" --target-metadata-dir /tmp/esc
+# edit <canEscalate>true</canEscalate> in the retrieved -meta.xml
+sf project deploy start --target-org "$ORG" --metadata "GenAiPlugin:${ESCALATION_TOPIC_API_NAME}"
+```
+
+Verify (the retrieved XML must contain `<canEscalate>true</canEscalate>`). There is no
+SOQL object for `canEscalate`; the source of truth is the retrieved metadata.
+
+## 2. `outboundRouteConfigs` on the agent's Messaging planner surface (`GenAiPlannerBundle`)
+
+The `GenAiPlannerBundle` for the agent carries the Messaging surface. Its
+`outboundRouteConfigs` block wires the escalation to an Omni-Channel outbound flow:
+
+```xml
+<outboundRouteConfigs>
+    <escalationMessage>Transferring you to a live support agent.</escalationMessage>
+    <outboundRouteName>Human_Escalation_Outbound_Flow</outboundRouteName>
+    <outboundRouteType>OmniChannelFlow</outboundRouteType>
+</outboundRouteConfigs>
+```
+
+Retrieve the bundle, add/update the block on the Messaging surface, redeploy. `outboundRouteName`
+must equal the active outbound `RoutingFlow` API name (see #3).
+
+## 3. Outbound QueueBased `RoutingFlow`
+
+The bundled asset `assets/force-app/main/default/flows/Human_Escalation_Outbound_Flow.flow-meta.xml`
+is a QueueBased outbound flow template that routes the escalated conversation to the human
+queue. It looks the queue up by `DeveloperName` at runtime (no hardcoded Id), so it is
+portable across orgs. Tokens `__FLOW_DEVELOPER_NAME__`, `__FLOW_LABEL__`,
+`__QUEUE_DEVELOPER_NAME__`, `__SERVICE_CHANNEL_DEV_NAME__`, `__SERVICE_CHANNEL_LABEL__`
+are substituted before deploy.
+
+After deploy, `FlowDefinitionView.ActiveVersionId` for the flow must be non-null.
+
+## 4. Human queue
+
+The escalation target is a queue whose `QueueSobject` includes the routed context object
+(`MessagingSession` by default, for Enhanced Chat / MIAW), plus a `QueueRoutingConfig`. See
+[queue-resolution.md](../../service-agentforce-channel-configure/references/queue-resolution.md)
+for the create-or-adopt recipe. Provision any broader routing infrastructure through an
+approved Omni setup workflow before running this skill.
+
+## Handoff to `service-agentforce-channel-configure`
+
+Inbound transport (`sessionHandlerAsa` on the MessagingChannel, Branch A) and the outbound
+`connection customer_web_client:` connection block on the agent are owned by
+`service-agentforce-channel-configure`. This skill focuses on the escalation-specific
+surfaces (#1, #2, #3, #4) and the threshold policy, delegating transport wiring to that skill.

package/skills/service-agentforce-human-escalation-configure/references/failure-policy.md

@@ -0,0 +1,44 @@
+# Failure-threshold policy (native, directive-based)
+
+## Why this is not a metadata counter
+
+Agentforce does not expose a metadata field or setting that counts "consecutive failed
+turns" and escalates automatically. The "escalate after two failures" behaviour is a
+**planner policy expressed as instruction text** in the agent's Agent Script (NGA
+authoring model). This is the platform-native representation the user selected.
+
+Consequences:
+
+- The threshold is **authored, not enforced by a counter**. The bundled template
+  [`assets/escalation-thresholds.instructions.md`](../assets/escalation-thresholds.instructions.md)
+  is the source directive text.
+- It is **verified by an ADK eval rubric** (does the agent escalate on the 2nd failure? on
+  the 1st failure for password reset?) and a **documented manual conversation test** — never
+  by a deterministic metadata round-trip.
+- The `verify-and-configure.sh` verdict therefore reports the threshold as `directive`
+  (authored / not-authored), distinct from the `deterministic` config surfaces
+  (`canEscalate`, `outboundRouteConfigs` name+type coupling on the Messaging surface, outbound
+  flow Active, queue + QueueSobject + bound QueueRoutingConfig, ≥1 active human member, agent Active).
+
+## Recommended thresholds
+
+The threshold is a **caller input**, not a fixed constant. The values below are defaults;
+a scenario that mandates a different number (e.g. a narrative requiring escalation after
+**three** consecutive failures) supplies its own value via the skill input — no code change
+is needed.
+
+| Scenario | Threshold | Rationale |
+|---|---|---|
+| Default (any unresolved request) | 2 consecutive failures | Give the agent one retry before handing off |
+| Password reset / credential issues | 1 failure | Time-sensitive; do not retry repeatedly |
+| Caller-specified | any N | Whatever the scenario's authoritative requirement is (pass N as the input) |
+
+## Authoring steps
+
+1. Substitute tokens in the template (`__DEFAULT_FAILURES__=2`, `__RESET_TOPIC_LABEL__`,
+   `__ESCALATION_MESSAGE__`).
+2. Add the default directive to the agent's global/system instructions.
+3. Add the per-topic override to the password-reset topic instructions.
+4. Republish + reactivate the agent (`sf agent validate|publish|activate ... --target-org $ORG`).
+5. Confirm via the eval rubric and the manual test in
+   [runtime-verification.md](./runtime-verification.md).

package/skills/service-agentforce-human-escalation-configure/references/nga-escalation.md

@@ -0,0 +1,57 @@
+# Next-gen (NGA) escalation — detection, surface split, and verdict
+
+The classic escalation surface (`GenAiPlannerBundle.outboundRouteConfigs` + `GenAiPlugin.canEscalate`) does not exist on next-gen authoring (NGA) orgs. NGA agents are defined by `AiAuthoringBundle` (Agent Script), and the escalation surface moves into the bundle. This skill supports both models from one code path; only the agent-side surface differs.
+
+## Detection (Phase 1b)
+
+`sf org list metadata-types` identifies the model surfaces available in the org. When both surfaces exist, the skill retrieves the requested agent from each surface and classifies that specific target rather than applying an org-wide default:
+
+| Metadata types exposed | `authoring_model` | Agent surface authored/verified |
+|---|---|---|
+| Requested agent is found only in `GenAiPlannerBundle` | `classic` | `canEscalate` + `outboundRouteConfigs` |
+| Requested agent is found only in `AiAuthoringBundle` | `nga` | `@utils.escalate` (Service) / create-record (Employee) |
+| Requested agent is found in both surfaces | `ambiguous` | — (skill blocks before any write) |
+| Requested agent is found in neither surface while both models exist | `none` | — (skill blocks before any write) |
+
+`AUTHORING_MODEL_OVERRIDE=classic|nga` explicitly pins the branch when the target is genuinely ambiguous or metadata retrieval is inconclusive. There is no classic-first default: an NGA target in a mixed-model org stays NGA.
+
+## Why classic ≠ NGA (not a straight port)
+
+The classic skill's value was deterministically authoring + verifying a failure-threshold outbound route on one metadata surface. NGA splits that into pieces of different natures:
+
+| Classic single surface | NGA equivalent | Deterministic? |
+|---|---|---|
+| `outboundRouteConfigs` → named queue | channel → queue Omni routing (the routing half this skill builds) | yes |
+| failure-threshold trigger | Agent Script instruction / `@utils.escalate` action | no — prompt-led (a directive) |
+| (n/a for employee agents) | Employee agent → create Incident/Case action → Omni-route that record | yes |
+
+There is no numeric "escalate after N failures" field in Agent Script; the threshold stays a directive (the same boundary the classic path already uses).
+
+## Service vs Employee split
+
+- **Service agent** — declares `connection messaging:` and can call `@utils.escalate` for a live hand-off routed through the messaging connection to the queue.
+- **Employee agent** — cannot declare `connection messaging:` or use `@utils.escalate`. Its escalation surrogate is an action that creates a routable record (Case/Incident/ticket) which then Omni-routes to the human queue.
+
+`scripts/classify-nga-escalation.mjs` walks the retrieved `AiAuthoringBundle` (in-process, so it never invokes `find` — the sandbox blocks `find -exec`'s `ARG_MAX` probe) and returns:
+
+To avoid a false `CONFIGURED`, it scans **only Agent Script** (`*.agent` files, or any file whose content declares `start_agent`), **strips comments** (`/* */`, whole-line `//`/`#`), and proves reachability **per agent block**: the escalation surface must live in the same `start_agent` block as its trigger, under a `reasoning: actions:` section (a line more indented than the `actions:` header). A commented-out block, prose mention, cross-block match, or unrelated file no longer satisfies the surface — when reachability cannot be proven it reports `escalationSurfacePresent:false` (→ caller stays `INCOMPLETE`). An unreadable/missing retrieve dir exits `3` (inconclusive), never an empty exit `0`.
+
+```text
+{ agentType, bundleFound, connectionMessaging, escalateActionPresent, createRecordActionPresent, escalationSurfacePresent }
+```
+
+- `agentType`: `service` if `connection messaging:` present, else `employee` (or `unknown` when no bundle was retrieved).
+- `escalationSurfacePresent`: `escalateActionPresent` for Service, `createRecordActionPresent` for Employee. `createRecordActionPresent` is a heuristic (action refs matching create + case/incident/ticket/record) — treat a false negative as "author via agentforce-generate", never as a hard failure of the agent.
+
+## NGA verdict set
+
+`verify-escalation-config.mjs` keeps the model-agnostic routing checks (`outboundFlowActive`, `humanQueue`, `queueSobject`, `queueHasActiveDirectUserMember`, `queueRoutingConfig`, `queueRoutingConfigBound`, `agentActive`) and swaps the surface checks:
+
+- classic → `canEscalate` + `outboundRouteConfigs`
+- nga → `ngaEscalationSurface` (from `escalationSurfacePresent`)
+
+`thresholdDirective` remains a directive check in both. `CONFIGURED` requires all deterministic checks; the threshold is reported separately.
+
+## Authoring delegation
+
+This skill **verifies** the NGA surface; it does not mutate Agent Script. When `ngaEscalationSurface` is missing the verdict is `INCOMPLETE` and `next_steps` points to `agentforce-generate` to author the surface: 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. Re-run afterward to reach `CONFIGURED`.

package/skills/service-agentforce-human-escalation-configure/references/runtime-verification.md

@@ -0,0 +1,72 @@
+# Runtime & manual verification checklist
+
+The deterministic config surfaces are verified headlessly by `verify-and-configure.sh`
+(see the JSON verdict). The conversational behaviour and context preservation **cannot be
+driven headlessly** and must be confirmed with a live conversation (per the EC V2 reference).
+
+## A. Deterministic config verdict (headless — done by the skill)
+
+`verify-and-configure.sh` round-trips and asserts:
+
+- `canEscalate=true` on the escalation topic (`GenAiPlugin`).
+- `outboundRouteConfigs` on the `GenAiPlannerBundle` Messaging planner surface couples
+  `outboundRouteName` (= the outbound flow API name) to `outboundRouteType=OmniChannelFlow`
+  in the SAME block on a Messaging-class surface.
+- Outbound `RoutingFlow` `ActiveVersionId` is non-null (`FlowDefinitionView`).
+- The human queue exists with a `QueueSobject` for the context object (`MessagingSession`
+  by default), a `QueueRoutingConfig` bound to the queue (`Group.QueueRoutingConfigId`), and
+  **at least one active human member** (`GroupMember` resolving to an active `User`).
+- The agent's latest `BotVersion` is `Active` after republish.
+
+## B. Threshold policy (eval rubric — not a counter)
+
+- ADK eval `TwoFailureThreshold`: on the 2nd consecutive failed attempt the agent escalates.
+- ADK eval `PasswordResetOverride`: on the 1st failed password-reset attempt the agent escalates.
+
+## C. Manual conversation test (runtime only)
+
+1. Open the Enhanced Chat / MIAW deployment as an end user.
+2. Ask the agent something it can resolve — confirm no premature escalation.
+3. Trigger two consecutive failed attempts on the same request — confirm the agent emits
+   the escalation message and hands off.
+4. Confirm an `AgentWork` record is created against the human queue:
+
+```bash
+sf data query --target-org "$ORG" --json \
+  --query "SELECT Id, Status, ServiceChannel, WorkItemId FROM AgentWork ORDER BY CreatedDate DESC LIMIT 5"
+```
+
+5. Confirm **context preservation**: the human agent receives the same `MessagingSession`
+   with the full prior transcript (same `MessagingSession.Id`, not a new session).
+
+```bash
+sf data query --target-org "$ORG" --json \
+  --query "SELECT Id, Status, Origin FROM MessagingSession ORDER BY LastModifiedDate DESC LIMIT 5"
+```
+
+Context preservation and `AgentWork` creation are runtime facts — record the result in the
+run notes; they are not part of the headless verdict.
+
+## D. Real-org proof record — 2026-08-17 (`sdb38` trial CDO)
+
+Read-only §7 verification run against a non-production org (`IsSandbox=false`,
+`TrialExpirationDate` non-null ⇒ `safe_to_write=true`). IDs abbreviated.
+
+| Check | Result |
+| --- | --- |
+| Org safety | PASS — Enterprise trial CDO, non-production |
+| Human queue + QRC bind | PASS — `General_IT_Queue`, `QueueRoutingConfigId=0K9…00BA` |
+| `QueueSobject` context object | PASS — `MessagingSession` |
+| Active human members | PASS — 2 active users |
+| Outbound `RoutingFlow` active | PASS — `ActiveVersionId=301…pYBB` |
+| Active MessagingChannels | PASS — 4 active |
+| Queue-based routing runtime | PASS — `PendingServiceRouting` rows `IsReadyForRouting=true`, `RoutingType=QueueBased`; `AgentWork` rows `Closed`/`Declined` on `sfdc_livemessage`; `MessagingSession` rows `Ended`/`Waiting` |
+
+**Not proven headlessly (manual step required):**
+
+- Agent-authoring side (`canEscalate` + `outboundRouteConfigs` on a live Agentforce planner
+  bundle) — the default agent developer name was absent on this org; running the authoring
+  path requires an explicit `AGENT_DEVELOPER_NAME` (e.g. an Active `ExternalCopilot` agent).
+- Phase 4 conversational escalation — must be driven through a live Enhanced Messaging
+  conversation (section C). Queue-based routing→agent-accept is already demonstrated above,
+  but the agent→human handoff trigger itself is a manual runtime confirmation.

package/skills/service-agentforce-human-escalation-configure/scripts/classify-agent-active.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Precondition classifier: BotDefinition+latest BotVersion query JSON → { exists, active, ready, ... }; ready only when exists && active; exit 3 on unparseable. Query/output shape: references/classifier-contracts.md.
+
+import { readFileSync } from 'node:fs';
+
+const [queryPath, developerName] = process.argv.slice(2);
+if (!queryPath || !developerName) {
+  process.stderr.write('usage: node classify-agent-active.mjs <bot-query.json> <developerName>\n');
+  process.exit(2);
+}
+
+let data;
+try {
+  const text = readFileSync(queryPath, 'utf8').trim();
+  data = text ? JSON.parse(text) : null;
+} catch {
+  process.stderr.write(`error: could not read/parse ${queryPath}\n`);
+  process.exit(3);
+}
+
+if (!data || (typeof data.status === 'number' && data.status !== 0) || data.result === undefined) {
+  process.stderr.write('error: query did not return a results envelope; surface the raw CLI error and stop\n');
+  process.exit(3);
+}
+
+const records = Array.isArray(data.result?.records) ? data.result.records : [];
+const wantedLower = String(developerName).toLowerCase();
+const matches = records.filter((r) => String(r?.DeveloperName ?? '').toLowerCase() === wantedLower);
+const exists = matches.length > 0;
+
+const latestVersion = exists ? matches[0]?.BotVersions?.records?.[0] ?? null : null;
+const latestVersionStatus = latestVersion?.Status ?? null;
+const active = exists && latestVersionStatus === 'Active';
+
+let reason;
+if (!exists) reason = 'agent-not-found';
+else if (!active) reason = 'agent-inactive';
+else reason = 'ready';
+
+process.stdout.write(JSON.stringify({
+  exists,
+  active,
+  agentId: exists ? (matches[0].Id ?? null) : null,
+  developerName,
+  latestVersionId: latestVersion?.Id ?? null,
+  latestVersionStatus,
+  ready: exists && active,
+  reason,
+}, null, 2) + '\n');

package/skills/service-agentforce-human-escalation-configure/scripts/classify-nga-escalation.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Classify the escalation surface of a retrieved next-gen (AiAuthoringBundle) agent -> { agentType, connectionMessaging, escalateActionPresent, createRecordActionPresent, escalationSurfacePresent, bundleFound }. Detection rules + Service-vs-Employee rationale: references/nga-escalation.md. Exit 3 on an unreadable dir.
+//
+// Hardening (avoids false CONFIGURED): only actual Agent Script (.agent files, or any file whose
+// content declares `start_agent`) is scanned; comments are stripped; and the escalation surface must
+// live in the SAME agent block as its trigger, under a `reasoning: actions:` section - a comment,
+// example, or unrelated file can no longer satisfy the match. When reachability cannot be proven the
+// surface is reported absent (escalationSurfacePresent:false) so the caller stays INCOMPLETE.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const [retrieveDir] = process.argv.slice(2);
+if (!retrieveDir) {
+  process.stderr.write('usage: node classify-nga-escalation.mjs <retrieve-dir>\n');
+  process.exit(2);
+}
+
+// The TOP dir must be readable — an unreadable/missing retrieve dir is inconclusive, not "no surface"
+// (file contract: exit 3). Nested unreadable files are skipped below (a single bad file is not fatal).
+try {
+  if (!statSync(retrieveDir).isDirectory()) throw new Error('not a directory');
+  readdirSync(retrieveDir);
+} catch {
+  process.stderr.write(`error: could not read ${retrieveDir}\n`);
+  process.exit(3);
+}
+
+// Strip comments so a commented-out / example escalation block cannot satisfy the regex: remove
+// /* ... */ blocks, then drop whole-line // and # comments (leaves inline // inside strings alone).
+function stripComments(text) {
+  const noBlock = text.replace(/\/\*[\s\S]*?\*\//g, '');
+  return noBlock
+    .split('\n')
+    .map((line) => {
+      const t = line.trimStart();
+      return t.startsWith('//') || t.startsWith('#') ? '' : line;
+    })
+    .join('\n');
+}
+
+// Walk the retrieve dir in-process (no `find`; the sandbox blocks find -exec's ARG_MAX probe) and
+// collect ONLY Agent Script: files named *.agent, or any file whose content declares `start_agent`
+// (covers a differently-named script). bundleFound also counts *.bundle-meta.xml so a bundle with no
+// readable script still reports bundleFound:true (→ agentType resolvable, surface simply absent).
+function collect(dir, acc) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return acc;
+  }
+  for (const name of entries) {
+    const full = join(dir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      collect(full, acc);
+      continue;
+    }
+    if (!st.isFile()) continue;
+    const isAgentExt = /\.agent$/i.test(name);
+    if (isAgentExt || /\.bundle-meta\.xml$/i.test(name)) acc.bundleFound = true;
+    let raw;
+    try {
+      raw = readFileSync(full, 'utf8');
+    } catch {
+      continue; // skip unreadable/binary file
+    }
+    if (isAgentExt || /^[ \t]*start_agent\b/im.test(raw)) {
+      acc.scripts.push(stripComments(raw));
+    }
+  }
+  return acc;
+}
+
+const scanned = collect(retrieveDir, { scripts: [], bundleFound: false });
+
+// Split concatenated Agent Script into per-agent blocks. Each `start_agent <name>:` opens a block that
+// runs until the next start_agent (or EOF). Reachability is proven per block, not across the file.
+function splitAgentBlocks(scriptText) {
+  const blocks = [];
+  let cur = null;
+  for (const line of scriptText.split('\n')) {
+    if (/^\s*start_agent\b/i.test(line)) {
+      if (cur) blocks.push(cur);
+      cur = [line];
+    } else if (cur) {
+      cur.push(line);
+    }
+  }
+  if (cur) blocks.push(cur);
+  return blocks;
+}
+
+// True when `re` matches an action line inside a `reasoning: actions:` section of the block — i.e. the
+// match is more indented than the `actions:` header it lives under (a real action, not prose/an example).
+function actionMatches(blockLines, re) {
+  let actionsIndent = -1;
+  for (const line of blockLines) {
+    if (line.trim() === '') continue;
+    const indent = line.length - line.trimStart().length;
+    if (actionsIndent >= 0) {
+      if (indent > actionsIndent) {
+        if (re.test(line)) return true;
+        continue;
+      }
+      actionsIndent = -1; // dedented out of the actions section; re-check this line as a new header
+    }
+    if (/^actions\s*:/.test(line.trim())) actionsIndent = indent;
+  }
+  return false;
+}
+
+const CREATE_RECORD_RE =
+  /@actions\.[A-Za-z0-9_]*create[A-Za-z0-9_]*(case|incident|ticket|record)|create[_-]?(case|incident|ticket)\b/i;
+const ESCALATE_RE = /@utils\.escalate\b/i;
+const MESSAGING_RE = /^\s*connection\s+messaging\s*:/im;
+
+let connectionMessaging = false;
+let escalateActionPresent = false;
+let createRecordActionPresent = false;
+let serviceSurface = false; // messaging + reachable @utils.escalate in the SAME block
+let employeeSurface = false; // no messaging + reachable create-record action in the block
+
+for (const script of scanned.scripts) {
+  for (const block of splitAgentBlocks(script)) {
+    const text = block.join('\n');
+    const hasMessaging = MESSAGING_RE.test(text);
+    const hasEscalate = actionMatches(block, ESCALATE_RE);
+    const hasCreateRecord = actionMatches(block, CREATE_RECORD_RE);
+    connectionMessaging = connectionMessaging || hasMessaging;
+    escalateActionPresent = escalateActionPresent || hasEscalate;
+    createRecordActionPresent = createRecordActionPresent || hasCreateRecord;
+    if (hasMessaging && hasEscalate) serviceSurface = true;
+    if (!hasMessaging && hasCreateRecord) employeeSurface = true;
+  }
+}
+
+// Service agents escalate via @utils.escalate; Employee agents lack messaging and must create a
+// routable record instead. Without a retrieved bundle the type is unknown.
+let agentType = 'unknown';
+if (scanned.bundleFound) agentType = connectionMessaging ? 'service' : 'employee';
+
+let escalationSurfacePresent = false;
+if (agentType === 'service') escalationSurfacePresent = serviceSurface;
+else if (agentType === 'employee') escalationSurfacePresent = employeeSurface;
+
+process.stdout.write(
+  JSON.stringify(
+    {
+      agentType,
+      bundleFound: scanned.bundleFound,
+      connectionMessaging,
+      escalateActionPresent,
+      createRecordActionPresent,
+      escalationSurfacePresent,
+    },
+    null,
+    2,
+  ) + '\n',
+);

package/skills/service-agentforce-human-escalation-configure/scripts/extract-outbound-route.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Extracts outbound-route wiring from a retrieved GenAiPlannerBundle, coupling routeName+routeType within one outboundRouteConfigs block → { name, type, surface, sameBlock, messagingSurface }; exit 2 on bad usage. Details: references/classifier-contracts.md.
+
+import { readFileSync } from 'node:fs';
+
+const [xmlPath, expectedFlow = ''] = process.argv.slice(2);
+if (!xmlPath) {
+  process.stderr.write('usage: node extract-outbound-route.mjs <bundle-xml-file> <expected-flow-name>\n');
+  process.exit(2);
+}
+
+const empty = { name: '', type: '', surface: '', sameBlock: false, messagingSurface: false };
+
+let xml = '';
+try {
+  xml = readFileSync(xmlPath, 'utf8');
+} catch {
+  process.stdout.write(JSON.stringify(empty) + '\n');
+  process.exit(0);
+}
+
+const MESSAGING_SURFACES = new Set(['Messaging', 'CustomerWebClient']);
+const tag = (block, name) => {
+  const m = block.match(new RegExp(`<${name}>\\s*([^<]*?)\\s*</${name}>`, 's'));
+  return m ? m[1].trim() : '';
+};
+
+// Collect candidate blocks: prefer plannerSurfaces entries (so we know the surfaceType), and
+// fall back to bare outboundRouteConfigs blocks if the bundle is flat/uncompiled.
+const candidates = [];
+for (const sm of xml.matchAll(/<plannerSurfaces>([\s\S]*?)<\/plannerSurfaces>/g)) {
+  const surfaceBlock = sm[1];
+  const surface = tag(surfaceBlock, 'surfaceType');
+  for (const cm of surfaceBlock.matchAll(/<outboundRouteConfigs>([\s\S]*?)<\/outboundRouteConfigs>/g)) {
+    candidates.push({ surface, block: cm[1] });
+  }
+}
+if (candidates.length === 0) {
+  for (const cm of xml.matchAll(/<outboundRouteConfigs>([\s\S]*?)<\/outboundRouteConfigs>/g)) {
+    candidates.push({ surface: '', block: cm[1] });
+  }
+}
+
+const describe = (c) => {
+  const name = tag(c.block, 'outboundRouteName');
+  const type = tag(c.block, 'outboundRouteType');
+  return {
+    name,
+    type,
+    surface: c.surface,
+    sameBlock: name !== '' && type !== '',
+    messagingSurface: MESSAGING_SURFACES.has(c.surface),
+  };
+};
+
+let chosen = null;
+if (expectedFlow) {
+  chosen = candidates.map(describe).find((d) => d.name === expectedFlow) || null;
+}
+if (!chosen) {
+  chosen = candidates.length ? describe(candidates[0]) : null;
+}
+if (!chosen) {
+  chosen = empty;
+}
+
+process.stdout.write(JSON.stringify(chosen) + '\n');