@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/investigating-agentforce-d360/assets/dc/steps.sql

@@ -0,0 +1,64 @@
+-- Planner steps — reusable for any WHERE filter.
+-- DMO: ssot__AIAgentInteractionStep__dlm
+--
+-- Placeholders (substituted by scripts/dc.py.load_sql):
+--   WHERE_CLAUSE  — the filter expression, no "WHERE" keyword
+--   ORDER_BY      — full "ORDER BY <col>" or empty string
+--
+-- One row per planner step within an interaction. Type enum (verified live):
+-- LLM_STEP | ACTION_STEP | TOPIC_STEP | TRUST_GUARDRAILS_STEP | SESSION_END.
+--
+-- NOTE: InputValueText__c / OutputValueText__c are HTML-escaped JSON.
+-- Callers should `html.unescape()` then `json.loads()` after fetch.
+-- No direct session FK — scope forward via ssot__AiAgentInteractionId__c
+-- (harvested from the session's Interaction rows).
+--
+-- ssot__GenAiGatewayRequestId__c / ssot__GenAiGatewayResponseId__c are
+-- included in the SELECT for completeness but are NOT used as join keys
+-- anywhere in the waterfall. Gateway audit rows are fetched forward from
+-- Session → GatewayRequest (via sessionId__c) — see gateway_requests.sql.
+-- ssot__ErrorMessageText__c uses the sentinel 'NOT_SET' (never NULL) to
+-- mean "no error"; filter with `!= 'NOT_SET'`, not `IS NOT NULL`.
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentInteractionId__c,
+    ssot__AiAgentInteractionStepType__c,
+    ssot__Name__c,
+    ssot__InputValueText__c,
+    ssot__OutputValueText__c,
+    ssot__PreStepVariableText__c,
+    ssot__PostStepVariableText__c,
+    ssot__GenerationId__c,
+    ssot__ErrorMessageText__c,
+    ssot__StartTimestamp__c,
+    ssot__EndTimestamp__c,
+    ssot__PrevStepId__c,
+    ssot__InternalOrganizationId__c,
+    ssot__TelemetryTraceSpanId__c,
+    ssot__AttributeText__c,
+    ssot__GenAiGatewayRequestId__c,
+    ssot__GenAiGatewayResponseId__c
+FROM ssot__AIAgentInteractionStep__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Steps for a specific interaction
+-- WHERE    → ssot__AiAgentInteractionId__c = '<interaction_id>'
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c
+
+-- Steps for a session (via interaction id IN list)
+-- WHERE    → ssot__AiAgentInteractionId__c IN ('<id1>','<id2>',...)
+
+-- Only action steps (exclude LLM + topic planning)
+-- WHERE    → ssot__AiAgentInteractionId__c IN ('<id1>','<id2>')
+--            AND ssot__AiAgentInteractionStepType__c = 'ACTION_STEP'
+
+-- Steps with errors (sentinel value; NOT null)
+-- WHERE    → ssot__AiAgentInteractionId__c IN ('<id1>','<id2>')
+--            AND ssot__ErrorMessageText__c != 'NOT_SET'

package/skills/investigating-agentforce-d360/assets/dc/tag_associations.sql

@@ -0,0 +1,46 @@
+-- Tag ↔ target association — which tag was applied to a moment/session/interaction.
+-- DMO: ssot__AiAgentTagAssociation__dlm
+--
+-- Placeholders (substituted by scripts/dc.py.load_sql):
+--   WHERE_CLAUSE  — the filter expression, no "WHERE" keyword
+--   ORDER_BY      — full "ORDER BY <col>" or empty string
+--
+-- Agent Optimization add-on DMO. THE applied-tag row — one per annotation.
+-- Points at a tag value (`ssot__AiAgentTagId__c`) + a target
+-- (moment | session | interaction) + the tag-definition-association that
+-- authorized it. `ssot__AssociationReasonText__c` carries the LLM's
+-- rationale for why it assigned this tag.
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentTagId__c,
+    ssot__AiAgentTagDefinitionAssociationId__c,
+    ssot__AiAgentMomentId__c,
+    ssot__AiAgentSessionId__c,
+    ssot__AiAgentInteractionId__c,
+    ssot__IsPassed__c,
+    ssot__AssociationReasonText__c,
+    ssot__CreatedDate__c,
+    ssot__InternalOrganizationId__c
+FROM ssot__AiAgentTagAssociation__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- All tag associations for one session
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+-- ORDER BY → ORDER BY ssot__CreatedDate__c
+
+-- Tags applied to a set of moments
+-- WHERE    → ssot__AiAgentMomentId__c IN ('<mom_id1>','<mom_id2>')
+
+-- Only passed evaluations (quality pass/fail)
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+--            AND ssot__IsPassed__c = true
+
+-- Associations by tag id (reverse lookup)
+-- WHERE    → ssot__AiAgentTagId__c IN ('<tag_id1>','<tag_id2>')

package/skills/investigating-agentforce-d360/assets/dc/tag_definition_associations.sql

@@ -0,0 +1,37 @@
+-- Tag definition ↔ agent association — which tags are available for an agent.
+-- DMO: ssot__AiAgentTagDefinitionAssociation__dlm
+--
+-- Placeholders (substituted by scripts/dc.py.load_sql):
+--   WHERE_CLAUSE  — the filter expression, no "WHERE" keyword
+--   ORDER_BY      — full "ORDER BY <col>" or empty string
+--
+-- Agent Optimization add-on DMO. Binds a TagDefinition to a specific agent
+-- (by API name) and prompt template. This is what `AiAgentTagAssociation`
+-- actually points at via `ssot__AiAgentTagDefinitionAssociationId__c`.
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentTagDefinitionId__c,
+    ssot__AiAgentApiName__c,
+    ssot__AiPromptTemplateId__c,
+    ssot__IsActive__c,
+    ssot__CreatedDate__c,
+    ssot__InternalOrganizationId__c
+FROM ssot__AiAgentTagDefinitionAssociation__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Active associations for a specific agent
+-- WHERE    → ssot__AiAgentApiName__c = '<agent_api_name>'
+--            AND ssot__IsActive__c = true
+
+-- Associations pointing at a set of tag definitions
+-- WHERE    → ssot__AiAgentTagDefinitionId__c IN ('<def_id1>','<def_id2>',...)
+
+-- Resolve by association id (from AiAgentTagAssociation)
+-- WHERE    → ssot__Id__c IN ('<assoc_id1>','<assoc_id2>',...)

package/skills/investigating-agentforce-d360/assets/dc/tag_definitions.sql

@@ -0,0 +1,50 @@
+-- Tag definitions — the schema/vocabulary for tags applied to moments or sessions.
+-- DMO: ssot__AiAgentTagDefinition__dlm
+--
+-- Placeholders (substituted by scripts/dc.py.load_sql):
+--   WHERE_CLAUSE  — the filter expression, no "WHERE" keyword
+--   ORDER_BY      — full "ORDER BY <col>" or empty string
+--
+-- Agent Optimization add-on DMO. Defines a tag type (name, data type,
+-- input scope, engine type, source) that can then be applied via
+-- AiAgentTag + AiAgentTagAssociation.
+
+SELECT
+    ssot__Id__c,
+    ssot__DeveloperName__c,
+    ssot__Name__c,
+    ssot__Description__c,
+    ssot__TagIdentifier__c,
+    ssot__DataType__c,
+    ssot__Status__c,
+    ssot__VersionNumber__c,
+    ssot__EngineType__c,
+    ssot__SourceType__c,
+    ssot__SourceTagReferenceName__c,
+    ssot__InputScope__c,
+    ssot__CreatedDate__c,
+    ssot__InternalOrganizationId__c
+FROM ssot__AiAgentTagDefinition__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- All active tag definitions
+--   Live orgs use 'Available' (not 'Active') — verified via live
+--   describe. Group by ssot__Status__c to confirm per-org.
+--   If 'Available' returns 0 rows, the waterfall retries unfiltered
+--   (`ssot__Id__c IS NOT NULL`). Callers replicating this template
+--   outside fetch_dc.py should apply the same fallback or expect
+--   empty catalogs on orgs where Status uses a different enum.
+-- WHERE    → ssot__Status__c = 'Available'
+-- ORDER BY → ORDER BY ssot__Name__c
+
+-- By developer name
+-- WHERE    → ssot__DeveloperName__c = 'IntentCategory'
+
+-- Definitions for a set of ids (resolves foreign keys from AiAgentTag)
+-- WHERE    → ssot__Id__c IN ('<def_id1>','<def_id2>',...)

package/skills/investigating-agentforce-d360/assets/dc/tags.sql

@@ -0,0 +1,37 @@
+-- Tag instances — a specific tag value under a tag definition.
+-- DMO: ssot__AiAgentTag__dlm
+--
+-- Placeholders (substituted by scripts/dc.py.load_sql):
+--   WHERE_CLAUSE  — the filter expression, no "WHERE" keyword
+--   ORDER_BY      — full "ORDER BY <col>" or empty string
+--
+-- Agent Optimization add-on DMO. A `AiAgentTag` belongs to a definition
+-- (e.g. definition "IntentCategory" with tag value "Refund Request").
+-- The tag is applied to a moment/session/interaction via AiAgentTagAssociation.
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentTagDefinitionId__c,
+    ssot__Value__c,
+    ssot__Description__c,
+    ssot__OrderNumber__c,
+    ssot__IsActive__c,
+    ssot__IsFallback__c,
+    ssot__CreatedDate__c,
+    ssot__InternalOrganizationId__c
+FROM ssot__AiAgentTag__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Tags for a specific definition (all allowed values)
+-- WHERE    → ssot__AiAgentTagDefinitionId__c = '<def_id>'
+--            AND ssot__IsActive__c = true
+-- ORDER BY → ORDER BY ssot__OrderNumber__c
+
+-- Resolve tags by id (from AiAgentTagAssociation.ssot__AiAgentTagId__c)
+-- WHERE    → ssot__Id__c IN ('<tag_id1>','<tag_id2>',...)

package/skills/investigating-agentforce-d360/assets/dc/telemetry_spans.sql

@@ -0,0 +1,55 @@
+-- Agent Platform Tracing spans — OpenTelemetry span tree per trace.
+-- DMO: ssot__TelemetryTraceSpan__dlm
+--
+-- Placeholders (substituted by scripts/dc.py.load_sql):
+--   WHERE_CLAUSE  — the filter expression, no "WHERE" keyword
+--   ORDER_BY      — full "ORDER BY <col>" or empty string
+--
+-- Provisioned only when **Agent Platform Tracing** is enabled (Setup →
+-- Einstein Audit, Analytics, and Monitoring Setup). Captures spans from
+-- Apex, Flows, Prompt Builder, Invocable Actions, Planner, AI Gateway,
+-- LLM Gateway, DC Query Federator.
+--
+-- Join to STDM: `ssot__TelemetryTrace__c = Interaction.ssot__TelemetryTraceId__c`.
+-- Parent/child within a trace: `ssot__TelemetryParentSpanId__c = <another span>.ssot__Id__c`.
+
+SELECT
+    ssot__Id__c,
+    ssot__TelemetryTrace__c,
+    ssot__TelemetryParentSpanId__c,
+    ssot__OperationName__c,
+    ssot__ServiceName__c,
+    ssot__SpanKind__c,
+    ssot__StatusCode__c,
+    ssot__StartDateTime__c,
+    ssot__EndDateTime__c,
+    ssot__DurationNumber__c,
+    ssot__TelemetrySpanAttributeText__c,
+    ssot__InternalOrganizationId__c
+FROM ssot__TelemetryTraceSpan__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- All spans for one trace (joins to Interaction.ssot__TelemetryTraceId__c)
+-- WHERE    → ssot__TelemetryTrace__c = '<trace_id>'
+-- ORDER BY → ORDER BY ssot__StartDateTime__c
+
+-- All spans for a set of traces (whole session)
+-- WHERE    → ssot__TelemetryTrace__c IN ('<trace_id1>','<trace_id2>',...)
+
+-- Only root spans (no parent)
+-- WHERE    → ssot__TelemetryTrace__c = '<trace_id>'
+--            AND ssot__TelemetryParentSpanId__c = null
+
+-- Only spans from a specific service
+-- WHERE    → ssot__TelemetryTrace__c = '<trace_id>'
+--            AND ssot__ServiceName__c = 'Atlas Reasoning Engine'
+
+-- Slow spans — duration > 1s (nanoseconds in DurationNumber)
+-- WHERE    → ssot__TelemetryTrace__c = '<trace_id>'
+--            AND ssot__DurationNumber__c > 1000000000

package/skills/investigating-agentforce-d360/references/artifacts.md

@@ -0,0 +1,50 @@
+# Artifacts reference
+
+Every successful trace lands artifacts under
+`~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<sid>/`.
+Re-running the same `(org, sid)` overwrites in place. Listed below in
+the order they're produced.
+
+```
+~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<sid>/
+├── dc._session_manifest.json ← per-query counts + session_shape + empties
+├── dc._session_tree.json ← hierarchical join (primary artifact)
+├── dc._session_summary.md ← human-readable summary, up to 11 sections (varies with session_shape + identity bootstrap + --show-prompts opt-in)
+├── dc.sessions.json ← 1 row (STDM session)
+├── dc.interactions.json ← N rows (TURN + SESSION_END)
+├── dc.messages.json ← USER + AGENT messages
+├── dc.steps.json ← LLM_STEP / ACTION_STEP / TOPIC_STEP / TRUST_GUARDRAILS_STEP / SESSION_END
+├── dc.participants.json ← USER + AGENT participants
+├── dc.generations.json ← LLM generations
+├── dc.gateway_requests.json ← gateway-logged LLM calls
+├── dc.gateway_responses.json ← 1:1 with gateway_requests
+├── dc.gateway_request_tags.json ← tag rows (bot_id, agent_version_api_name, etc.)
+├── dc.gateway_request_metadata.json ← per-call metadata
+├── dc.content_quality.json ← Trust Layer quality scores
+├── dc.content_category.json ← toxicity + other category rows
+├── dc.feedback.json ← user thumbs-up/down (often empty)
+├── dc.feedback_details.json ← feedback text (often empty)
+├── dc.moments.json ← optional Agent Optimization rollup (often empty)
+├── dc.moment_interactions.json ← moment→interaction junction (often empty)
+├── dc.tag_*.json ← org-wide agent tag catalog (often empty)
+├── dc.telemetry_spans.json ← usually empty (Agent Platform Tracing off)
+├── dc.app_generation.json ← reserved, always empty today
+├── dc.gateway_records.json ← grounded attachments (rare)
+├── dc.gateway_request_llm.json ← writer inactive on observed orgs
+└── dc.tag_associations.json ← agent↔tag links (often empty)
+```
+
+## Read order
+
+1. **`dc._session_summary.md`** — human-readable, top-to-bottom answers
+ "what happened in this session?"
+2. **`dc._session_tree.json`** — single source of truth, the
+ hierarchical join the summary was rendered from. Open this when the
+ summary is missing a detail you need.
+3. **`dc._session_manifest.json`** — per-DMO row counts, classified
+ `session_shape`, and empty-by-design reasons for any DMO that
+ returned zero rows. Open this when something looks missing in the
+ tree.
+4. **`dc.<name>.json`** — raw per-DMO rows. Only needed when the
+ manifest reports an unexpected count or the assembler logs a parse
+ warning.