forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-agentforce-human-escalation-configure
service-agentforce-human-escalation-configure
UnverifiedUse 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/patch-escalation-surfaces.mjs
View on GitHub#!/usr/bin/env node
// Idempotent in-place patcher for canEscalate + outboundRoute surfaces; refuses (exit 4) if no safe insertion point. XSD order + modes: references/classifier-contracts.md.
import { readFileSync, writeFileSync } from 'node:fs';
const [mode, filePath, flowName, escalationMessageArg] = process.argv.slice(2);
if (!mode || !filePath) {
process.stderr.write('usage: node patch-escalation-surfaces.mjs <canEscalate|outboundRoute> <file> [flowApiName] [escalationMessage]\n');
process.exit(2);
}
const xmlEscape = (s) => String(s)
.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>');
let text;
try {
text = readFileSync(filePath, 'utf8');
} catch {
process.stderr.write(`error: cannot read ${filePath}\n`);
process.exit(2);
}
const done = (summary) => { process.stdout.write(JSON.stringify(summary) + '\n'); process.exit(0); };
const refuse = (msg) => { process.stderr.write(`refuse: ${msg}\n`); process.exit(4); };
// Return {index, indent} of the earliest top-level opening tag from `tags` found in `hay`
// (searched from offset `from`), along with the leading whitespace on that tag's line.
const firstTag = (hay, tags, from = 0) => {
const scope = hay.slice(from);
let best = null;
for (const t of tags) {
const re = new RegExp(`([ \\t]*)<${t}(?=[ >/])`, 'g');
for (const m of scope.matchAll(re)) {
const idx = from + m.index;
if (best === null || idx < best.index) best = { index: idx, indent: m[1] || '' };
break; // first match of this tag is enough
}
}
return best;
};
if (mode === 'canEscalate') {
// Idempotent: normalize an existing <canEscalate> to true.
if (/<canEscalate>[\s\S]*?<\/canEscalate>/.test(text)) {
const next = text.replace(/<canEscalate>[\s\S]*?<\/canEscalate>/, '<canEscalate>true</canEscalate>');
if (next !== text) writeFileSync(filePath, next);
done({ mode, changed: next !== text, action: 'set-existing' });
}
const rootOpen = text.match(/<GenAiPlugin\b[^>]*>/);
if (!rootOpen) refuse('no <GenAiPlugin> root element found');
let searchFrom = rootOpen.index + rootOpen[0].length;
// Skip PAST any <aiPluginUtterances> blocks first - they legally precede canEscalate and each
// one carries a nested <developerName>, which would otherwise be mistaken for the top-level anchor.
const utteranceCloses = [...text.matchAll(/<\/aiPluginUtterances>/g)];
if (utteranceCloses.length) {
const last = utteranceCloses[utteranceCloses.length - 1];
searchFrom = last.index + '</aiPluginUtterances>'.length;
}
// canEscalate must come BEFORE the first of these top-level siblings.
const anchor = firstTag(text, [
'description', 'developerName', 'genAiFunctions', 'genAiPluginInstructions',
'language', 'localActionLinks', 'localActions', 'localDeveloperName',
'masterLabel', 'pluginType', 'scope', 'source',
], searchFrom);
if (!anchor) refuse('no post-canEscalate sibling (description/developerName/masterLabel/...) found; refusing to guess placement');
const indent = anchor.indent || ' ';
const insertion = `${indent}<canEscalate>true</canEscalate>\n`;
const followingTag = text.slice(anchor.index).match(/<([A-Za-z]+)/)[1];
const next = text.slice(0, anchor.index) + insertion + text.slice(anchor.index);
writeFileSync(filePath, next);
done({ mode, changed: true, action: 'inserted-before-' + followingTag });
}
if (mode === 'outboundRoute') {
if (!flowName) { process.stderr.write('error: outboundRoute requires <flowApiName>\n'); process.exit(2); }
const escMsg = xmlEscape(escalationMessageArg || 'Transferring you to a live support agent.');
const MESSAGING_SURFACES = new Set(['Messaging', 'CustomerWebClient']);
const surfaces = [...text.matchAll(/<plannerSurfaces>([\s\S]*?)<\/plannerSurfaces>/g)];
if (surfaces.length === 0) refuse('no <plannerSurfaces> block found; refusing to invent one');
const chosen = surfaces.find((m) => {
const t = m[1].match(/<surfaceType>\s*([^<]*?)\s*<\/surfaceType>/);
return t && MESSAGING_SURFACES.has(t[1].trim());
});
if (!chosen) refuse('no Messaging-class planner surface (surfaceType Messaging|CustomerWebClient) found');
const innerStart = chosen.index + '<plannerSurfaces>'.length;
const innerEnd = chosen.index + chosen[0].length - '</plannerSurfaces>'.length;
const inner = text.slice(innerStart, innerEnd);
// Idempotent: an existing outboundRouteConfigs already targeting this flow -> normalize the type only.
const existing = [...inner.matchAll(/<outboundRouteConfigs>([\s\S]*?)<\/outboundRouteConfigs>/g)]
.find((c) => {
const n = c[1].match(/<outboundRouteName>\s*([^<]*?)\s*<\/outboundRouteName>/);
return n && n[1].trim() === flowName;
});
if (existing) {
const block = existing[0];
let newBlock = block;
if (/<outboundRouteType>[\s\S]*?<\/outboundRouteType>/.test(block)) {
newBlock = block.replace(/<outboundRouteType>[\s\S]*?<\/outboundRouteType>/, '<outboundRouteType>OmniChannelFlow</outboundRouteType>');
} else {
newBlock = block.replace(/<\/outboundRouteConfigs>/, ' <outboundRouteType>OmniChannelFlow</outboundRouteType>\n </outboundRouteConfigs>');
}
if (newBlock === block) done({ mode, changed: false, action: 'already-configured' });
const newInner = inner.replace(block, newBlock);
const next = text.slice(0, innerStart) + newInner + text.slice(innerEnd);
writeFileSync(filePath, next);
done({ mode, changed: true, action: 'normalized-type' });
}
// Insert a fresh block BEFORE <surface> to honor the AiPlannerSurfaceDef XSD sequence
// (...outboundRouteConfigs*, surface, surfaceType). <surface> is required, so it must be present.
const surfaceAnchor = firstTag(inner, ['surface']);
if (!surfaceAnchor) refuse('Messaging planner surface has no <surface> element; refusing to guess insertion point');
const indent = surfaceAnchor.indent || ' ';
const childIndent = indent + ' ';
const block =
`${indent}<outboundRouteConfigs>\n` +
`${childIndent}<escalationMessage>${escMsg}</escalationMessage>\n` +
`${childIndent}<outboundRouteName>${xmlEscape(flowName)}</outboundRouteName>\n` +
`${childIndent}<outboundRouteType>OmniChannelFlow</outboundRouteType>\n` +
`${indent}</outboundRouteConfigs>\n`;
const newInner = inner.slice(0, surfaceAnchor.index) + block + inner.slice(surfaceAnchor.index);
const next = text.slice(0, innerStart) + newInner + text.slice(innerEnd);
writeFileSync(filePath, next);
done({ mode, changed: true, action: 'inserted-before-surface' });
}
process.stderr.write(`error: unknown mode '${mode}'\n`);
process.exit(2);
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |