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_identity_coherence.py

View on GitHub
"""Top-level vs nested identity coherence under manifest-placeholder shapes.

Regression coverage for the bug where ``fetch_dc._resolve_identity`` falls
through its strict AGENT-participant pick (fetch_dc.py:570-597) on agent
shapes like MyAgent — leaving the manifest with
``agent_version="v0"`` (placeholder) — while wave 5 then materializes
``gateway_request_tags`` rows that carry the real ``v24``. The harvester
``_build_session_identity`` correctly reads ``v24`` into
``session.identity.agent_version``, but the top-level ``identity`` block
was previously copied straight off the manifest and silently disagreed
with the same JSON file's nested copy.

These tests pin the promotion policy implemented by
``_promote_identity`` / ``_reconcile_top_identity``:

  - manifest "v0" + session "v24"     -> top promotes to v24
  - manifest "v3" + session None      -> top stays v3 (manifest wins)
  - manifest api None + session real  -> top promotes
  - manifest "v3" + session "v5"      -> top stays v3 (manifest wins;
                                          strict AGENT pick is intentional)
  - manifest "v0" + session "v0"      -> top stays v0 (no real value
                                          available; placeholder leak
                                          remains visible to investigator)

Plus a full round-trip through ``assemble_dc.assemble`` to confirm the
top-level and nested identity records agree on a real MyAgent-shape
session.
"""
from __future__ import annotations

import json
import unittest
from copy import deepcopy
from pathlib import Path
from tempfile import TemporaryDirectory
from unittest import mock

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

import assemble_dc  # type: ignore
from config import paths  # type: ignore
from .fixtures.synthetic_session import (  # type: ignore
    IDS, make_manifest, make_rows, write_to_disk,
)


# -----------------------------------------------------------------------------
# Unit tests for _promote_identity (single-field policy)
# -----------------------------------------------------------------------------


class PromoteVersionTests(unittest.TestCase):
    """`_promote_identity(..., kind="version")` — placeholder-only promotion."""

    def test_v0_placeholder_promoted_when_session_has_real_version(self):
        out = assemble_dc._promote_identity("v0", "v24", kind="version")
        self.assertEqual(out, "v24")

    def test_keeps_manifest_value_when_session_identity_is_none(self):
        # Manifest already real; no reason to look elsewhere.
        out = assemble_dc._promote_identity("v3", None, kind="version")
        self.assertEqual(out, "v3")

    def test_keeps_v0_when_session_also_returns_v0(self):
        # No real value harvestable. Placeholder remains visible so
        # the investigator can still see the resolution failed.
        out = assemble_dc._promote_identity("v0", "v0", kind="version")
        self.assertEqual(out, "v0")

    def test_keeps_v0_when_session_value_is_garbage(self):
        # Session shouldn't be able to "promote" a non-version-shaped string.
        out = assemble_dc._promote_identity("v0", "garbage", kind="version")
        self.assertEqual(out, "v0")

    def test_keeps_v0_when_session_value_is_none(self):
        out = assemble_dc._promote_identity("v0", None, kind="version")
        self.assertEqual(out, "v0")

    def test_no_promotion_when_both_real_but_disagree(self):
        # Strict AGENT-row pick is intentional — manifest wins.
        out = assemble_dc._promote_identity("v3", "v5", kind="version")
        self.assertEqual(out, "v3")


class PromoteApiNameTests(unittest.TestCase):
    """`_promote_identity(..., kind="api_name")` — NOT_SET-ish promotion."""

    def test_none_manifest_promoted_when_session_has_value(self):
        out = assemble_dc._promote_identity(
            None, "MyAgent", kind="api_name",
        )
        self.assertEqual(out, "MyAgent")

    def test_not_set_string_promoted_when_session_has_value(self):
        out = assemble_dc._promote_identity(
            "NOT_SET", "MyAgent", kind="api_name",
        )
        self.assertEqual(out, "MyAgent")

    def test_empty_manifest_promoted_when_session_has_value(self):
        out = assemble_dc._promote_identity("", "MyAgent", kind="api_name")
        self.assertEqual(out, "MyAgent")

    def test_keeps_manifest_value_when_session_is_none(self):
        # Symmetric of the version case — manifest wins when session
        # has nothing to offer.
        out = assemble_dc._promote_identity(
            "MyAgent", None, kind="api_name",
        )
        self.assertEqual(out, "MyAgent")

    def test_keeps_manifest_when_both_real(self):
        out = assemble_dc._promote_identity(
            "ManifestAgent", "SessionAgent", kind="api_name",
        )
        self.assertEqual(out, "ManifestAgent")


# -----------------------------------------------------------------------------
# Reconcile helper — composed policy across both fields + stderr note
# -----------------------------------------------------------------------------


class ReconcileTopIdentityTests(unittest.TestCase):

    def test_reconcile_emits_stderr_note_when_version_promoted(self):
        manifest = {"agent_api_name": "MyAgent", "agent_version": "v0"}
        session_identity = {
            "agent_api_name": None,
            "agent_version": "v24",
        }
        with mock.patch("sys.stderr") as fake_stderr:
            top = assemble_dc._reconcile_top_identity(
                manifest, session_identity, "00DXX0000000ABC",
            )
        self.assertEqual(top["agent_version"], "v24")
        self.assertEqual(top["agent_api_name"], "MyAgent")
        self.assertEqual(top["org_id_15"], "00DXX0000000ABC")
        # The stderr note format is part of the contract — at least
        # one print call mentioning "promoted" must fire.
        emitted = [
            call.args[0] for call in fake_stderr.write.call_args_list
            if call.args
        ]
        self.assertTrue(
            any("promoted" in str(s) for s in emitted),
            f"expected promotion note on stderr; got writes: {emitted}",
        )

    def test_reconcile_silent_when_no_promotion_needed(self):
        manifest = {"agent_api_name": "DemoAgent", "agent_version": "v5"}
        session_identity = {
            "agent_api_name": "DemoAgent",
            "agent_version": "v5",
        }
        with mock.patch("sys.stderr") as fake_stderr:
            top = assemble_dc._reconcile_top_identity(
                manifest, session_identity, "00DXX0000000ABC",
            )
        self.assertEqual(top["agent_version"], "v5")
        emitted = [
            call.args[0] for call in fake_stderr.write.call_args_list
            if call.args
        ]
        self.assertFalse(
            any("promoted" in str(s) for s in emitted),
            f"unexpected promotion note: {emitted}",
        )


# -----------------------------------------------------------------------------
# Full-fixture round-trip — MyAgent-shape session through assemble()
# -----------------------------------------------------------------------------


def _serviceagent2_shape_disk_writer(tmp_root: Path) -> Path:
    """Materialize a MyAgent-shape session under tmp_root.

    Mutates the synthetic fixture so that:

      - manifest carries the placeholder ``agent_version="v0"`` (mirrors
        what ``fetch_dc._resolve_identity``'s fallback stamps).
      - the AGENT participant row has its ``ssot__AiAgentVersionApiName__c``
        cleared to NOT_SET (so ``_build_session_identity`` doesn't pick up
        a version from there).
      - ``gateway_request_tags`` carries an ``agent_version_api_name=v24``
        tag against the declared GW request, so the harvester finds the
        real value.

    The session dir lives under ``<org>/<api_name>__v0/<sid>/`` to match the
    placeholder-stamped layout fetch_dc actually writes on this path.
    """
    rows = make_rows()

    # AGENT row: clear version so _build_session_identity has no hint
    # via that path; the harvest must come from gateway_request_tags.
    for p in rows["participants"]:
        if p.get("ssot__AiAgentSessionParticipantRole__c") == "AGENT":
            p["ssot__AiAgentVersionApiName__c"] = "NOT_SET"

    # Add the agent_version_api_name tag against the declared GW request.
    rows["gateway_request_tags"].append({
        "id__c": "tag-agent-version",
        "parent__c": IDS.GW_REQ_DECLARED,
        "tag__c": "agent_version_api_name",
        "tagValue__c": '"v24"',  # quoted form mirrors live shape
    })
    # Plus agent_developer_name so session.identity.agent_api_name
    # also gets a real value to test the api_name path.
    rows["gateway_request_tags"].append({
        "id__c": "tag-agent-dev",
        "parent__c": IDS.GW_REQ_DECLARED,
        "tag__c": "agent_developer_name",
        "tagValue__c": '"MyAgent"',
    })

    # Manifest: placeholder version, real api_name (matches the
    # MyAgent fallback's actual output — it stamps api_name from
    # any participant row but version is forced to "v0").
    manifest = make_manifest()
    manifest["agent_api_name"] = "MyAgent"
    manifest["agent_version"] = "v0"
    manifest["org_id_15"] = IDS.ORG_ID_15

    # Layout: <org>/<api_name>__v0/<sid>/ — the placeholder-shaped dir.
    sdir = tmp_root / IDS.ORG_ID_15 / "MyAgent__v0" / IDS.SID
    sdir.mkdir(parents=True, exist_ok=True)

    (sdir / "dc._session_manifest.json").write_text(
        json.dumps(manifest, indent=2) + "\n"
    )
    for name, rs in rows.items():
        if rs:
            (sdir / f"dc.{name}.json").write_text(
                json.dumps(rs, indent=2) + "\n"
            )

    # Breadcrumb for _find_session_dir's primary path.
    link_dir = tmp_root / IDS.ORG_ID_15 / "_sessions"
    link_dir.mkdir(parents=True, exist_ok=True)
    (link_dir / f"{IDS.SID}.link").write_text(
        f"../MyAgent__v0/{IDS.SID}\n"
    )
    return sdir


class AssembleEndToEndIdentityCoherenceTests(unittest.TestCase):
    """The bug repro — top-level vs nested identity must agree after fix."""

    def test_top_identity_promoted_when_manifest_has_v0_and_tags_have_v24(self):
        with TemporaryDirectory() as tmp:
            tmp_root = Path(tmp)
            _serviceagent2_shape_disk_writer(tmp_root)
            with mock.patch.object(paths, "DATA_ROOT", tmp_root):
                tree, _ = assemble_dc.assemble(IDS.SID)
        # The harvester (_build_session_identity) reads v24 from tags.
        self.assertEqual(tree["session"]["identity"]["agent_version"], "v24")
        # The top-level — previously v0 — must now agree.
        self.assertEqual(tree["identity"]["agent_version"], "v24")

    def test_top_and_session_identity_agree_on_agent_version(self):
        with TemporaryDirectory() as tmp:
            tmp_root = Path(tmp)
            _serviceagent2_shape_disk_writer(tmp_root)
            with mock.patch.object(paths, "DATA_ROOT", tmp_root):
                tree, _ = assemble_dc.assemble(IDS.SID)
        # The whole point of the fix.
        self.assertEqual(
            tree["identity"]["agent_version"],
            tree["session"]["identity"]["agent_version"],
        )

    def test_api_name_top_level_keeps_manifest_when_session_returns_null(self):
        # Mirror the live live-verification observation: top-level
        # api_name is "MyAgent" (from manifest), session.identity
        # api_name is None because no agent_developer_name tag fired.
        # Strip the agent_developer_name tag we added in the helper.
        with TemporaryDirectory() as tmp:
            tmp_root = Path(tmp)
            _serviceagent2_shape_disk_writer(tmp_root)
            sdir = tmp_root / IDS.ORG_ID_15 / "MyAgent__v0" / IDS.SID
            tags_path = sdir / "dc.gateway_request_tags.json"
            tags = json.loads(tags_path.read_text())
            tags = [t for t in tags if t.get("tag__c") != "agent_developer_name"]
            tags_path.write_text(json.dumps(tags, indent=2) + "\n")

            with mock.patch.object(paths, "DATA_ROOT", tmp_root):
                tree, _ = assemble_dc.assemble(IDS.SID)
        # session.identity.agent_api_name None — no harvestable value.
        self.assertIsNone(tree["session"]["identity"]["agent_api_name"])
        # Top-level keeps manifest's "MyAgent" — promotion does NOT
        # erase a real manifest value when session has nothing to offer.
        self.assertEqual(tree["identity"]["agent_api_name"], "MyAgent")


# -----------------------------------------------------------------------------
# Sanity: the existing happy-path fixture still produces matching identity
# (regression guard against the fix mutating the simple case).
# -----------------------------------------------------------------------------


class HappyPathStillCoherentTests(unittest.TestCase):

    def test_happy_path_unchanged(self):
        # The synthetic fixture's gateway_request_tags don't include
        # `agent_version_api_name`, so session.identity.agent_version is
        # None on this path. The fix's policy preserves the manifest
        # value ("v5") in that case — verifying the no-promote branch
        # doesn't accidentally null out the top-level when the harvest
        # layer has nothing to offer.
        with TemporaryDirectory() as tmp:
            tmp_root = Path(tmp)
            write_to_disk(tmp_root)
            with mock.patch.object(paths, "DATA_ROOT", tmp_root):
                tree, _ = assemble_dc.assemble(IDS.SID)
        self.assertEqual(tree["identity"]["agent_version"], IDS.AGENT_VERSION)
        self.assertEqual(tree["identity"]["agent_api_name"], IDS.AGENT_API)
        # session.identity may be None here (no agent_version_api_name tag);
        # the top-level keeps the manifest's real value, which is the point.
        self.assertIn(
            tree["session"]["identity"]["agent_version"],
            (None, IDS.AGENT_VERSION),
        )


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