@salesforce/afv-skills 1.13.0 → 1.15.0

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

@@ -0,0 +1,44 @@
+-- Additional per-request metadata — reusable for any WHERE filter.
+-- DMO: GenAIGtwyRequestMetadata__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
+--
+-- Child of GenAIGatewayRequest__dlm. Holds typed metadata rows for a
+-- request — observed values include `metadataType__c = 'ToolCall'` and
+-- `feature__c = 'plannerservice'`, so this is where planner/tool-call
+-- metadata on a gateway request lives.
+--
+-- No `ssot__` prefix — fields end in `__c` directly.
+--
+-- Joined via `parent__c = GatewayRequest.gatewayRequestId__c`.
+-- Join direction verified live: sampled row's parent__c matched exactly
+-- one row in GenAIGatewayRequest__dlm. The table is usually heavily
+-- populated on orgs with Trust Layer gateway logging enabled.
+
+SELECT
+    id__c,
+    parent__c,
+    metadataType__c,
+    metadata__c,
+    feature__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIGtwyRequestMetadata__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- All metadata rows for a set of gateway request ids
+-- WHERE    → parent__c IN ('<req_id1>','<req_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Only ToolCall-type metadata
+-- WHERE    → parent__c IN ('<req_id1>','<req_id2>')
+--            AND metadataType__c = 'ToolCall'

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

@@ -0,0 +1,42 @@
+-- Gateway request tags — k/v metadata attached to a gateway request.
+-- DMO: GenAIGatewayRequestTag__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
+--
+-- Many rows per request. Common tags include:
+--   - `prompt_template_dev_name` → which prompt template was used
+--   - `user_utterance`           → raw user input that triggered this request
+--
+-- Joined via `parent__c = GatewayRequest.gatewayRequestId__c`.
+-- No `ssot__` prefix — fields end in `__c` directly.
+
+SELECT
+    id__c,
+    parent__c,
+    tag__c,
+    tagValue__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIGatewayRequestTag__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- All tags for a set of request ids
+-- WHERE    → parent__c IN ('<req_id1>','<req_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Only `prompt_template_dev_name` tags
+-- WHERE    → parent__c IN ('<req_id1>','<req_id2>')
+--            AND tag__c = 'prompt_template_dev_name'
+
+-- Find requests where the user utterance matched a pattern
+-- WHERE    → tag__c = 'user_utterance'
+--            AND tagValue__c LIKE '%refund%'

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

@@ -0,0 +1,89 @@
+-- Gateway requests — one row per LLM request at the GenAI Gateway.
+-- DMO: GenAIGatewayRequest__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
+--
+-- Richer than GenAIGeneration — carries the actual prompt text, token counts,
+-- model params (temperature/penalties), session/user IDs, bot version, and
+-- the masked-prompt variant.
+--
+-- NOTE: No `ssot__` prefix — fields end in `__c` directly.
+--
+-- sessionId__c storage format (verified live): the value is stored as a
+-- literal 40-char string INCLUDING surrounding double-quotes, e.g.
+--   sessionId__c = "<session_uuid>"
+-- Non-session features (prompt-builder previews, eval harnesses, etc.) store
+-- the literal sentinel "no_session". Exact-match queries MUST include the
+-- double-quotes:
+--   WHERE sessionId__c = '"<session_uuid>"'
+-- Or use LIKE with wildcards (robust against format variants):
+--   WHERE sessionId__c LIKE '%<session_uuid>%'
+-- Raw-UUID exact match returns 0 rows — the quotes are part of the stored value.
+--
+-- Forward join path from a session:
+--   Session.ssot__Id__c  →  GatewayRequest.sessionId__c (LIKE or quoted match)
+-- This is the authoritative and only supported entry point. GatewayRequest is
+-- then the parent for all downstream audit-chain children — Response (via
+-- generationRequestId__c), Tag/ObjRecord/Metadata/LLM (via parent__c).
+-- See `scripts/fetch_dc.py` wave 3 and `references/dc_dmo_fields.md` "Cross-DMO
+-- join map" for the full forward tree.
+
+SELECT
+    gatewayRequestId__c,
+    generationGroupId__c,
+    sessionId__c,
+    userId__c,
+    botVersionId__c,
+    plannerId__c,
+    feature__c,
+    appType__c,
+    model__c,
+    provider__c,
+    promptTemplateDevName__c,
+    promptTemplateVersionNo__c,
+    prompt__c,
+    maskedPrompt__c,
+    parameters__c,
+    temperature__c,
+    frequencyPenalty__c,
+    presencePenalty__c,
+    stopSequences__c,
+    numGenerations__c,
+    promptTokens__c,
+    completionTokens__c,
+    totalTokens__c,
+    enableInputSafetyScoring__c,
+    enableOutputSafetyScoring__c,
+    enablePiiMasking__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIGatewayRequest__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Requests for one session (direct FK; note the mandatory double-quoted form).
+-- Two equivalent WHERE forms — both verified live, both return the same rows:
+-- WHERE    → sessionId__c = '"<session_id>"'            (exact match on quoted string)
+-- WHERE    → sessionId__c LIKE '%<session_id>%'          (format-tolerant)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Requests for a specific set of gatewayRequestIds (e.g. narrowing after a
+-- session fetch, or lookup by ids harvested from another query)
+-- WHERE    → gatewayRequestId__c IN ('<req_id1>','<req_id2>',...)
+
+-- All requests for a bot version in a time window
+-- WHERE    → botVersionId__c = '<version_id>'
+--            AND timestamp__c >= '<iso_cutoff>'
+-- ORDER BY → ORDER BY timestamp__c DESC
+
+-- Requests using a specific prompt template
+-- WHERE    → promptTemplateDevName__c = '<template_dev_name>'
+--            AND timestamp__c >= '<iso_cutoff>'

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

@@ -0,0 +1,43 @@
+-- Gateway responses — one row per LLM call response at the GenAI Gateway.
+-- DMO: GenAIGatewayResponse__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
+--
+-- FK shape (small table; documented for reference only):
+--   generationRequestId__c   = GatewayRequest.gatewayRequestId__c
+--   generationResponseId__c  = Step.ssot__GenAiGatewayResponseId__c
+--                            = Generation.generationResponseId__c
+--
+-- Forward join path from a session:
+--   Session → GatewayRequest (sessionId__c LIKE)
+--           → GatewayResponse (generationRequestId__c IN {gw_req_ids})
+-- This is the canonical and only supported direction. 1:1 invariant holds
+-- in live data — every GatewayRequest for a session produces one Response
+-- row (modulo in-flight calls at fetch time).
+--
+-- NOTE: No `ssot__` prefix — fields end in `__c` directly.
+
+SELECT
+    generationResponseId__c,
+    generationRequestId__c,
+    parameters__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIGatewayResponse__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Forward: Responses for the session's gateway requests (primary use case)
+-- WHERE    → generationRequestId__c IN ('<req_id1>','<req_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Ad-hoc lookup by specific response ids (not used by the waterfall)
+-- WHERE    → generationResponseId__c IN ('<resp_id1>','<resp_id2>',...)

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

@@ -0,0 +1,52 @@
+-- GenAI gateway generations — reusable for any WHERE filter.
+-- DMO: GenAIGeneration__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 LLM call at the gateway (Trust Layer).
+--
+-- NOTE: No `ssot__` prefix on this DMO — fields end in `__c` directly.
+--
+-- Forward join to a session: this DMO has NO session/trace/turn column.
+-- The only supported path is Step.ssot__GenerationId__c → generationId__c,
+-- driven forward from the session:
+--   Session → Interaction (ssot__AiAgentSessionId__c)
+--           → Step        (ssot__AiAgentInteractionId__c)
+--           → Generation  (step.ssot__GenerationId__c IN {generationId__c})
+-- Pull step rows for the session's interactions first, collect non-empty
+-- `ssot__GenerationId__c` values (LLM_STEP rows populate it; others are
+-- NOT_SET), then query here with `generationId__c IN (...)`.
+
+SELECT
+    generationId__c,
+    generationResponseId__c,
+    responseText__c,
+    maskedResponseText__c,
+    responseParameters__c,
+    feature__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIGeneration__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Generations for a set of step generation ids
+-- WHERE    → generationId__c IN ('<gen_id1>','<gen_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Generations in a time window for one org
+-- WHERE    → orgId__c = '<org_id_18>'
+--            AND timestamp__c >= '<iso_window_start>'
+--            AND timestamp__c <  '<iso_window_end>'
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Filter by feature (e.g. Copilot vs guardrails)
+-- WHERE    → feature__c = 'CopilotForDigitalChannels'

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

@@ -0,0 +1,53 @@
+-- Session interactions (turns + session-end event) — reusable for any WHERE.
+-- DMO: ssot__AIAgentInteraction__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 turn plus one SESSION_END row per session.
+-- Type enum: TURN | SESSION_END.
+--
+-- Casing gotcha: DMO name uses `AIAgent` (uppercase AI). Field names use
+-- `AiAgent` (lowercase i). See references/dc_dmo_fields.md.
+--
+-- trace_id gotcha: `ssot__TelemetryTraceId__c` is often empty on real orgs
+-- (verified live). The runtime trace_id lives inside
+-- `ssot__AttributeText__c` as HTML-escaped JSON, key `internalTraceId`.
+-- Consumers must `html.unescape()` + regex-extract. Used to join with
+-- GenAIGeneration (generationId via Step) and TelemetryTraceSpan.
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentSessionId__c,
+    ssot__AiAgentInteractionType__c,
+    ssot__TopicApiName__c,
+    ssot__StartTimestamp__c,
+    ssot__EndTimestamp__c,
+    ssot__PrevInteractionId__c,
+    ssot__SessionOwnerId__c,
+    ssot__IndividualId__c,
+    ssot__InternalOrganizationId__c,
+    ssot__TelemetryTraceId__c,
+    ssot__TelemetryTraceSpanId__c,
+    ssot__AttributeText__c
+FROM ssot__AIAgentInteraction__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- All interactions for one session
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c
+
+-- TURN rows only (exclude SESSION_END)
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+--            AND ssot__AiAgentInteractionType__c = 'TURN'
+
+-- Interactions handled by a specific topic across sessions
+-- WHERE    → ssot__TopicApiName__c = 'Order_Management'
+--            AND ssot__StartTimestamp__c >= '2026-01-01T00:00:00.000Z'

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

@@ -0,0 +1,53 @@
+-- User/agent messages — reusable for any WHERE filter.
+-- DMO: ssot__AiAgentInteractionMessage__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 user/agent message. Type enum: Input | Output.
+--
+-- This DMO has a direct session FK (`ssot__AiAgentSessionId__c`) — verified
+-- live against Data Cloud v66.0. Scope by session directly; no need to join through
+-- interactions. It also has a participant FK and a parent-message FK for
+-- threading, plus `MessageStartTimestamp__c` / `MessageEndTimestamp__c` for
+-- voice-modality durations (richer than the single `MessageSentTimestamp__c`).
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentSessionId__c,
+    ssot__AiAgentInteractionId__c,
+    ssot__AiAgentSessionParticipantId__c,
+    ssot__ParentMessageId__c,
+    ssot__ContentText__c,
+    ssot__AiAgentInteractionMessageType__c,
+    ssot__AiAgentInteractionMsgContentType__c,
+    Modality__c,
+    ssot__MessageSentTimestamp__c,
+    MessageStartTimestamp__c,
+    MessageEndTimestamp__c,
+    ssot__InternalOrganizationId__c
+FROM ssot__AiAgentInteractionMessage__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Messages for one session (direct FK — preferred)
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+-- ORDER BY → ORDER BY ssot__MessageSentTimestamp__c
+
+-- Messages for a specific interaction
+-- WHERE    → ssot__AiAgentInteractionId__c = '<interaction_id>'
+-- ORDER BY → ORDER BY ssot__MessageSentTimestamp__c
+
+-- Only user inputs for a session
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+--            AND ssot__AiAgentInteractionMessageType__c = 'Input'
+
+-- Voice-modality messages (use start/end timestamps for duration)
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+--            AND Modality__c = 'Voice'

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

@@ -0,0 +1,37 @@
+-- MessagingSession id → AI-agent session id lookup.
+-- DMO: ssot__AIAgentSession__dlm
+--
+-- Given a Salesforce MessagingSession id (0Mw... prefix, 15 or 18 chars),
+-- find every ssot__AIAgentSession__dlm row with matching
+-- RelatedMessagingSessionId. Used by scripts/resolve_session.py to map a
+-- messaging id to the canonical AI-agent session UUID that every other
+-- script keys on.
+--
+-- Placeholders (substituted by scripts/dc.py.load_sql):
+--   MSG_ID  — the MessagingSession id (pre-validated by the caller:
+--             is_messaging_id() enforces the `0Mw` key prefix plus an
+--             exact 15 or 18 char length before this template is loaded.
+--             A raw-UUID or free-text id can never reach this template.)
+--
+-- Returned rows:
+--   * zero rows  → caller raises SystemExit ("no messaging session found")
+--   * one row    → caller returns ssot__Id__c as the UUID
+--   * many rows  → caller prints every candidate with timestamps + end_type
+--                  + channel and exits non-zero so the user can pick one
+--                  and re-invoke with the specific UUID.
+--
+-- The `RelatedMessagingSessionId__c != 'NOT_SET'` clause is defensive —
+-- a real msg_id cannot equal the literal 'NOT_SET', but the guard lets
+-- the template be copy-pasted for other filters that might otherwise
+-- accidentally match the sentinel.
+
+SELECT
+    ssot__Id__c,
+    ssot__StartTimestamp__c,
+    ssot__EndTimestamp__c,
+    ssot__AiAgentSessionEndType__c,
+    ssot__AiAgentChannelType__c
+FROM ssot__AIAgentSession__dlm
+WHERE ssot__RelatedMessagingSessionId__c = '{{MSG_ID}}'
+  AND ssot__RelatedMessagingSessionId__c != 'NOT_SET'
+ORDER BY ssot__StartTimestamp__c DESC;

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

@@ -0,0 +1,34 @@
+-- Moment ↔ Interaction junction — which turns belong to a moment.
+-- DMO: ssot__AiAgentMomentInteraction__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. Provisioned only when Agent Optimization
+-- is enabled. Junction between AiAgentMoment and AIAgentInteraction.
+-- Observed live: one Moment per Interaction (N:1 direction). The junction
+-- schema supports true many-to-many; the assembler emits Moment.interaction_ids[]
+-- back-refs to preserve the schema-correct shape even when live data is 1:N.
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentMomentId__c,
+    ssot__AiAgentInteractionId__c,
+    ssot__StartTimestamp__c,
+    ssot__InternalOrganizationId__c
+FROM ssot__AiAgentMomentInteraction__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Junction rows for a set of moments
+-- WHERE    → ssot__AiAgentMomentId__c IN ('<mom_id1>','<mom_id2>',...)
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c
+
+-- Junction rows for a set of interactions (reverse lookup)
+-- WHERE    → ssot__AiAgentInteractionId__c IN ('<int_id1>','<int_id2>')

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

@@ -0,0 +1,39 @@
+-- Session-level agent moment rollup — reusable for any WHERE filter.
+-- DMO: ssot__AiAgentMoment__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
+--
+-- When present, carries agent identity + a request/response summary for
+-- the session. This is the only STDM DMO outside Participant that exposes
+-- AiAgentApiName__c. Moments are absent on orgs without Agent Optimization
+-- enabled; the assembler falls back to Participant (AGENT role) for agent
+-- identity in that case.
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentSessionId__c,
+    ssot__AiAgentApiName__c,
+    ssot__AiAgentVersionApiName__c,
+    ssot__RequestSummaryText__c,
+    ssot__ResponseSummaryText__c,
+    ssot__StartTimestamp__c,
+    ssot__EndTimestamp__c,
+    ssot__InternalOrganizationId__c
+FROM ssot__AiAgentMoment__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Moment(s) for one session — usually 0 or 1 row
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+
+-- All sessions handled by a specific agent API name in a date range
+-- WHERE    → ssot__AiAgentApiName__c = 'MyAgent'
+--            AND ssot__StartTimestamp__c >= '2026-01-01T00:00:00.000Z'
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c

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

@@ -0,0 +1,48 @@
+-- Session participants from Data Cloud — reusable for any WHERE filter.
+-- DMO: ssot__AiAgentSessionParticipant__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 participant per session. Roles: USER, AGENT.
+-- AiAgentApiName__c is populated on AGENT rows only.
+--
+-- Casing gotcha: DMO name uses `AiAgent` (lowercase i), unlike the Session
+-- DMO which uses `AIAgent` (uppercase AI). See references/dc_dmo_fields.md.
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentSessionId__c,
+    ssot__ParticipantId__c,
+    ssot__AiAgentApiName__c,
+    ssot__AiAgentType__c,
+    ssot__AiAgentTemplateApiName__c,
+    ssot__AiAgentVersionApiName__c,
+    ssot__AiAgentSessionParticipantRole__c,
+    ssot__ParticipantObject__c,
+    ssot__StartTimestamp__c,
+    ssot__EndTimestamp__c,
+    ssot__IndividualId__c,
+    ssot__InternalOrganizationId__c,
+    ssot__ParticipantAttributeText__c
+FROM ssot__AiAgentSessionParticipant__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Participants for one session
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c
+
+-- Only AGENT rows (carry agent identity)
+-- WHERE    → ssot__AiAgentSessionId__c = '<session_id>'
+--            AND ssot__AiAgentSessionParticipantRole__c = 'AGENT'
+
+-- All sessions handled by a specific agent
+-- WHERE    → ssot__AiAgentApiName__c = 'MyAgent'
+--            AND ssot__StartTimestamp__c >= '2026-01-01T00:00:00.000Z'

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

@@ -0,0 +1,78 @@
+-- Sessions from Data Cloud — reusable for any WHERE filter.
+-- DMO: ssot__AIAgentSession__dlm
+--
+-- Placeholders (substituted by scripts/dc.py._load):
+--   WHERE_CLAUSE  — the filter expression, no "WHERE" keyword
+--   ORDER_BY      — full "ORDER BY <col>" or empty string
+--
+-- See EXAMPLE QUERIES below for common WHERE patterns.
+--
+-- This query extracts session-level data including:
+--   - Session ID and timestamps
+--   - Channel type (how user connected)
+--   - How the session ended (Completed, Abandoned, Escalated, etc.)
+--   - Related messaging session (if applicable)
+--
+-- NOTE: Agent name is NOT on Session table. Join with Moment to get agent info.
+
+SELECT
+    ssot__Id__c,
+    ssot__AiAgentChannelType__c,
+    ssot__StartTimestamp__c,
+    ssot__EndTimestamp__c,
+    ssot__AiAgentSessionEndType__c,
+    ssot__RelatedMessagingSessionId__c,
+    ssot__RelatedVoiceCallId__c,
+    ssot__InternalOrganizationId__c,
+    ssot__SessionOwnerId__c,
+    ssot__SessionOwnerObject__c,
+    ssot__IndividualId__c,
+    ssot__PreviousSessionId__c,
+    ssot__VariableText__c
+FROM ssot__AIAgentSession__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE QUERIES (pass to sessions_sql via where_clause= / order_by=)
+-- ============================================================================
+
+-- One session by id (this skill's primary use case)
+-- WHERE    → ssot__Id__c = '<session_uuid>'
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c
+
+-- Last 7 days of sessions
+-- WHERE    → ssot__StartTimestamp__c >= '<iso_cutoff_7d_ago>'
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c
+
+-- Date range
+-- WHERE    → ssot__StartTimestamp__c >= '2026-01-01T00:00:00.000Z'
+--            AND ssot__StartTimestamp__c < '2026-02-01T00:00:00.000Z'
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c
+
+-- Failed / escalated sessions only
+-- WHERE    → ssot__AiAgentSessionEndType__c IN ('Escalated', 'Abandoned', 'Failed')
+--            AND ssot__StartTimestamp__c >= '2026-01-01T00:00:00.000Z'
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c
+
+-- Sessions by channel (e.g. embedded messaging only)
+-- WHERE    → ssot__AiAgentChannelType__c = 'SCRT2 - EmbeddedMessaging'
+--            AND ssot__StartTimestamp__c >= '2026-01-01T00:00:00.000Z'
+-- ORDER BY → ORDER BY ssot__StartTimestamp__c
+
+-- Session count by end type (aggregate — SELECT list changes too; separate template)
+-- SELECT
+--     ssot__AiAgentSessionEndType__c,
+--     COUNT(*) as session_count
+-- FROM ssot__AIAgentSession__dlm
+-- WHERE ssot__StartTimestamp__c >= '2026-01-01T00:00:00.000Z'
+-- GROUP BY ssot__AiAgentSessionEndType__c;
+
+-- Sessions by agent (requires Moment join — separate query shape, not this template)
+-- SELECT DISTINCT s.*
+-- FROM ssot__AIAgentSession__dlm s
+-- JOIN ssot__AiAgentMoment__dlm m
+--     ON m.ssot__AiAgentSessionId__c = s.ssot__Id__c
+-- WHERE m.ssot__AiAgentApiName__c = 'MyAgent'
+--   AND s.ssot__StartTimestamp__c >= '2026-01-01T00:00:00.000Z';