@salesforce/afv-skills 1.46.0 → 1.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.46.0",
+  "version": "1.48.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/agentforce-observe/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: agentforce-observe
-description: "Analyze production Agentforce agent behavior using session traces and Data Cloud. TRIGGER when: user queries STDM session data or Data Cloud trace records; investigates production agent failures, regressions, or performance issues; asks about session traces, conversation logs, or agent metrics; wants to reproduce a reported production issue in preview; runs findSessions or trace analysis queries. DO NOT TRIGGER when: user creates, modifies, or debugs .agent files during development (use agentforce-generate); writes or runs test specs (use agentforce-test); uses sf agent preview for local development iteration; deploys or publishes agents."
+description: "Analyze production Agentforce agent behavior using session traces and Data Cloud, and manage Agent Health Monitoring (AHM) alerts. TRIGGER when: user queries STDM session data or Data Cloud trace records; investigates production agent failures, regressions, or performance issues; asks about session traces, conversation logs, or agent metrics; wants to reproduce a reported production issue in preview; runs findSessions or trace analysis queries; creates, lists, or deletes an AHM data alert on an agent metric (escalation rate, deflection, etc.); asks why an alert is not firing or wants to check whether alerts have fired (notification counts, or the per-alert Incidents view). DO NOT TRIGGER when: user creates, modifies, or debugs .agent files during development (use agentforce-generate); writes or runs test specs (use agentforce-test); uses sf agent preview for local development iteration; deploys or publishes agents."
 allowed-tools: Bash Read Write Edit Glob Grep
 metadata:
   relatedSkills:
     - "agentforce-generate"
     - "agentforce-test"
-  version: "0.8"
+  version: "0.9"
   domains: ["Agentforce", "Data 360"]
   cliTools:
     - tool: ["git"]
@@ -44,18 +44,22 @@ Improve Agentforce agents using session trace data and live preview testing.
 
 Gather these inputs before starting:
 
-- **Org alias** (required)
+- **Org alias** (required) -- must be authenticated (else `sf org login web`)
 - **Agent API name** (required for preview and deploy; ask if not provided)
 - **Agent file path** (optional) -- path to the `.agent` file, typically `force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent`. Auto-detect if not provided.
 - **Session IDs** (optional) -- analyze specific sessions; if absent, query last 7 days
 - **Days to look back** (optional, default 7)
+- **Alert owner user** (optional, alerts only) -- user whose alerts to list/manage; defaults to the current user
 
 Determine intent from user input:
 
-- **No specific action** -> run all three phases: Observe -> surface issues -> ask if user wants to Reproduce and/or Improve
+- **No specific action** -> run all three analysis phases: Observe -> surface issues -> ask if user wants to Reproduce and/or Improve
 - **"analyze" / "sessions" / "what's wrong"** -> Phase 1 only, then suggest next steps
 - **"reproduce" / "test" / "preview"** -> Phase 2 (run Phase 1 first if no issues in hand)
 - **"fix" / "improve" / "update"** -> Phase 3 (run Phase 1 first if no issues in hand)
+- **"create alert" / "set up monitoring" / "alert me when"** -> Phase 4 (create)
+- **"list alerts" / "show my alerts" / "delete alert"** -> Phase 4 (list / delete)
+- **"why isn't my alert firing" / "have my alerts fired" / "alert notifications"** -> Phase 4 (notification-count signal + Incidents view + metric verify)
 
 ### Resolve agent name
 
@@ -380,11 +384,35 @@ Create regression test cases from confirmed issues in Testing Center YAML format
 
 ---
 
+## Agent Health Monitoring (AHM)
+
+> Full AHM alert procedures -- POST schema, enums, SDM/metric/agent discovery, thresholds, metric verification, troubleshooting: see `references/ahm-alerts.md`
+
+Proactive complement to the reactive Observe phases: **AHM data alerts** fire when an agent metric (escalation, deflection, etc.) crosses a threshold. Driven through `sf api request rest` against `tableau/dataAlerts` (`dataAlertType: "agenthealthmonitoring"`) -- there is no `sf agent alert` subcommand yet. Reuse **Phase 0** for `dataspace`. Build the POST body and discover the SDM, its `_mtc` metric id, and the agent filter value **per the reference first**, then:
+
+```bash
+# List/describe -- resolve owner id first (required); single-alert GET is 405 => list + filter client-side
+USER_ID=$(sf org display user --target-org <org> --json | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
+sf api request rest "/services/data/v66.0/tableau/dataAlerts?ownerId=$USER_ID" -o <org>
+# Create (body built per reference into a 0600 mktemp file) / delete (204)
+sf api request rest "/services/data/v66.0/tableau/dataAlerts" -X POST -H "Content-Type: application/json" -b "@$body" -o <org>
+sf api request rest "/services/data/v66.0/tableau/dataAlerts/$ALERT_ID" -X DELETE -o <org> --include
+# Notification counts are org-global, NOT per-alert (confirm the specific alert in the UI Incidents tab).
+sf api request rest "/services/data/v66.0/connect/notifications/status" -o <org>
+```
+
+**Two silent-failure traps to carry into any alert work:**
+- **Thresholds are raw 0-1 ratios**, not display percentages -- 5% is `"0.05"`, `"1"` means 100%.
+- **POST field names/casing differ from GET** -- POST uses `utterance` (not `alertName`) and PascalCase `type` discriminators, so copying a GET response back into a POST fails.
+
+---
+
 ## Reference Files
 
 | Reference | Contents |
 |---|---|
 | `references/stdm-queries.md` | STDM query procedures, Apex service deployment, response parsing |
+| `references/ahm-alerts.md` | AHM data-alert create/list/delete, trigger history, SDM/metric/agent discovery, threshold schema, metric verification |
 | `references/issue-classification.md` | Issue pattern table, root cause categories, structural analysis checks |
 | `references/reproduce-reference.md` | Phase 2 preview procedures, trace diagnosis, classification criteria |
 | `references/improve-reference.md` | Phase 3 editing, deployment chain, verification, safety, test cases |