@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/investigating-agentforce-d360/README.md

@@ -0,0 +1,123 @@
+# investigating-agentforce-d360
+
+Data Cloud 360° view of a single Agentforce session. Pulls 24 STDM + GenAI DMOs from Salesforce Data Cloud, assembles a hierarchical session tree (Interaction → Step → Generation → GatewayRequest), and renders a human-readable markdown summary.
+
+This skill is **DC-only** — it reads runtime audit data that Salesforce Data Cloud has materialized for a session. It does not call into runtime telemetry, performance services, or any Splunk / observability surface.
+
+Input: an Agent Session UUID (`019d…`) **or** a MessagingSession id (`0Mw…`, 15/18 chars), and an `sf` CLI org alias.
+
+Output: per-DMO JSON artifacts plus three derived files under `~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<version>/<session_id>/` (default; override per-script with `--data-dir <path>`):
+
+- `dc.<name>.json` — 24 raw DMO results (one per query in the waterfall)
+- `dc._session_manifest.json` — per-DMO row counts, classified `session_shape`, and empty-by-design reasons
+- `dc._session_tree.json` — hierarchical join (the primary artifact; the summary is rendered from this)
+- `dc._session_summary.md` — human-readable summary, up to 11 sections
+
+---
+
+## Runtime budget
+
+**~10–30s typical** on a 15-turn session. The 5-wave fetch waterfall fans out 24 queries; later waves depend on ids harvested from earlier waves, so wave-to-wave is sequential, but each wave's queries run concurrently within the wave.
+
+---
+
+## Prerequisites
+
+| Tool | Why |
+|---|---|
+| `sf` CLI (authenticated against the target org) | Shells `sf org display --target-org <alias> --json` for the Data Cloud Query REST API access token |
+| Data Cloud enabled on the target org | Required — the STDM + GenAI DMOs must have materialized for the session |
+| Python 3.10+ | `pathlib`, dataclasses, `\|` union types |
+
+---
+
+## Usage
+
+Invoked conversationally through whatever skill-aware runtime hosts it. Example prompts:
+
+| User says | Skill does |
+|---|---|
+| `trace session 019dface-... in my-org` | Run the 3-stage pipeline: fetch → assemble → render |
+| `summarize what happened in 0MwTESTMSG12345AAA` | Resolve the messaging id → UUID, then run the pipeline |
+| `find escalated sessions today on Messaging in my-org` | Run `discover_sessions.py`, print a numbered picker, user picks one, then run the pipeline |
+| `walk me through this session` | Same as trace — the rendered summary reads top-to-bottom |
+
+See `SKILL.md` for the full TRIGGER conditions, flag table, and the "DC-only blind spot" guidance.
+
+---
+
+## Pipeline
+
+Three stages, each independently runnable:
+
+```
+fetch_dc.py     →  24 dc.<name>.json + dc._session_manifest.json   (DC Query REST waterfall)
+assemble_dc.py  →  dc._session_tree.json                           (in-memory hierarchical join)
+render_dc.py    →  dc._session_summary.md                          (markdown rendering)
+```
+
+`fetch_dc.py --session <sid> --org <alias>` chains all three by default. Pass `--no-assemble` / `--no-render` to stop early.
+
+---
+
+## Artifacts 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
+3. **`dc._session_manifest.json`** — open this when something looks missing in the tree (per-DMO row counts, empty-by-design reasons)
+4. **`dc.<name>.json`** — raw per-DMO rows, only when the manifest reports an unexpected count
+
+See `references/artifacts.md` for the full inventory.
+
+---
+
+## What this skill does NOT answer
+
+DC alone tells you **what happened** — every step, every LLM call, every gateway request, in order, with timestamps. It does **not** tell you **what could have happened but didn't**:
+
+- Which **topics were eligible** for the classifier on a given turn
+- Which **actions survived rule expressions** and were actually offered to the LLM
+- Why the LLM picked one topic/action over another
+
+If the user's question is about *why a particular topic or action was or wasn't used*, DC-only is almost never sufficient. See "DC-only blind spot" in `SKILL.md`.
+
+For design-time architecture questions (topic/action tree, flow inventory, Apex classes, prompt templates), use the sibling skill `investigating-agentforce-architecture` instead.
+
+---
+
+## Layout
+
+```
+investigating-agentforce-d360/
+├── SKILL.md                               ← runtime-parsed entry point (TRIGGER / DO NOT TRIGGER, flags, prompts)
+├── README.md                              ← this file
+├── scripts/
+│   ├── fetch_dc.py                        ← 5-wave DC fetch + chained pipeline driver
+│   ├── assemble_dc.py                     ← in-memory hierarchical join → dc._session_tree.json
+│   ├── render_dc.py                       ← markdown rendering → dc._session_summary.md
+│   ├── discover_sessions.py               ← session picker by time / agent / channel / outcome / grep
+│   ├── resolve_session.py                 ← `0Mw…` MessagingSession id → Agent Session UUID
+│   ├── dc.py                              ← DC Query REST API client (load_sql, post)
+│   ├── storage.py                         ← per-session JSON writer (path-validated)
+│   ├── config.py                          ← shared constants + DATA_ROOT re-export
+│   ├── _shared/                           ← path / SQL helpers (paths, fs_guard, sql)
+│   └── tests/                             ← pytest suite (372 tests + 18 subtests)
+├── references/
+│   ├── artifacts.md                       ← the full per-session artifact inventory
+│   ├── dc_dmo_fields.md                   ← per-DMO field reference + cross-DMO join map
+│   └── dc_pipeline_contract.md            ← pipeline contract: tree shape + render-stage section list
+└── assets/
+    └── dc/                                ← 26 .sql templates loaded by dc.load_sql
+```
+
+---
+
+## Authored by
+
+Raghul Jayagopal (RJ), Salesforce ANZ FDE.
+
+---
+
+## License
+
+Apache-2.0. See repository root `LICENSE`.

package/skills/investigating-agentforce-d360/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: investigating-agentforce-d360
+description: "Data Cloud 360° view of a single Agentforce session. Pulls 24 STDM + GenAI DMO rows via the DC Query REST API, assembles a hierarchical session tree (Interaction → Step → Generation → GatewayRequest), renders a human-readable summary with transcript + per-turn topic/action invocations + LLM generations + tool calls + audit chain. TRIGGER when user asks to trace, inspect, summarize, or describe a specific Agentforce session by session id (Agent Session UUID `019d…` or MessagingSession id `0Mw…`). Also triggers on session discovery — find/list/search sessions by time, agent, channel, outcome, or conversation text — when the user has no session id yet. DO NOT TRIGGER for design-time architecture questions (use investigating-agentforce-architecture instead) or for runtime perf/latency/SLO questions that require platform telemetry beyond Data Cloud."
+metadata:
+  version: "1.0"
+---
+
+# investigating-agentforce-d360 — Data Cloud 360° session view
+
+Hierarchical session reconstruction from Data Cloud STDM + GenAI DMOs for one Agentforce session. Three stages — fetch → assemble → render. Typical wall-clock: ~10–30s for a ~15-turn session.
+
+The pipeline is **DC-only**: it reads runtime audit rows that Data Cloud has materialized. It is **not** a runtime-availability tool — see "DC-only blind spot" below for what this skill cannot answer.
+
+## If the user hasn't given enough to proceed
+
+When invoked with no session id AND no discovery criteria, print this block **verbatim** — do not paraphrase, do not pre-run any script. Trigger condition: the input is empty OR contains no session-id shape (neither a UUID nor a `0Mw…` messaging id) AND no discovery expression (no time phrase / `--agent` / `--channel` / `--outcome` / `--grep` / verbs like "find" / "list").
+
+> Which session should I pull from Data Cloud, and in which org?
+>
+> I need:
+> - **Session id** — either an Agent Session UUID (`019db7f6-…`) or a MessagingSession id (`0Mw…`, 15/18 chars).
+>   - **No session id?** — Tell me what you remember and I'll find it: how recent (e.g. "last 2 hours", "today", a date), which agent, which channel (Messaging / Builder / Voice), how it ended (escalated, user ended, transferred, timed out), or a phrase from the conversation. I'll show matching sessions as a numbered list — you pick one, I pull it.
+> - **Org alias** — for `sf` CLI auth (the alias you configured with `sf org login`).
+>
+> Artifacts land in `~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<session_id>/` (override per-script with `--data-dir <path>`).
+
+## Session id forms — UUID or MessagingSession id
+
+Both forms are accepted on `--session`:
+
+| Form | Example | Resolution |
+|---|---|---|
+| Agent Session UUID | `019dface-0000-7000-8000-000000000002` | Pass-through |
+| MessagingSession id (`0Mw` prefix) | `0MwTESTMSG12345AAA` | Resolved via `resolve_session.py` — live DC lookup on first fetch, disk-first thereafter |
+
+**Multi-match is real.** One MessagingSession id can map to multiple Agent Session UUIDs. On multi-match the resolver prints every candidate and exits non-zero; the user re-invokes with a specific UUID.
+
+Artifacts always land under `~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<session_id>/` (default; overridable per-script with `--data-dir <path>`) — the messaging id is a lookup key only, never a directory name. The dominant agent (first in `sorted(agents_observed)`) names the `<agent>__<ver>/` segment.
+
+## Resolving the script prefix
+
+The default install puts the skill under the runtime's plugin root. If the
+skill was cloned somewhere else (e.g. directly from the `forcedotcom/sf-skills`
+repo into a custom path), set `PLUGIN_ROOT` to point at the runtime's skills
+directory.
+
+```bash
+prefix="${SKILL_ROOT:-${PLUGIN_ROOT:-$HOME/.vibe/skills}/investigating-agentforce-d360}/scripts"
+```
+
+Every subsequent invocation in this doc uses `"$prefix/..."`.
+
+## Session discovery (no id yet)
+
+When the user doesn't have a session id, run `discover_sessions.py` against the STDM session DMO. Prints a numbered picker; user picks one; proceed with the chosen UUID.
+
+```bash
+python3 "$prefix/discover_sessions.py" --org <alias> [filters...]
+```
+
+**Filters** (all optional except `--org`): `--since <expr>` (default last 24h; accepts "last 2 hours", "today", ISO dates), `--agent <api-name>`, `--channel <Messaging|Builder|Voice>`, `--outcome <USER_ENDED|ESCALATED|TRANSFERRED|TIMEOUT|NOT_SET>`, `--grep <substring>` (conversation text), `--tz <IANA>`, `--limit <N>` (default 20).
+
+**Output**: markdown table with `#`, `UUID`, `Start (UTC)`, `Agent`, `Channel`, `Duration`, `Outcome`. User replies with a number; proceed with that UUID.
+
+## Pipeline — three stages
+
+```
+fetch_dc.py     →  24 dc.<name>.json + dc._session_manifest.json     (DC Query REST waterfall, 5 waves)
+assemble_dc.py  →  dc._session_tree.json                             (pure in-memory hierarchical join)
+render_dc.py    →  dc._session_summary.md                            (human summary, multi-section)
+```
+
+Each stage is independently runnable. `fetch_dc.py --session <sid> --org <alias>` chains all three by default.
+
+### Invocation
+
+```bash
+python3 "$prefix/fetch_dc.py" --session <session-id-or-messaging-id> --org <alias>
+```
+
+Flags: `--verbose` for per-DMO row counts; `--no-assemble` / `--no-render` to stop early. All entry scripts (`fetch_dc.py`, `assemble_dc.py`, `render_dc.py`, `resolve_session.py`, `discover_sessions.py`) accept `--data-dir <path>` and `--cache-dir <path>` to override the default `~/.vibe/{data,cache}/investigating-agentforce-d360/` roots — pass these when the host runtime needs artifacts under a different distribution layout.
+
+### Output artifacts
+
+Everything lands under `~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<session_id>/` (default; override with `--data-dir <path>`):
+
+```
+dc.sessions.json              dc.steps.json                dc.gateway_requests.json
+dc.interactions.json          dc.messages.json             dc.gateway_responses.json
+dc.participants.json          dc.generations.json          dc.gateway_request_llm.json
+dc.content_quality.json       dc.content_category.json     dc.gateway_request_metadata.json
+dc.tags.json                  dc.tag_definitions.json      dc.gateway_request_tags.json
+dc.tag_associations.json      dc.tag_definition_associations.json
+dc.feedback.json              dc.feedback_details.json     dc.gateway_records.json
+dc.moments.json               dc.moment_interactions.json
+dc.telemetry_spans.json       dc.app_generation.json
+
+dc._session_manifest.json     (per-DMO row counts + empties)
+dc._session_tree.json         (hierarchical join — session → interactions → steps → messages → generations → gateway)
+dc._session_summary.md        (rendered human summary)
+```
+
+Zero-row queries are recorded in the manifest with `status: empty`; no file is written. `assemble_dc` tolerates missing files. See `references/artifacts.md` for the full read order.
+
+## The DC-only blind spot — read before committing to a root cause
+
+DC alone answers **what happened** — steps that ran, generations that fired, gateway requests that were logged. It does NOT answer **what could have happened but didn't**:
+
+- Which **topics were eligible** for the classifier on a given turn (this lives in runtime planner telemetry, not DC).
+- Which **actions were declared** on a topic vs. which **survived rule expressions** and were actually offered to the LLM.
+- Why the LLM picked one topic/action over another (the full prompt + response text only lives in the planner runtime telemetry).
+
+If the user's question is about *why a particular topic or action was or wasn't used*, DC-only is almost never sufficient. **Tell the user**: "Availability questions need the runtime planner trace for that turn — which is outside this skill's Data Cloud surface. Check the platform telemetry that mirrors the planner's logged decisions." Don't fabricate a root cause from runtime-only evidence.
+
+### What DC IS good at
+
+- **What ran** — every step, every LLM call, every gateway request + response, in order, with timestamps and durations. Good for "walk me through the session".
+- **What the user saw** — full message transcript (user + agent), ordered.
+- **What the LLM produced** — generations, token counts, trust scores (toxicity, instruction adherence, content-category breakdown from `content_quality` + `content_category`).
+- **Tool invocations** — action calls, inputs, outputs, errors (from `gateway_request_metadata` + `gateway_records`).
+- **Feedback + flags** — user feedback, escalation markers, session-end type.
+- **Audit integrity** — the 1:1 invariant between GatewayRequest and GatewayResponse is checked; drift is flagged in `counts.audit_chain_1to1_ok`.
+
+## Prerequisites
+
+| Tool | Required |
+|---|---|
+| `sf` CLI (authenticated against the target org) | yes — `sf org login web --alias <alias>` |
+| Data Cloud enabled on the target org | yes — the STDM + GenAI DMOs must have materialized for the session |
+| Python 3.10+ | yes — pipeline scripts |
+
+## Typical prompts — what they map to
+
+| User says | Skill does |
+|---|---|
+| *"Trace session `<uuid>` in my-org"* | `fetch_dc.py --session <uuid> --org my-org` → assemble → render |
+| *"Summarize what happened in `0Mw…`"* | Resolve `0Mw…` → UUID, then full DC pipeline |
+| *"Find escalated sessions today in my-org on Messaging"* | Run `discover_sessions.py --since today --outcome ESCALATED --channel Messaging`, print picker, user picks, then DC pipeline |
+| *"Walk me through this session"* | Same as trace — read the rendered summary top to bottom |
+
+## What comes back to the user
+
+After the pipeline completes, the rendered `dc._session_summary.md` carries these top-level sections:
+
+1. **Session identity** — UUID, start/end, duration, agent, channel, end type, participant counts
+2. **Session bootstrap** — channel mode + bootstrap variables (`identity.mode`, `identity.bootstrap_variables`)
+3. **ID reference** — full UUIDs for everything truncated in the hierarchical trace
+4. **Transcript** — USER ↔ AGENT narrative per TURN interaction
+5. **Complete hierarchical trace** — Interaction → Step → Generation → GatewayRequest, with `+start + duration = +end` math
+6. **Per-turn summary** — one row per interaction
+7. **Planner LLM calls (full prompts + responses)** — opt-in via `--show-prompts`; suppressed by default
+8. **Visual analysis** — gantt + LLM-call overlay
+9. **Session counts** — engineer-facing table of manifest counts
+10. **Empties diagnostics** — one row per DMO with `rows == 0` and a populated `_unavailable_reason`
+11. **Catalog (session-filtered)** — TagDefinitions / TagDefinitionAssociations / Tags filtered to agents observed in the session
+
+For deep-dive, open `dc._session_tree.json` — the single source of truth the summary was rendered from. See `references/dc_pipeline_contract.md` for the full pipeline contract and `references/dc_dmo_fields.md` for per-DMO field reference.
+
+## Caveats
+
+- **`gateway_requests_dropped_by_stdm`** — when DC reports zero `gateway_requests` rows but runtime telemetry would show LLM calls did fire, this skill cannot definitively distinguish "STDM exporter dropped writes" from "logging genuinely disabled at the source". The session is reported as `planner_ran_no_gateway_logs`; the operator can check platform telemetry to disambiguate. See `references/dc_pipeline_contract.md` §2.8.
+- **Latency** — Generation and GatewayRequest carry single-write timestamps, not start/end pairs. The renderer does not compute "latencies" between them — that delta reflects DC's serialization order, not how long the LLM call took.
+- **Data Cloud materialization lag** — fresh sessions may show `interactions_not_materialized_yet` if STDM hasn't caught up. Re-run after a minute or two.

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

@@ -0,0 +1,51 @@
+-- App-layer generation records — reusable for any WHERE filter.
+-- DMO: GenAIAppGeneration__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
+--
+-- Sibling of GenAIGeneration__dlm: where GenAIGeneration is the raw
+-- gateway response, GenAIAppGeneration appears to be the app/feature-
+-- layer view of the same generation (separate `id__c` from `generationId__c`).
+--
+-- No `ssot__` prefix — fields end in `__c` directly.
+--
+-- Join to a session: the same Step → Generation bridge used for
+-- GenAIGeneration also works here. Pull session steps, collect
+-- non-empty `ssot__GenerationId__c` values, then query here with
+-- `generationId__c IN (...)`. The App-Generation row points at the
+-- same underlying gateway generation.
+--
+-- The DMO is provisioned by default on orgs with generative AI audit
+-- enabled, but row population depends on whether the org uses app-layer
+-- regeneration / update flows. Verify presence with `sf ssot/metadata`
+-- before relying on it.
+
+SELECT
+    id__c,
+    generationId__c,
+    generationUpdate__c,
+    generationUpdateId__c,
+    feature__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIAppGeneration__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- App-generations for a set of step generation ids
+-- WHERE    → generationId__c IN ('<gen_id1>','<gen_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- App-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

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

@@ -0,0 +1,44 @@
+-- GenAI content category (per-detector rows) — reusable WHERE.
+-- DMO: GenAIContentCategory__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
+--
+-- Two shapes of parent FK:
+--   - Direct on a generation: non-TOXICITY detectors (InstructionAdherence,
+--     TaskResolution, PII, PROMPT_DEFENSE) — parent__c = generationId__c
+--   - Via a quality row: TOXICITY sub-categories —
+--     parent__c = GenAIContentQuality.id__c
+--
+-- NOTE: No `ssot__` prefix — fields end in `__c` directly.
+
+SELECT
+    id__c,
+    parent__c,
+    detectorType__c,
+    category__c,
+    value__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIContentCategory__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Non-TOXICITY detectors for a set of generations (direct join)
+-- WHERE    → parent__c IN ('<gen_id1>','<gen_id2>')
+--            AND detectorType__c != 'TOXICITY'
+
+-- TOXICITY sub-categories for a set of quality rows
+-- WHERE    → parent__c IN ('<quality_id1>','<quality_id2>')
+--            AND detectorType__c = 'TOXICITY'
+
+-- InstructionAdherence scores only
+-- WHERE    → parent__c IN ('<gen_id1>','<gen_id2>')
+--            AND detectorType__c = 'InstructionAdherence'

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

@@ -0,0 +1,41 @@
+-- GenAI content quality (per-generation quality rows) — reusable WHERE.
+-- DMO: GenAIContentQuality__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
+--
+-- Joined to a generation via `parent__c = generationId__c`. One row per
+-- INPUT/OUTPUT side. `isToxicityDetected__c` is populated only on OUTPUT rows.
+--
+-- NOTE: No `ssot__` prefix — fields end in `__c` directly.
+
+SELECT
+    id__c,
+    parent__c,
+    isToxicityDetected__c,
+    contentType__c,
+    feature__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIContentQuality__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Quality rows for a set of generations
+-- WHERE    → parent__c IN ('<gen_id1>','<gen_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Only rows where toxicity was detected (OUTPUT rows)
+-- WHERE    → parent__c IN ('<gen_id1>','<gen_id2>')
+--            AND isToxicityDetected__c = 'true'
+
+-- Only OUTPUT-side rows
+-- WHERE    → parent__c IN ('<gen_id1>','<gen_id2>')
+--            AND contentType__c = 'OUTPUT'

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

@@ -0,0 +1,36 @@
+-- Session discovery — find candidate sessions by time/agent/channel/outcome/grep.
+-- Produces a short row-per-session shape for the picker rendered by
+-- scripts/discover_sessions.py. NOT used by the trace pipeline — once the user
+-- picks a UUID, the full pipeline runs fetch_dc.py against the 24-DMO waterfall.
+--
+-- Placeholders (substituted by scripts/dc.py.load_sql):
+--   SELECT_LIST  — either `s.ssot__Id__c, s.ssot__StartTimestamp__c, s.ssot__EndTimestamp__c,
+--                          s.ssot__AiAgentChannelType__c, s.ssot__AiAgentSessionEndType__c`
+--                 OR `DISTINCT <same columns>` when JOINs are present (DC SQL requires
+--                 ORDER BY columns to appear in a DISTINCT projection).
+--   JOINS        — zero or more JOIN clauses, newline-separated, or empty string:
+--                   * `JOIN ssot__AiAgentSessionParticipant__dlm p ON s.ssot__Id__c = p.ssot__AiAgentSessionId__c`
+--                     (required when filtering by --agent)
+--                   * `JOIN ssot__AiAgentInteraction__dlm i ON s.ssot__Id__c = i.ssot__AiAgentSessionId__c
+--                      JOIN ssot__AiAgentInteractionMessage__dlm m ON i.ssot__Id__c = m.ssot__AiAgentInteractionId__c`
+--                     (required when filtering by --grep)
+--   WHERE_CLAUSE — composed by the caller. No "WHERE" keyword. Always non-empty
+--                 (at minimum the time-range predicate). All user-supplied string
+--                 literals are single-quote-escaped by doubling quotes (O'Brien → O''Brien).
+--   LIMIT        — integer, 1..N. Default in caller is 20.
+--
+-- Field reference:
+--   time range → s.ssot__StartTimestamp__c >= '<startISO>' AND s.ssot__StartTimestamp__c < '<endISO>'
+--   outcome    → s.ssot__AiAgentSessionEndType__c = '<USER_ENDED|ESCALATED|TRANSFERRED|TIMEOUT|NOT_SET>'
+--   channel    → s.ssot__AiAgentChannelType__c = '<Builder|SCRT2 - EmbeddedMessaging|Voice|...>'
+--   agent      → p.ssot__AiAgentApiName__c = '<AgentApiName>'  (requires participant JOIN)
+--   grep       → m.ssot__ContentText__c LIKE '%<escaped-pattern>%'  (requires interaction+message JOIN)
+--
+-- All STDM timestamps are UTC.
+
+SELECT {{SELECT_LIST}}
+FROM ssot__AIAgentSession__dlm s
+{{JOINS}}
+WHERE {{WHERE_CLAUSE}}
+ORDER BY s.ssot__StartTimestamp__c DESC
+LIMIT {{LIMIT}};

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

@@ -0,0 +1,47 @@
+-- User feedback on generations — one row per feedback event.
+-- DMO: GenAIFeedback__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
+--
+-- Captures thumbs-up/thumbs-down (and richer `action__c`) that a user gave
+-- a specific generation. Joined via `generationId__c = Generation.generationId__c`.
+-- `feedbackId__c` is the PK that GenAIFeedbackDetail rows point at.
+--
+-- NOTE: No `ssot__` prefix — fields end in `__c` directly.
+
+SELECT
+    feedbackId__c,
+    generationId__c,
+    generationUpdateId__c,
+    generationGroupId__c,
+    userId__c,
+    feedback__c,
+    action__c,
+    source__c,
+    feature__c,
+    appType__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIFeedback__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Feedback for a set of generations (typical session trace path)
+-- WHERE    → generationId__c IN ('<gen_id1>','<gen_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Feedback by a specific user in a time window
+-- WHERE    → userId__c = '<user_id>'
+--            AND timestamp__c >= '<iso_cutoff>'
+
+-- Only thumbs-down
+-- WHERE    → generationId__c IN ('<gen_id1>','<gen_id2>')
+--            AND feedback__c = 'DOWN'

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

@@ -0,0 +1,38 @@
+-- Free-text / structured detail attached to a feedback event.
+-- DMO: GenAIFeedbackDetail__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
+--
+-- Zero or more rows per feedback. `feedbackText__c` is what the user typed;
+-- `appFeedback__c` is an app-layer tag (e.g. the reason bucket).
+-- Joined via `parent__c = GenAIFeedback.feedbackId__c`.
+--
+-- NOTE: No `ssot__` prefix — fields end in `__c` directly.
+
+SELECT
+    feedbackDetailId__c,
+    parent__c,
+    feedbackText__c,
+    appFeedback__c,
+    feature__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIFeedbackDetail__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Details for a set of feedback rows
+-- WHERE    → parent__c IN ('<feedback_id1>','<feedback_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Free-text feedback only (DC Query returns "" for unset text, not NULL)
+-- WHERE    → parent__c IN ('<feedback_id1>','<feedback_id2>')
+--            AND feedbackText__c IS NOT NULL AND feedbackText__c != ''

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

@@ -0,0 +1,45 @@
+-- Gateway object records — structured attachments on requests/feedback.
+-- DMO: GenAIGtwyObjRecord__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
+--
+-- Polymorphic attachment table. `parent__c` points at different parents
+-- depending on `type__c`:
+--   - `parent__c = GenAIGatewayRequest.gatewayRequestId__c` (grounded-record
+--     attachments) — the forward-only path used by this skill's waterfall.
+--   - `parent__c = GenAIFeedback.feedbackId__c` (feedback attachments) —
+--     present only when the session has feedback rows.
+-- The waterfall queries the gateway-request case (wave 3); feedback attachments
+-- appear through the session only when feedback is present.
+--
+-- NOTE: No `ssot__` prefix — fields end in `__c` directly.
+
+SELECT
+    id__c,
+    parent__c,
+    recordId__c,
+    type__c,
+    name__c,
+    value__c,
+    metadata__c,
+    feature__c,
+    timestamp__c,
+    orgId__c,
+    cloud__c
+FROM GenAIGtwyObjRecord__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- Records attached to a set of feedback rows
+-- WHERE    → parent__c IN ('<feedback_id1>','<feedback_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Records attached to a set of gateway request ids
+-- WHERE    → parent__c IN ('<req_id1>','<req_id2>')

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

@@ -0,0 +1,50 @@
+-- Per-request LLM call diagnostics — reusable for any WHERE filter.
+-- DMO: GenAIGtwyRequestLLM__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. Captures LLM invocation
+-- diagnostics (latency, status, endpoint, region, model). Populated
+-- only when Trust Layer gateway LLM telemetry is on.
+--
+-- The DMO is provisioned by default but rows only appear when the
+-- gateway LLM telemetry is emitted. Join column pattern mirrors
+-- GenAIGtwyRequestMetadata__dlm (same parent__c shape).
+--
+-- No `ssot__` prefix — fields end in `__c` directly. Note that org id
+-- is `salesforceOrgId__c` on this DMO, not the usual `orgId__c`.
+--
+-- Joined via `parent__c = GatewayRequest.gatewayRequestId__c`.
+
+SELECT
+    id__c,
+    parent__c,
+    endpoint__c,
+    region__c,
+    genAILLM__c,
+    llmCallStatus__c,
+    llmCallLatency__c,
+    llmErrorTrace__c,
+    metadata__c,
+    feature__c,
+    salesforceOrgId__c,
+    timestamp__c,
+    cloud__c
+FROM GenAIGtwyRequestLLM__dlm
+WHERE {{WHERE_CLAUSE}}
+{{ORDER_BY}};
+
+
+-- ============================================================================
+-- EXAMPLE WHERE clauses (pass via where_clause=)
+-- ============================================================================
+
+-- All LLM diagnostic rows for a set of gateway request ids
+-- WHERE    → parent__c IN ('<req_id1>','<req_id2>',...)
+-- ORDER BY → ORDER BY timestamp__c
+
+-- Only failed LLM calls
+-- WHERE    → parent__c IN ('<req_id1>','<req_id2>')
+--            AND llmCallStatus__c != 'success'