Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-d360-analyze

agentforce-d360-analyze

Verified

Data Cloud 360° view of a single Agentforce session. 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 agentforce-architecture-analyze instead) or for runtime perf/latency/SLO questions that require platform telemetry beyond Data Cloud.

FileKindSize
README.mdmarkdown6.2 KB
SKILL.mdskill md13.2 KB
assets/dc/app_generation.sqlother1.9 KB
assets/dc/content_category.sqlother1.5 KB
assets/dc/content_quality.sqlother1.3 KB
assets/dc/discover_sessions.sqlother2.3 KB
assets/dc/feedback.sqlother1.5 KB
assets/dc/feedback_details.sqlother1.3 KB
assets/dc/gateway_records.sqlother1.6 KB
assets/dc/gateway_request_llm.sqlother1.6 KB
assets/dc/gateway_request_metadata.sqlother1.5 KB
assets/dc/gateway_request_tags.sqlother1.4 KB
assets/dc/gateway_requests.sqlother3.4 KB
assets/dc/gateway_responses.sqlother1.7 KB
assets/dc/generations.sqlother1.9 KB
assets/dc/interactions.sqlother2.0 KB
assets/dc/messages.sqlother2.1 KB
assets/dc/messaging_session.sqlother1.7 KB
assets/dc/moment_interactions.sqlother1.4 KB
assets/dc/moments.sqlother1.5 KB
assets/dc/participants.sqlother1.8 KB
assets/dc/sessions.sqlother3.0 KB
assets/dc/steps.sqlother2.6 KB
assets/dc/tag_associations.sqlother1.7 KB
assets/dc/tag_definition_associations.sqlother1.4 KB
assets/dc/tag_definitions.sqlother1.8 KB
assets/dc/tags.sqlother1.3 KB
assets/dc/telemetry_spans.sqlother2.1 KB
references/artifacts.mdmarkdown2.7 KB
references/dc_dmo_fields.mdmarkdown42.1 KB
references/dc_pipeline_contract.mdmarkdown26.3 KB
scripts/_shared/__init__.pyscript122 B
scripts/_shared/cli_override.pyscript3.3 KB
scripts/_shared/fs_guard.pyexecutablescript13.2 KB
scripts/_shared/paths.pyscript5.8 KB
scripts/_shared/runtime.pyscript2.0 KB
scripts/_shared/sql.pyscript548 B
scripts/assemble_dc.pyscript69.6 KB
scripts/config.pyscript1.8 KB
scripts/dc.pyscript13.8 KB
scripts/discover_sessions.pyscript21.1 KB
scripts/fetch_dc.pyscript45.1 KB
scripts/render_dc.pyscript69.7 KB
scripts/resolve_session.pyscript10.8 KB
scripts/storage.pyscript3.1 KB
scripts/tests/__init__.pyscript0 B
scripts/tests/_bootstrap.pyscript483 B
scripts/tests/fixtures/__init__.pyscript0 B
scripts/tests/fixtures/synthetic_session.pyscript14.6 KB
scripts/tests/test_assemble_dc_bootstrap_and_mode.pyscript4.2 KB
scripts/tests/test_assemble_dc_gateway_direct.pyscript8.3 KB
scripts/tests/test_assemble_dc_gateway_direct_integration.pyscript6.4 KB
scripts/tests/test_assemble_dc_helpers.pyscript10.0 KB
scripts/tests/test_assemble_dc_integration.pyscript9.3 KB
scripts/tests/test_dc_and_resolve_session.pyscript26.7 KB
scripts/tests/test_default_target_org.pyscript18.8 KB
scripts/tests/test_discover_sessions.pyscript19.0 KB
scripts/tests/test_discover_sessions_grep_ci.pyscript8.2 KB
scripts/tests/test_fetch_dc_helpers.pyscript10.6 KB
scripts/tests/test_fetch_dc_identity.pyscript22.0 KB
scripts/tests/test_fetch_dc_main.pyscript9.4 KB
scripts/tests/test_fetch_dc_waterfall.pyscript8.6 KB
scripts/tests/test_fetch_dc_waterfall_full.pyscript11.2 KB
scripts/tests/test_identity_coherence.pyscript13.8 KB
scripts/tests/test_render_dc_branches.pyscript9.9 KB
scripts/tests/test_render_dc_gateway_direct.pyscript5.1 KB
scripts/tests/test_render_dc_helpers.pyscript10.5 KB
scripts/tests/test_render_dc_integration.pyscript7.7 KB
scripts/tests/test_render_dc_planner_llm_calls.pyscript11.8 KB
scripts/tests/test_render_dc_show_prompts_gating.pyscript8.7 KB
scripts/tests/test_resolve_from_disk.pyscript4.1 KB
scripts/tests/test_resolve_session_main.pyscript5.2 KB
scripts/tests/test_runtime_override.pyscript4.2 KB
scripts/tests/test_session_shape.pyscript3.5 KB
scripts/tests/test_session_shape_dropped_by_stdm.pyscript3.5 KB
scripts/tests/test_skill_md_prefix_block.pyscript6.8 KB

scripts/tests/test_fetch_dc_waterfall_full.py

View on GitHub
"""End-to-end waterfall tests for ``fetch_dc._run_waterfall``.

Mocks ``dc.post`` at the network boundary; dispatches per-query fixture
rows so the 5-wave orchestration runs to completion. Asserts on:

- per-query manifest entries (rows, status, wave)
- harvested_ids tracking across waves
- session_shape classification
- on-disk dc.<name>.json artifacts written by ``storage.save``
"""
from __future__ import annotations

import json
import unittest
from datetime import datetime, timezone
from pathlib import Path
from tempfile import TemporaryDirectory
from unittest import mock

from . import _bootstrap  # noqa: F401  — sys.path setup

import fetch_dc  # type: ignore
from config import paths  # type: ignore
from .fixtures.synthetic_session import IDS, make_rows  # type: ignore


def _build_fixture_dispatch() -> dict[str, list[dict]]:
    """Return rows keyed by DMO name for the synthetic session fixture."""
    return make_rows()


def _make_post_dispatcher(rows_by_name: dict[str, list[dict]]):
    """Return a fake ``dc.post`` that dispatches to the right fixture
    rows by inspecting the query_name argument."""
    def fake_post(sql: str, instance_url: str, token: str, query_name: str = ""):
        # `_fetch` passes the template name as query_name; that's exactly
        # what we keyed on in the fixture.
        return list(rows_by_name.get(query_name, []))
    return fake_post


def _make_ctx(tmpdir: Path) -> dict:
    """Build the same ctx shape that fetch_dc.main() builds."""
    return {
        "session_id": IDS.SID,
        "org_alias": "my-org",
        "instance_url": "https://example.salesforce.com",
        "token": "TOKEN",
        "verbose": False,
        "queries": [],
        "started_at": datetime.now(timezone.utc),
        "org_id_15": None,
        "agent_api_name": None,
        "agent_version": None,
    }


class _WaterfallHarness:
    """Patch DATA_ROOT + dc.post; build ctx; run the waterfall."""

    def __init__(self, *, rows_overrides: dict[str, list[dict]] | None = None):
        self.rows_overrides = rows_overrides or {}

    def __enter__(self):
        self._tmp = TemporaryDirectory()
        self._tmpdir = Path(self._tmp.name)
        self.ctx = _make_ctx(self._tmpdir)
        rows = _build_fixture_dispatch()
        rows.update(self.rows_overrides)
        self._post = _make_post_dispatcher(rows)
        self._patches = [
            mock.patch.object(paths, "DATA_ROOT", self._tmpdir),
            mock.patch.object(fetch_dc, "post", side_effect=self._post),
            # Keep _log quiet during tests
            mock.patch.object(fetch_dc, "_log"),
        ]
        for p in self._patches:
            p.start()
        return self

    def __exit__(self, *exc):
        for p in self._patches:
            p.stop()
        self._tmp.cleanup()

    def session_dir(self) -> Path:
        # macOS resolves /var → /private/var; resolve once so `is_file`
        # checks work after storage.save's path composition.
        return (
            self._tmpdir.resolve()
            / IDS.ORG_ID_15
            / f"{IDS.AGENT_API}__{IDS.AGENT_VERSION}"
            / IDS.SID
        )


# -----------------------------------------------------------------------------
# Identity stamping (wave 1a)
# -----------------------------------------------------------------------------


class WaterfallIdentityTests(unittest.TestCase):

    def test_identity_resolved_into_ctx_after_wave_1a(self):
        with _WaterfallHarness() as h:
            fetch_dc._run_waterfall(h.ctx)
        self.assertEqual(h.ctx["org_id_15"], IDS.ORG_ID_15)
        self.assertEqual(h.ctx["agent_api_name"], IDS.AGENT_API)
        self.assertEqual(h.ctx["agent_version"], IDS.AGENT_VERSION)

    def test_sessions_and_participants_persisted_after_identity_resolved(self):
        # The deferred-save flush in wave 1a should write both files.
        with _WaterfallHarness() as h:
            fetch_dc._run_waterfall(h.ctx)
            # Search the entire tmp tree — avoids macOS /private/var ↔ /var
            # resolution discrepancies between paths.session_dir() and our
            # locally-built path.
            written = {p.name for p in h._tmpdir.rglob("dc.*.json")}
        self.assertIn("dc.sessions.json", written)
        self.assertIn("dc.participants.json", written)


# -----------------------------------------------------------------------------
# Wave-by-wave artifact persistence
# -----------------------------------------------------------------------------


class WaterfallWritesArtifactsTests(unittest.TestCase):

    def test_populated_dmos_emit_dc_json_artifacts(self):
        with _WaterfallHarness() as h:
            fetch_dc._run_waterfall(h.ctx)
            files = {p.name for p in h._tmpdir.rglob("dc.*.json")}
        # 11 DMOs are populated in the synthetic fixture; each lands as a file.
        for name in (
            "dc.sessions.json", "dc.interactions.json", "dc.steps.json",
            "dc.messages.json", "dc.participants.json",
            "dc.gateway_requests.json", "dc.gateway_responses.json",
            "dc.generations.json", "dc.content_quality.json",
            "dc.gateway_records.json", "dc.gateway_request_tags.json",
        ):
            self.assertIn(name, files, f"{name} should be on disk")

    def test_zero_row_dmos_skipped_no_artifact(self):
        with _WaterfallHarness() as h:
            fetch_dc._run_waterfall(h.ctx)
            files = {p.name for p in h._tmpdir.rglob("dc.*.json")}
        # `tags` and friends have empty rows → no on-disk artifact.
        self.assertNotIn("dc.tags.json", files)
        self.assertNotIn("dc.tag_definitions.json", files)


# -----------------------------------------------------------------------------
# Manifest entries (one per query)
# -----------------------------------------------------------------------------


class WaterfallManifestTests(unittest.TestCase):

    def test_24_query_entries_appended(self):
        with _WaterfallHarness() as h:
            fetch_dc._run_waterfall(h.ctx)
        names = [q["name"] for q in h.ctx["queries"]]
        # Exactly the 24 templates fetch_dc declares (no duplicates from
        # tag_definitions retry: synthetic fixture's tag_definitions is
        # empty, so retry runs once and overwrites the prior empty entry).
        self.assertGreaterEqual(len(names), 24)
        # Critical names appear at least once
        for required in ("sessions", "interactions", "steps", "participants",
                         "gateway_requests", "generations", "messages"):
            self.assertIn(required, names)

    def test_each_query_has_wave_status_rows_elapsed_ms(self):
        with _WaterfallHarness() as h:
            fetch_dc._run_waterfall(h.ctx)
        for q in h.ctx["queries"]:
            self.assertIn("name", q)
            self.assertIn("wave", q)
            self.assertIn("rows", q)
            self.assertIn("status", q)
            self.assertIn("elapsed_ms", q)
            self.assertIn(q["status"], ("ok", "empty", "skipped", "error"))


# -----------------------------------------------------------------------------
# harvested_ids
# -----------------------------------------------------------------------------


class WaterfallHarvestedIdsTests(unittest.TestCase):

    def test_harvested_ids_match_fixture_counts(self):
        with _WaterfallHarness() as h:
            fetch_dc._run_waterfall(h.ctx)
            harvested = h.ctx["harvested_ids"]
        self.assertEqual(harvested["sessions"], 1)
        self.assertEqual(harvested["interactions"], 3)
        self.assertEqual(harvested["steps_total"], 3)
        self.assertEqual(harvested["gateway_request_ids"], 2)
        # moments DMO is empty; fetch_dc falls through to the participants
        # harvest (AGENT participant row carries IDS.AGENT_API = "DemoAgent").
        from .fixtures.synthetic_session import IDS  # type: ignore
        self.assertEqual(harvested["agents_observed"], [IDS.AGENT_API])

    def test_steps_by_type_categorizes_correctly(self):
        with _WaterfallHarness() as h:
            fetch_dc._run_waterfall(h.ctx)
            sbt = h.ctx["harvested_ids"]["steps_by_type"]
        # Synthetic fixture has 1 each of TOPIC_STEP, ACTION_STEP, TRUST_GUARDRAILS_STEP
        self.assertEqual(sbt["ACTION_STEP"], 1)
        self.assertEqual(sbt["TOPIC_STEP"], 1)
        self.assertEqual(sbt["TRUST_GUARDRAILS_STEP"], 1)
        self.assertEqual(sbt["LLM_STEP"], 0)


# -----------------------------------------------------------------------------
# Session-shape classification
# -----------------------------------------------------------------------------


class WaterfallSessionShapeTests(unittest.TestCase):

    def test_normal_session_classified_as_complete(self):
        with _WaterfallHarness() as h:
            fetch_dc._run_waterfall(h.ctx)
        self.assertEqual(h.ctx["session_shape"], "complete")

    def test_no_steps_with_gateway_requests_classified_as_lag(self):
        # Override: empty interactions/steps/messages but keep gateway_requests.
        rows = make_rows()
        rows["interactions"] = []
        rows["steps"] = []
        rows["messages"] = []
        with _WaterfallHarness(rows_overrides=rows) as h:
            fetch_dc._run_waterfall(h.ctx)
        self.assertEqual(h.ctx["session_shape"], "interactions_not_materialized_yet")

    def test_steps_no_llm_no_gateway_classified_as_abandoned(self):
        # ACTION_STEP + TOPIC_STEP exist but no LLM_STEP and no gateway_requests.
        rows = make_rows()
        rows["gateway_requests"] = []
        rows["gateway_responses"] = []
        rows["gateway_records"] = []
        rows["gateway_request_tags"] = []
        with _WaterfallHarness(rows_overrides=rows) as h:
            fetch_dc._run_waterfall(h.ctx)
        self.assertEqual(h.ctx["session_shape"], "abandoned_before_llm")


# -----------------------------------------------------------------------------
# Empty harvest branches (zero IDs → _fetch_empty path)
# -----------------------------------------------------------------------------


class WaterfallEmptyHarvestTests(unittest.TestCase):

    def test_no_interactions_skips_steps_via_fetch_empty(self):
        rows = make_rows()
        rows["interactions"] = []
        with _WaterfallHarness(rows_overrides=rows) as h:
            fetch_dc._run_waterfall(h.ctx)
        # The steps query should be in the manifest as 'skipped'.
        steps_entries = [q for q in h.ctx["queries"] if q["name"] == "steps"]
        self.assertEqual(len(steps_entries), 1)
        self.assertEqual(steps_entries[0]["status"], "skipped")
        self.assertIn("no interactions", steps_entries[0]["_unavailable_reason"])

    def test_no_gateway_requests_skips_audit_chain(self):
        rows = make_rows()
        rows["gateway_requests"] = []
        with _WaterfallHarness(rows_overrides=rows) as h:
            fetch_dc._run_waterfall(h.ctx)
        # gateway_responses + tags + records + metadata + llm all skipped
        for name in ("gateway_responses", "gateway_request_tags",
                     "gateway_records", "gateway_request_metadata",
                     "gateway_request_llm"):
            entries = [q for q in h.ctx["queries"] if q["name"] == name]
            self.assertEqual(entries[0]["status"], "skipped",
                             f"{name} should be skipped")


if __name__ == "__main__":
    unittest.main()
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall