@salesforce/afv-skills 1.52.0 → 1.54.0

package/skills/service-agentforce-contact-center-coordinate/references/omni-flow-routing.md

@@ -0,0 +1,74 @@
+# Omni Flow routing (Agentforce agent on voice)
+
+Two routing models attach a `PstnVoice` channel to the contact center:
+
+| Model | `SessionHandlerId` | `FallbackQueueId` | Use when |
+|-------|--------------------|-------------------|----------|
+| **Omni Queue** (default) | ACC queue Id (`00G…`) | — | Calls land straight in the contact center queue for human reps. |
+| **Omni Flow** | inbound RoutingFlow **FlowDefinition** Id (`300…`) | ACC/voice queue Id (`00G…`) | Calls route to an Agentforce agent first, with the queue as fallback/escalation. |
+
+Omni Queue is the skill's original behavior (Step 8). This file covers **Omni Flow**.
+
+## The wiring contract
+
+An Omni Flow channel points its `SessionHandlerId` at an **inbound RoutingFlow** (not a queue) and names the queue in `FallbackQueueId`. That inbound flow references a **published, active** Agentforce agent. So the flow and agent must exist *before* the channel is created:
+
+```text
+agent (published + Active)  ->  inbound RoutingFlow (Active, 300-prefix)  ->  channel
+                                escalation RoutingFlow (Active)           ->  agent outbound (optional)
+```
+
+`FlowDefinition` (Id prefix `300`) is the stable handle used in `SessionHandlerId` — not the per-version `Flow` (prefix `301`).
+
+## Sub-fork: new vs existing
+
+- **Use existing** — the user supplies an already-published agent and an active inbound RoutingFlow. Resolve the flow's `300` Id with `scripts/resolve-flow-definition.sh <alias> <flow-dev-name>`, then create the channel (below). Skip agent/flow creation.
+- **Create new** — build both, in order:
+  1. **Preflight** — `scripts/check-agentforce-prereq.sh <alias>` must return a canonical `Einstein Agent User` profile user. It can provision one with `sf org create agent-user` if the org has capacity. Do not use broad Agent/Bot profile matches.
+  2. **Work dir** — `scripts/prepare-agent-workdir.sh acc-voice-build`, then run `sf agent generate agent-spec ... --output-file specs/<api-name>.yaml --target-org <alias>` from inside `acc-voice-build`; the spec generator requires SFDX project context.
+  3. **Agent** — from the parent/original work dir, run `scripts/create-voice-agent.sh <alias> <api-name> <label> acc-voice-build/specs/<api-name>.yaml acc-voice-build`. The script generates the authoring bundle, replaces the generator's `default_agent_user: "NEW AGENT USER"` placeholder with the spec's `agentUser`, deploys the `AiAuthoringBundle`, validates, publishes, and activates.
+  4. **Flows** — `scripts/create-routing-flows.sh <alias> <api-name> <label> <queue-id> <queue-name> acc-voice-build`. Renders and deploys the inbound (`_Voice_Omni_Flow`) and escalation (`_Voice_Escalation`) flows from inside the SFDX work dir and prints the inbound `300` Id.
+
+## Create the channel
+
+```bash
+scripts/create-voice-channel.sh <alias> <number> <channelLineId> <flowDefinitionId> <queueId>
+# 5th arg present -> Omni Flow: SessionHandlerId=<flowDefinitionId 300>, FallbackQueueId=<queueId>
+```
+
+## RoutingFlow field contract
+
+Both flows are `processType: RoutingFlow`, `status: Active`, on the `sfdc_phone` service channel (`serviceChannelLabel: Phone`). Templates: `assets/omni-flow.flow-meta.xml`, `assets/escalation-flow.flow-meta.xml`.
+
+| Field | Inbound (`_Voice_Omni_Flow`) | Escalation (`_Voice_Escalation`) |
+|-------|------------------------------|----------------------------------|
+| `routingType` | `Copilot` (routes to the agent) | `QueueBased` (routes to the queue) |
+| `copilotId` | `<setupReference>` → `BotDefinition` = agent api-name (required) | — |
+| `copilotLabel` | agent `MasterLabel` | — |
+| `queueId` / `queueLabel` | fallback queue (18-char Id + `Name`) | escalation queue |
+
+## Deviation — planner type
+
+Do **not** switch the agent's `plannerType` to `Atlas__VoiceAgent` (or add `plannerSurfaces`). This org (API ≤ 67) rejects it with an opaque server error (e.g. `-1103525358`), even with a complete published bundle. Keep the `Atlas__ConcurrentMultiAgentOrchestration` planner that `sf agent publish` generates — **inbound voice routes correctly via the `Copilot` RoutingFlow regardless of planner type** (verified against the org's own working voice agent). `create-voice-agent.sh` never touches the planner, so no action is needed; just don't add a planner-swap step.
+
+## Fallback to Omni Queue
+
+If the Agentforce prerequisite can't be confirmed (`references/agentforce-prerequisite.md`), or agent/flow creation fails, stop and report unless the user explicitly accepts a queue-only fallback. Some runs require an Agentforce agent and Omni Flow channel, so do not silently downgrade the routing model.
+
+## Agent creation gotchas
+
+| Symptom | Fix |
+|---------|-----|
+| `RequiresProjectError` from `sf agent generate agent-spec` | Prepare and run from `acc-voice-build` with `scripts/prepare-agent-workdir.sh` |
+| `default agent user NEW AGENT USER` during publish | Let `create-voice-agent.sh` patch the generated `.agent` from the spec's `agentUser` before deploy/publish |
+| `Unable to access the Salesforce Agent APIs` / `User doesn't have access to use agent` | Ensure `agentUser` is a canonical `Einstein Agent User` profile user, not a generic Agent/Bot-profile user |
+| `InvalidProjectWorkspaceError` during flow deploy | Reuse the prepared work dir; `create-routing-flows.sh` deploys from inside it |
+
+## Verify
+
+```sql
+SELECT Id, DeveloperName, MessageType, SessionHandlerId, FallbackQueueId, IsActive
+FROM MessagingChannel WHERE Id = '<channel-id>'
+```
+
+`SessionHandlerId` must start with `300` (the inbound FlowDefinition) and `FallbackQueueId` with `00G` (the queue).

package/skills/service-agentforce-contact-center-coordinate/references/setup_summary.md

@@ -0,0 +1,36 @@
+# Setup Summary
+
+After the voice channel is created and verified, present a summary to the user.
+
+## Summary table
+
+| Configuration | Value |
+|---------------|-------|
+| Phone Number | `<phone-number>` |
+| Number Type | `<phone-type>` |
+| Country | `<country>` |
+| ChannelLine ID | `<channel-line-id>` |
+| Phone Status | `<code-status>` |
+| Channel ID | `<channel-id>` |
+| Channel Status | Active |
+| Routing model | `<Omni Queue \| Omni Flow>` |
+| Queue | `<acc-queue-name>` |
+| Agentforce agent (Omni Flow) | `<agent-label>` (`<agent-api-name>`) |
+| Inbound flow (Omni Flow) | `<agent-api-name>_Voice_Omni_Flow` |
+| Developer Name | `<dev-name>` |
+
+Include the Agentforce agent / inbound flow rows only for the Omni Flow path.
+
+## What's ready
+
+- Phone number procured and provisioned
+- ChannelLine resolved
+- Voice channel created and activated
+- **Omni Queue:** channel routed to the Agentforce Contact Center queue
+- **Omni Flow:** channel routed to the Agentforce agent (Copilot inbound flow) with the queue as fallback; escalation flow deployed
+
+## Suggested next steps
+
+- **Omni Queue:** configure agents in the queue.
+- **Omni Flow:** test the agent conversation; optionally tune voice (`modality voice:`) or wire outbound escalation to the agent.
+- Test by calling the procured number.

package/skills/service-agentforce-contact-center-coordinate/references/verification_and_errors.md

@@ -0,0 +1,42 @@
+# Verification & Error Handling
+
+## Live-verification polling strategy
+
+A procured number must reach `Live` status on its `CommunicationChannelLine`
+before a working voice channel can route calls.
+
+`CommunicationChannelLine` is Tooling-API-only — it is not queryable via `sf data query`
+(that returns `INVALID_TYPE: sObject type 'CommunicationChannelLine' is not supported`).
+Query it via `sf api request rest .../tooling/query` instead, the same way
+`scripts/resolve-channel-line.sh` does. The live-status field is `CodeStatus`
+(not `Status__c`, which does not exist on this object), and it's looked up by `Code`
+(not `Name`).
+
+1. Query the line by code:
+   `SELECT Id, Code, CodeStatus FROM CommunicationChannelLine WHERE Code = '<number>'`
+2. If the record exists and `CodeStatus = 'Live'` → done.
+3. Otherwise call `POST /numberStateReconcile` (see `number_management_api.md`) to
+   force reconciliation.
+4. Poll every **5 seconds**, up to **3 attempts** (≈15 seconds total), re-querying `CodeStatus`.
+5. If still not `Live` after 3 attempts, warn the user and offer to wait/retry or proceed
+   anyway (the channel may be created but not immediately operational).
+
+`scripts/verify-number-live.sh` implements this loop and prints the final status.
+
+## ChannelLine resolution (retry)
+
+Immediately after procurement, `CommunicationChannelLine` may not yet exist because
+records propagate asynchronously. `scripts/resolve-channel-line.sh` queries by `Code`
+and retries up to 3 times (3s apart) before reporting failure.
+
+## Error categories
+
+| Category | Symptom | Handling |
+|----------|---------|----------|
+| Number fetch | `400` | Invalid country/type — re-collect selections |
+| Number fetch | `500` | Retry after a few seconds |
+| Procurement | `409` | Already procured — pick a different number |
+| Sync | `404` | Number missing — re-run procurement |
+| Sync | `500` | Retry after a few seconds |
+| Channel create | duplicate `DeveloperName` | Derive a unique name |
+| Channel create | invalid queue Id | Re-resolve the queue by name (Step 7) |

package/skills/service-agentforce-contact-center-coordinate/scripts/check-agentforce-prereq.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Preflight the Agentforce (service agent) prerequisite and resolve the canonical Einstein Agent User.
+# The Omni Flow "create new agent" path needs a user with the Einstein Agent User profile;
+# broader Agent/Bot profile matches can validate a spec but fail at publish time.
+# If no canonical user exists, ask the Salesforce CLI to provision one with the correct
+# profile, permission sets, and PSL assignments.
+# Usage: check-agentforce-prereq.sh <org-alias> [base-username]
+# Output: the Einstein Agent User Username on stdout.
+# Exit 0 if found/provisioned, 2 usage, 3 if none exists and auto-provisioning fails.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" || $# -lt 1 ]]; then
+  echo "Usage: check-agentforce-prereq.sh <org-alias> [base-username]" >&2
+  [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
+fi
+
+ALIAS="$1"
+BASE_USERNAME="${2:-agentforce-service-agent@example.com}"
+
+# The profile name is the canonical signal used by `sf org create agent-user`.
+# Do not fall back to generic Agent/Bot profiles; those users can make spec generation
+# appear successful but fail `sf agent publish authoring-bundle`.
+USERNAME=$(sf data query \
+  --query "SELECT Username FROM User WHERE IsActive = true AND Profile.Name = 'Einstein Agent User' ORDER BY CreatedDate DESC LIMIT 1" \
+  --target-org "$ALIAS" --json 2>/dev/null | jq -r '.result.records[0].Username // empty')
+
+if [[ -n "$USERNAME" ]]; then
+  echo "$USERNAME"
+  exit 0
+fi
+
+CREATE_RESP=$(sf org create agent-user \
+  --target-org "$ALIAS" \
+  --base-username "$BASE_USERNAME" \
+  --first-name "EinsteinServiceAgent" \
+  --last-name "User" \
+  --json 2>&1) || {
+    echo "error: no Einstein Agent User found in '${ALIAS}', and auto-provisioning failed." >&2
+    echo "$CREATE_RESP" >&2
+    echo "See references/agentforce-prerequisite.md to enable Agentforce Agents or free an Agentforce Service Agent User license, then retry." >&2
+    exit 3
+  }
+
+USERNAME=$(echo "$CREATE_RESP" | jq -r '.result.username // empty')
+if [[ -z "$USERNAME" ]]; then
+  echo "error: sf org create agent-user did not return result.username:" >&2
+  echo "$CREATE_RESP" >&2
+  exit 3
+fi
+
+echo "$USERNAME"

package/skills/service-agentforce-contact-center-coordinate/scripts/create-routing-flows.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Create and deploy the two RoutingFlows of a voice Omni Flow, then return the inbound flow's
+# FlowDefinition Id (300-prefix) for the channel's SessionHandlerId.
+#   - Inbound    <api-name>_Voice_Omni_Flow  : routingType=Copilot   -> routes to the agent, queue as fallback
+#   - Escalation <api-name>_Voice_Escalation : routingType=QueueBased -> agent hands off to the queue
+# Usage: create-routing-flows.sh <org-alias> <agent-api-name> <agent-label> <queue-id> <queue-name> [work-dir]
+#   work-dir defaults to ./acc-voice-build (reuse the same dir as create-voice-agent.sh)
+# Output: the inbound FlowDefinition Id (300-prefix) on stdout.
+# Exit 0 on success, 2 usage, 5 on deploy failure, 3 if the inbound flow did not activate.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" || $# -lt 5 ]]; then
+  echo "Usage: create-routing-flows.sh <org-alias> <agent-api-name> <agent-label> <queue-id> <queue-name> [work-dir]" >&2
+  [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
+fi
+
+ALIAS="$1"; API_NAME="$2"; LABEL="$3"; QUEUE_ID="$4"; QUEUE_NAME="$5"; WORK_DIR="${6:-acc-voice-build}"
+
+INBOUND="${API_NAME}_Voice_Omni_Flow"
+ESC="${API_NAME}_Voice_Escalation"
+ASSETS_DIR="$(cd "$SCRIPT_DIR/../assets" && pwd)"
+
+# Free-text values land in XML stringValue/label nodes — escape them so a queue name or
+# agent label containing &, <, >, etc. can't produce malformed XML. QUEUE_ID and API_NAME
+# are platform-constrained (Id / DeveloperName), so they pass through unescaped.
+LABEL_X="$(xml_escape "$LABEL")"
+QUEUE_NAME_X="$(xml_escape "$QUEUE_NAME")"
+
+ensure_sfdx_project "$WORK_DIR"
+WORK_DIR_ABS="$(cd "$WORK_DIR" && pwd)"
+FLOWS_DIR="$WORK_DIR_ABS/force-app/main/default/flows"
+mkdir -p "$FLOWS_DIR"
+
+render_template "$ASSETS_DIR/omni-flow.flow-meta.xml" \
+  "FLOW_LABEL=${LABEL_X} Voice Omni Flow" "AGENT_API_NAME=${API_NAME}" "AGENT_LABEL=${LABEL_X}" \
+  "QUEUE_ID=${QUEUE_ID}" "QUEUE_LABEL=${QUEUE_NAME_X}" > "$FLOWS_DIR/${INBOUND}.flow-meta.xml"
+
+render_template "$ASSETS_DIR/escalation-flow.flow-meta.xml" \
+  "FLOW_LABEL=${LABEL_X} Voice Escalation" "QUEUE_ID=${QUEUE_ID}" "QUEUE_LABEL=${QUEUE_NAME_X}" \
+  > "$FLOWS_DIR/${ESC}.flow-meta.xml"
+
+DEP=$(cd "$WORK_DIR_ABS" && sf project deploy start --source-dir "$FLOWS_DIR" --target-org "$ALIAS" --json 2>&1) \
+  || { echo "flow deploy failed:" >&2; echo "$DEP" >&2; exit 5; }
+
+# The channel wires to the inbound flow's FlowDefinition Id; it must be active.
+"$SCRIPT_DIR/resolve-flow-definition.sh" "$ALIAS" "$INBOUND"

package/skills/service-agentforce-contact-center-coordinate/scripts/create-voice-agent.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Create, publish, and activate an Agentforce voice service agent (Omni Flow "new agent" path).
+# Replicates the validated session flow: generate an authoring bundle from a spec, repair
+# generator placeholders, deploy the AiAuthoringBundle, validate, publish, and activate.
+# Runs inside a scaffolded SFDX project so the bundle can publish.
+#
+# DEVIATION (do not remove): do NOT change plannerType to Atlas__VoiceAgent. This org (API <= 67)
+# rejects it with an opaque server error. Keep the publish-generated
+# Atlas__ConcurrentMultiAgentOrchestration planner — inbound voice routes correctly via the
+# Copilot RoutingFlow regardless of planner type. See references/omni-flow-routing.md.
+#
+# Usage: create-voice-agent.sh <org-alias> <agent-api-name> <agent-label> <spec-file> [work-dir]
+#   work-dir defaults to ./acc-voice-build (pass the same dir to create-routing-flows.sh)
+# Output: the agent api-name (== BotDefinition DeveloperName) on stdout once Active.
+# Exit 0 on Active, 2 usage, 5 on any generate/validate/publish/activate failure.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" || $# -lt 4 ]]; then
+  echo "Usage: create-voice-agent.sh <org-alias> <agent-api-name> <agent-label> <spec-file> [work-dir]" >&2
+  [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
+fi
+
+ALIAS="$1"; API_NAME="$2"; LABEL="$3"; SPEC="$4"; WORK_DIR="${5:-acc-voice-build}"
+
+[[ -f "$SPEC" ]] || { echo "error: spec file not found: $SPEC" >&2; exit 2; }
+SPEC_ABS="$(cd "$(dirname "$SPEC")" && pwd)/$(basename "$SPEC")"
+AGENT_USER=$(awk -F: '/^agentUser:[[:space:]]*/ { sub(/^[[:space:]]+/, "", $2); gsub(/^"|"$/, "", $2); print $2; exit }' "$SPEC_ABS")
+
+ensure_sfdx_project "$WORK_DIR"
+cd "$WORK_DIR"
+
+GEN=$(sf agent generate authoring-bundle --spec "$SPEC_ABS" --name "$LABEL" --api-name "$API_NAME" \
+  --output-dir force-app/main/default --target-org "$ALIAS" --json 2>&1) \
+  || { echo "authoring-bundle generation failed:" >&2; echo "$GEN" >&2; exit 5; }
+
+AGENT_FILE="force-app/main/default/aiAuthoringBundles/${API_NAME}/${API_NAME}.agent"
+if [[ -n "$AGENT_USER" && -f "$AGENT_FILE" ]]; then
+  tmp_file="$(mktemp)"
+  awk -v user="$AGENT_USER" '
+    /^[[:space:]]*default_agent_user:/ {
+      match($0, /^[[:space:]]*/)
+      print substr($0, RSTART, RLENGTH) "default_agent_user: \"" user "\""
+      next
+    }
+    { print }
+  ' "$AGENT_FILE" > "$tmp_file"
+  mv "$tmp_file" "$AGENT_FILE"
+fi
+
+DEP=$(sf project deploy start --source-dir "force-app/main/default/aiAuthoringBundles/${API_NAME}" \
+  --target-org "$ALIAS" --json 2>&1) \
+  || { echo "authoring-bundle deploy failed:" >&2; echo "$DEP" >&2; exit 5; }
+
+VAL=$(sf agent validate authoring-bundle --api-name "$API_NAME" --target-org "$ALIAS" --json 2>&1) \
+  || { echo "agent validate failed:" >&2; echo "$VAL" >&2; exit 5; }
+
+PUB=$(sf agent publish authoring-bundle --api-name "$API_NAME" --target-org "$ALIAS" --json 2>&1) \
+  || { echo "agent publish failed:" >&2; echo "$PUB" >&2; exit 5; }
+
+# --json + --api-name is non-interactive: with --json and no --version the CLI auto-activates
+# the latest version and does not prompt, so no confirmation needs to be piped in.
+ACT=$(sf agent activate --api-name "$API_NAME" --target-org "$ALIAS" --json 2>&1) \
+  || { echo "agent activate failed:" >&2; echo "$ACT" >&2; exit 5; }
+
+STATUS=$(sf data query \
+  --query "SELECT Status FROM BotVersion WHERE BotDefinition.DeveloperName = '${API_NAME}' ORDER BY VersionNumber DESC LIMIT 1" \
+  --target-org "$ALIAS" --json 2>/dev/null | jq -r '.result.records[0].Status // empty')
+
+[[ "$STATUS" == "Active" ]] || { echo "error: agent '${API_NAME}' is not Active (status: ${STATUS:-unknown})" >&2; exit 5; }
+echo "$API_NAME"

package/skills/service-agentforce-contact-center-coordinate/scripts/create-voice-channel.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Create an active PstnVoice MessagingChannel for a procured number.
+# Usage: create-voice-channel.sh <org-alias> <phone-number> <channel-line-id> <session-handler-id> [fallback-queue-id]
+#   Omni Queue (4 args): pass the ACC queue Id as <session-handler-id>.
+#   Omni Flow  (5 args): pass the inbound FlowDefinition Id (300-prefix) as <session-handler-id>
+#                        and the fallback queue Id as [fallback-queue-id].
+# Output: JSON create response on stdout. Exit 0 only when the response is
+# "success": true; exit 5 otherwise.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" || $# -lt 4 ]]; then
+  echo "Usage: create-voice-channel.sh <org-alias> <phone-number> <channel-line-id> <session-handler-id> [fallback-queue-id]" >&2
+  [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
+fi
+
+ALIAS="$1"; NUMBER="$2"; CHANNEL_LINE_ID="$3"; SESSION_HANDLER_ID="$4"; FALLBACK_QUEUE_ID="${5:-}"
+
+DEV_NAME="Voice_Channel_${NUMBER//+/}"
+ENDPOINT="/services/data/${API_VERSION}/sobjects/MessagingChannel/"
+
+post_channel() {
+  local err_file out status
+  err_file="$(mktemp)"
+  set +e
+  out=$(sf api request rest "$ENDPOINT" \
+    --method POST \
+    --body "$1" \
+    --target-org "$ALIAS" 2>"$err_file")
+  status=$?
+  set -e
+
+  if [[ -n "$out" ]]; then
+    printf '%s\n' "$out"
+  else
+    cat "$err_file"
+  fi
+  rm -f "$err_file"
+  return "$status"
+}
+
+# SessionHandlerId is the queue Id (Omni Queue) or the inbound FlowDefinition Id (Omni Flow).
+# On the Omni Flow path also set FallbackQueueId to the queue the agent overflows/escalates to.
+if [[ -n "$FALLBACK_QUEUE_ID" ]]; then
+  BODY=$(jq -n \
+    --arg dn "$DEV_NAME" --arg num "$NUMBER" --arg cl "$CHANNEL_LINE_ID" \
+    --arg sh "$SESSION_HANDLER_ID" --arg fq "$FALLBACK_QUEUE_ID" \
+    '{DeveloperName:$dn, MasterLabel:("Voice Channel " + $num), MessageType:"PstnVoice",
+      MessagingPlatformKey:$num, ChannelLineId:$cl, IsActive:true, SessionHandlerId:$sh, FallbackQueueId:$fq}')
+else
+  BODY=$(jq -n \
+    --arg dn "$DEV_NAME" --arg num "$NUMBER" --arg cl "$CHANNEL_LINE_ID" --arg sh "$SESSION_HANDLER_ID" \
+    '{DeveloperName:$dn, MasterLabel:("Voice Channel " + $num), MessageType:"PstnVoice",
+      MessagingPlatformKey:$num, ChannelLineId:$cl, IsActive:true, SessionHandlerId:$sh}')
+fi
+
+RESP=$(post_channel "$BODY") || true
+
+echo "$RESP"
+
+# The response is emitted above for the caller to parse; set the exit code so a
+# failed create (error payload, non-live number, duplicate name) can't be mistaken
+# for success by a caller that only checks the exit status.
+echo "$RESP" | jq -e '.success == true' >/dev/null 2>&1 || exit 5

package/skills/service-agentforce-contact-center-coordinate/scripts/fetch-numbers.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Fetch available default phone numbers for a country + phone-number type.
+# Usage: fetch-numbers.sh <org-alias> <country> <phone-type>
+#   country:    US | CA
+#   phone-type: 10DLC | "Toll Free"
+# Output: JSON { "phoneNumbers": [...] } on stdout.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" || $# -lt 3 ]]; then
+  echo "Usage: fetch-numbers.sh <org-alias> <country> <phone-type>" >&2
+  [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
+fi
+
+ALIAS="$1"; COUNTRY="$2"; PHONE_TYPE="$3"
+
+sf api request rest \
+  "/${NM_BASE}/numbers?countryCode=${COUNTRY}&phoneNumberType=$(urlenc_spaces "$PHONE_TYPE")" \
+  --target-org "$ALIAS"

package/skills/service-agentforce-contact-center-coordinate/scripts/lib.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Shared constants for the Agentforce Contact Center coordination scripts.
+# Not invoked directly — sourced by the other scripts.
+#
+# All API calls go through `sf api request rest`, which uses the CLI's stored
+# session for --target-org. Never extract the access token from `sf org display`.
+
+set -euo pipefail
+
+API_VERSION="v68.0"
+NM_BASE="services/data/${API_VERSION}/connect/number-management/v1"
+
+# URL-encode a value's spaces (sufficient for country/phoneType query params).
+urlenc_spaces() { printf '%s' "${1// /%20}"; }
+
+# XML-escape a value for safe interpolation into flow-template stringValue/label nodes.
+# Free-text org data (queue names, agent labels) can contain &, <, >, ", ' — unescaped
+# they produce malformed XML and an opaque `sf project deploy start` parse error.
+# Escape & first so the entities emitted by the later rules aren't double-escaped.
+xml_escape() { printf '%s' "$1" | sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g; s/'"'"'/\&apos;/g'; }
+
+# Scaffold a minimal SFDX project at <dir> if one isn't already there. The Omni Flow path
+# generates an agent authoring bundle and deploys RoutingFlows, both of which need a project
+# context. sourceApiVersion is pinned to API_VERSION for consistency (v68).
+ensure_sfdx_project() {
+  local dir="$1"
+  mkdir -p "$dir/force-app/main/default"
+  if [[ ! -f "$dir/sfdx-project.json" ]]; then
+    printf '%s\n' "{\"packageDirectories\":[{\"path\":\"force-app\",\"default\":true}],\"namespace\":\"\",\"sfdcLoginUrl\":\"https://login.salesforce.com\",\"sourceApiVersion\":\"${API_VERSION#v}\"}" \
+      > "$dir/sfdx-project.json"
+  fi
+}
+
+# Render a token template to stdout, replacing every {{KEY}} with the paired value.
+# Usage: render_template <template-file> KEY=VALUE [KEY=VALUE ...]
+# Plain string replacement (no regex) so XML/URL values pass through unchanged.
+render_template() {
+  local tmpl="$1"; shift
+  local content pair key val
+  content="$(<"$tmpl")"
+  for pair in "$@"; do
+    key="${pair%%=*}"; val="${pair#*=}"
+    content="${content//\{\{${key}\}\}/${val}}"
+  done
+  printf '%s\n' "$content"
+}

package/skills/service-agentforce-contact-center-coordinate/scripts/prepare-agent-workdir.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Prepare a minimal SFDX project work directory for Agentforce agent generation.
+# `sf agent generate agent-spec` requires Salesforce project context before the
+# authoring-bundle script has a chance to call ensure_sfdx_project.
+# Usage: prepare-agent-workdir.sh [work-dir]
+# Output: absolute work-dir path on stdout.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" ]]; then
+  echo "Usage: prepare-agent-workdir.sh [work-dir]" >&2
+  exit 0
+fi
+
+WORK_DIR="${1:-acc-voice-build}"
+ensure_sfdx_project "$WORK_DIR"
+mkdir -p "$WORK_DIR/specs"
+cd "$WORK_DIR"
+pwd

package/skills/service-agentforce-contact-center-coordinate/scripts/procure-number.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Procure a selected phone number.
+# Usage: procure-number.sh <org-alias> <country> <phone-type> <phone-number>
+# Output: JSON response body on stdout. Non-zero exit on API error.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" || $# -lt 4 ]]; then
+  echo "Usage: procure-number.sh <org-alias> <country> <phone-type> <phone-number>" >&2
+  [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
+fi
+
+ALIAS="$1"; COUNTRY="$2"; PHONE_TYPE="$3"; NUMBER="$4"
+
+BODY=$(jq -n --arg t "$PHONE_TYPE" --arg c "$COUNTRY" --arg p "$NUMBER" \
+  '{phoneNumberType:$t, country:$c, phoneNumber:$p}')
+
+sf api request rest \
+  "/${NM_BASE}/number" \
+  --method POST \
+  --body "$BODY" \
+  --target-org "$ALIAS"

package/skills/service-agentforce-contact-center-coordinate/scripts/resolve-acc-queue.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Resolve the Agentforce Contact Center default queue Id by name (never hardcoded — org-specific).
+# Usage: resolve-acc-queue.sh <org-alias> [queue-name]
+#   queue-name defaults to "Default Queue Agentforce Contact Center"
+# Output: the queue Id on stdout. Exit 1 if not found.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" || $# -lt 1 ]]; then
+  echo "Usage: resolve-acc-queue.sh <org-alias> [queue-name]" >&2
+  [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
+fi
+
+ALIAS="$1"
+QUEUE_NAME="${2:-Default Queue Agentforce Contact Center}"
+
+ID=$(sf data query \
+  --query "SELECT Id FROM Group WHERE Type = 'Queue' AND Name = '${QUEUE_NAME}' LIMIT 1" \
+  --target-org "$ALIAS" --json 2>/dev/null | jq -r '.result.records[0].Id // empty')
+
+if [[ -z "$ID" ]]; then
+  echo "error: queue '${QUEUE_NAME}' not found in org '${ALIAS}'" >&2
+  exit 1
+fi
+echo "$ID"

package/skills/service-agentforce-contact-center-coordinate/scripts/resolve-channel-line.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Resolve the CommunicationChannelLine for a procured number, retrying while it propagates.
+# Usage: resolve-channel-line.sh <org-alias> <phone-number>
+# Output: JSON { "id": "...", "codeStatus": "..." } on success. Exit 1 if not found
+# after retries; 2 on usage error; 4 if the query API returns an error envelope.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" || $# -lt 2 ]]; then
+  echo "Usage: resolve-channel-line.sh <org-alias> <phone-number>" >&2
+  [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
+fi
+
+ALIAS="$1"; NUMBER="$2"
+ENCODED_PHONE="${NUMBER//+/%2B}"
+QUERY="SELECT+Id,CodeStatus+FROM+CommunicationChannelLine+WHERE+Code='${ENCODED_PHONE}'+LIMIT+1"
+
+for attempt in 1 2 3; do
+  DATA=$(sf api request rest \
+    "/services/data/${API_VERSION}/tooling/query?q=${QUERY}" \
+    --target-org "$ALIAS" 2>/dev/null || true)
+  # A success query is an object; an API error is a JSON array [{errorCode,...}].
+  # Stop on the error shape instead of letting jq crash on `.records` below.
+  echo "$DATA" | jq -e 'type == "array"' >/dev/null 2>&1 && { echo "error: query failed for ${NUMBER}: $DATA" >&2; exit 4; }
+  ID=$(echo "$DATA" | jq -r '.records[0].Id // empty')
+  STATUS=$(echo "$DATA" | jq -r '.records[0].CodeStatus // empty')
+  if [[ -n "$ID" ]]; then
+    jq -n --arg id "$ID" --arg s "$STATUS" '{id:$id, codeStatus:$s}'
+    exit 0
+  fi
+  [[ $attempt -lt 3 ]] && sleep 3
+done
+
+echo "error: CommunicationChannelLine not found for ${NUMBER} after 3 attempts" >&2
+exit 1

package/skills/service-agentforce-contact-center-coordinate/scripts/resolve-flow-definition.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Resolve a RoutingFlow's FlowDefinition Id (300-prefix) by DeveloperName via the Tooling API.
+# Used for the channel's SessionHandlerId on the Omni Flow path, and to validate an existing
+# inbound flow when the user reuses one. FlowDefinition (300) is the stable handle — not the
+# per-version Flow (301) Id.
+# Usage: resolve-flow-definition.sh <org-alias> <flow-developer-name>
+# Output: the 300-prefix FlowDefinition Id on stdout.
+# Exit 0 if active, 2 usage, 1 if not found, 3 if found but not activated (ActiveVersionId null).
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib.sh"
+
+if [[ "${1:-}" == "--help" || $# -lt 2 ]]; then
+  echo "Usage: resolve-flow-definition.sh <org-alias> <flow-developer-name>" >&2
+  [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
+fi
+
+ALIAS="$1"; DEVNAME="$2"
+
+RESP=$(sf api request rest \
+  "/services/data/${API_VERSION}/tooling/query?q=SELECT+Id,DeveloperName,ActiveVersionId+FROM+FlowDefinition+WHERE+DeveloperName='${DEVNAME}'+LIMIT+1" \
+  --target-org "$ALIAS" 2>/dev/null || true)
+
+# A success query is an object; an API error is a JSON array [{errorCode,...}].
+echo "$RESP" | jq -e 'type == "array"' >/dev/null 2>&1 && { echo "error: FlowDefinition query failed for ${DEVNAME}: $RESP" >&2; exit 1; }
+
+ID=$(echo "$RESP" | jq -r '.records[0].Id // empty')
+ACTIVE=$(echo "$RESP" | jq -r '.records[0].ActiveVersionId // empty')
+
+[[ -n "$ID" ]] || { echo "error: FlowDefinition '${DEVNAME}' not found in '${ALIAS}'" >&2; exit 1; }
+[[ -n "$ACTIVE" ]] || { echo "error: FlowDefinition '${DEVNAME}' exists but has no active version" >&2; exit 3; }
+echo "$ID"