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/dc.py

View on GitHub
"""Data Cloud queries for investigating-agentforce-d360.

Two responsibilities:

1. **Templates.** `load_sql(name, **params)` reads `assets/dc/*.sql` and
   substitutes `{{PLACEHOLDER}}` values. `parse(response)` turns a DC
   query response into a list of row dicts. Neither knows specific
   column names — those live in the .sql files.

2. **Transport.** `resolve_org(alias)` shells out to `sf org display`
   for the instance URL and `sf org auth show-access-token` for the
   access token. `post(sql, instance_url, token)`
   POSTs the SQL to the Data Cloud Query API and returns parsed rows.
   Errors route through `DCQueryError` with the full response body + SQL
   context so callers can surface a useful message.
   `default_target_org()` reads the sf CLI default target org for entry
   points invoked without `--org`. Both it and `resolve_org` run the
   `show-access-token` capability preflight as their first sf call, so on
   either path a too-old CLI fails with the upgrade message first.

Persistence lives in `storage.save`.
"""
from __future__ import annotations

import json
import re
import subprocess
import sys
import urllib.error
import urllib.request
from pathlib import Path

from config import DC_API_PATH

SQL_DIR = Path(__file__).parent.parent / "assets" / "dc"


class DCQueryError(RuntimeError):
    """Data Cloud query failed. Carries full response body + SQL context."""


# ---- templates -------------------------------------------------------------

def load_sql(name: str, **params: str) -> str:
    """Read assets/dc/<name>.sql and substitute {{PARAM}} placeholders.

    Add a new query by dropping a `.sql` file into `assets/dc/` — no
    python edits needed. Callers pass whichever placeholders that
    template defines.
    """
    sql = (SQL_DIR / f"{name}.sql").read_text()
    for key, value in params.items():
        sql = sql.replace(f"{{{{{key}}}}}", value)
    return sql.strip()


def parse(response: dict | None) -> list[dict]:
    """Data Cloud response → list of row dicts. No field knowledge.

    Callers pick whatever columns they need by ssot__* name. Empty list
    means "no response" or "zero rows" — callers decide whether that's
    a partial state worth flagging.
    """
    if not response:
        return []
    return response.get("data") or []


# ---- transport -------------------------------------------------------------

_REDACTION_MARKER_FRAGMENT = "show-access-token"
"""Substring identifying the sf CLI v2 redaction placeholder. The full
literal is `"[REDACTED] Use 'sf org auth show-access-token' to view"`,
but we match on the embedded subcommand name because the surrounding
wording has shifted across sf CLI builds while the subcommand has been
stable since forcedotcom/cli#3560 landed."""


# Token-redaction patterns, vendored from agentforce-architecture-analyze's
# rest_client (this skill is self-contained and must not import across
# skills). sf CLI failure output can echo the access token — e.g. a
# `show-access-token --json` run that exits non-zero with the payload on
# stdout — so every stderr/stdout string is scrubbed before it reaches a
# SystemExit message. Deliberately permissive: over-redact, never leak.
_AUTH_HEADER_RE = re.compile(r"(Authorization\s*:\s*Bearer\s+)\S+", re.IGNORECASE)  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
_BEARER_RE = re.compile(r"(\bBearer\s+)[^\s\"']+", re.IGNORECASE)  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
_ACCESS_TOKEN_QS_RE = re.compile(r"(access[_]?token\s*=\s*)[^&\s\"']+", re.IGNORECASE)  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
_ACCESS_TOKEN_JSON_RE = re.compile(r"(\"access[_]?token\"\s*:\s*\")[^\"]*", re.IGNORECASE)  # @rule-suppress starter-sec-002 — re.compile, not exec/eval


def _redact_text(text: str | None) -> str:
    """Scrub bearer tokens and accessToken values from sf CLI output."""
    if not text:
        return ""
    text = _AUTH_HEADER_RE.sub(r"\1<redacted>", text)
    text = _BEARER_RE.sub(r"\1<redacted>", text)
    text = _ACCESS_TOKEN_QS_RE.sub(r"\1<redacted>", text)
    text = _ACCESS_TOKEN_JSON_RE.sub(r"\1<redacted>", text)
    return text


def _run_sf_json(argv: list[str]) -> dict:
    """Shell out + parse JSON. SystemExits on FileNotFoundError /
    CalledProcessError so callers get a clean message instead of a stack.
    Failure output is redacted before it is surfaced."""
    try:
        r = subprocess.run(argv, capture_output=True, text=True, check=True)
    except FileNotFoundError:
        raise SystemExit("sf CLI not found on PATH — install Salesforce CLI first")
    except subprocess.CalledProcessError as e:
        detail = _redact_text((e.stderr or "").strip() or (e.stdout or "").strip())
        raise SystemExit(f"{' '.join(argv[:4])}... failed:\n{detail}") from None
    return json.loads(r.stdout)


_show_access_token_capability_ok = False
"""Set once the preflight succeeds; the check then never reruns in this
process. Failures are NOT cached, so a fixed PATH/upgrade is picked up on
the next call."""

_SHOW_ACCESS_TOKEN_HELP_SIGNATURE_RE = re.compile(
    r"\$\s*sf\s+org\s+auth\s+show-access-token\b"
)
"""USAGE-line form that real `--help` output always contains
(`$ sf org auth show-access-token -o <value> ...`). The bare command name is
not enough: unknown-command notices echo it too
(`Command org:auth:show-access-token not found`,
`show-access-token is not a sf command`). A zero-exit probe whose output
lacks the USAGE form is treated as a failed check."""

_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")


def _assert_show_access_token_capability() -> None:
    """Fail fast if the installed sf CLI lacks `sf org auth show-access-token`.

    That command is the only supported token-retrieval path
    (forcedotcom/cli#3560). Probing `--help` needs no org auth and turns a
    confusing downstream failure into an actionable upgrade message.
    `default_target_org` and `resolve_org` each call this first, ahead of
    every other sf call they make. A successful probe is cached for the
    process lifetime, so the second call costs nothing.

    Exit status alone is not trusted: a CLI build that answers an unknown
    command with exit 0 (e.g. printing top-level help or a "not found"
    notice) would otherwise pass. The probe therefore also requires the
    command's USAGE line (`$ sf org auth show-access-token`) in the
    ANSI-stripped stdout+stderr; if it is absent the check fails and is not
    cached.
    """
    global _show_access_token_capability_ok
    if _show_access_token_capability_ok:
        return
    try:
        proc = subprocess.run(
            ["sf", "org", "auth", "show-access-token", "--help"],
            capture_output=True,
            text=True,
            timeout=30,
            check=True,
        )
    except FileNotFoundError as exc:
        raise SystemExit(
            "sf CLI not found on PATH — install Salesforce CLI first"
        ) from exc
    except subprocess.CalledProcessError as exc:
        detail = (
            _redact_text((exc.stderr or "").strip() or (exc.stdout or "").strip())
            or "unknown error"
        )
        raise SystemExit(
            "sf CLI is missing required command "
            "'sf org auth show-access-token'. Upgrade/reinstall Salesforce CLI "
            "to a build that provides this command, then retry.\n"
            f"Preflight detail: {detail}"
        ) from exc
    except subprocess.TimeoutExpired as exc:
        raise SystemExit(
            "sf CLI capability preflight for 'sf org auth show-access-token' "
            "timed out after 30s"
        ) from exc
    help_text = _ANSI_ESCAPE_RE.sub(
        "", f"{proc.stdout or ''}\n{proc.stderr or ''}",
    )
    if not _SHOW_ACCESS_TOKEN_HELP_SIGNATURE_RE.search(help_text):
        # Zero exit without the command's help signature — the CLI did not
        # recognise the command. Fail (uncached) like a non-zero exit.
        # Redact before truncating so a token can never be split past the regex.
        detail = (
            _redact_text(help_text.strip())[:500]
            or "help output lacked the command signature"
        )
        raise SystemExit(
            "sf CLI is missing required command "
            "'sf org auth show-access-token'. Upgrade/reinstall Salesforce CLI "
            "to a build that provides this command, then retry.\n"
            f"Preflight detail: {detail}"
        )
    _show_access_token_capability_ok = True


NO_DEFAULT_ORG_MSG = (
    "no --org given and no default target org set — run "
    "`sf config set target-org <alias>` or pass --org <alias>"
)


def default_target_org() -> str:
    """Return the sf CLI default target org alias/username.

    Used by entry points when ``--org`` is omitted ("my org" means the CLI
    default). Reads ``.result[0].value`` from
    ``sf config get target-org --json``. Raises SystemExit with a clear,
    redacted message when the CLI is missing, fails, times out, returns
    non-JSON, or has no default set.

    The show-access-token capability preflight runs first, before
    ``sf config get``. A CLI too old to fetch a token then fails with the
    upgrade/reinstall message, not a misleading "no default org" message.
    The preflight is cached per process, so the later ``resolve_org`` call
    does not probe again.
    """
    _assert_show_access_token_capability()
    argv = ["sf", "config", "get", "target-org", "--json"]
    try:
        proc = subprocess.run(
            argv, capture_output=True, text=True, timeout=30, check=True,
        )
    except FileNotFoundError:
        raise SystemExit(
            "sf CLI not found on PATH — install Salesforce CLI first"
        ) from None
    except subprocess.CalledProcessError as exc:
        detail = (
            _redact_text((exc.stderr or "").strip() or (exc.stdout or "").strip())
            or "unknown error"
        )
        raise SystemExit(
            f"{NO_DEFAULT_ORG_MSG}\n`sf config get target-org` failed: {detail}"
        ) from None
    except subprocess.TimeoutExpired:
        raise SystemExit(
            f"{NO_DEFAULT_ORG_MSG}\n`sf config get target-org` timed out after 30s"
        ) from None
    try:
        payload = json.loads(proc.stdout or "")
    except json.JSONDecodeError:
        raise SystemExit(
            f"{NO_DEFAULT_ORG_MSG}\n`sf config get target-org --json` returned "
            f"non-JSON output: {_redact_text(proc.stdout.strip())[:200]}"
        ) from None
    result = payload.get("result") if isinstance(payload, dict) else None
    first = result[0] if isinstance(result, list) and result else {}
    value = first.get("value") if isinstance(first, dict) else None
    if not isinstance(value, str) or not value.strip():
        raise SystemExit(NO_DEFAULT_ORG_MSG)
    return value.strip()


def resolve_org(alias: str) -> tuple[str, str]:
    """Resolve instanceUrl + accessToken for the sf org alias.

    Token retrieval is fail-fast (forcedotcom/cli#3560): the access token
    comes ONLY from `sf org auth show-access-token --json --no-prompt`.
    `sf org display --json --verbose` is used for non-secret metadata
    (instanceUrl); any `accessToken` it carries is ignored.

    Raises SystemExit on CLI failure — this is the one thing every
    downstream operation depends on, so a clean early exit is friendlier
    than a stack trace.
    """
    # Step 1: capability preflight first, so a missing sf binary or missing
    # command yields the actionable preflight error (cached once it passes).
    _assert_show_access_token_capability()

    # Step 2: org_display for instanceUrl (non-secret metadata only).
    display = _run_sf_json(
        ["sf", "org", "display", "--target-org", alias, "--json", "--verbose"],
    )["result"]
    instance_url = display.get("instanceUrl") or ""
    if not instance_url:
        raise SystemExit(
            f"sf org display returned no instanceUrl for alias {alias!r}"
        )

    # Step 3: dedicated command is the only token source.
    try:
        token_payload = _run_sf_json(
            ["sf", "org", "auth", "show-access-token",
             "--target-org", alias, "--json", "--no-prompt"],
        )
    except (SystemExit, json.JSONDecodeError) as exc:
        raise SystemExit(
            f"could not retrieve access token for alias {alias!r} via "
            "sf org auth show-access-token; ensure the org is authenticated "
            f"(sf org login web --alias {alias}).\nDetail: {exc}"
        ) from exc

    token_result = token_payload.get("result") or {}
    access_token = token_result.get("accessToken") or ""

    if not access_token or _REDACTION_MARKER_FRAGMENT in access_token:
        raise SystemExit(
            f"could not retrieve a usable access token for alias {alias!r} "
            "via sf org auth show-access-token. Ensure sf CLI is logged in "
            "for this org and the command returned a real token."
        )

    return instance_url, access_token


def post(sql: str, instance_url: str, token: str, query_name: str = "") -> list[dict]:
    """POST SQL to Data Cloud Query API, return parsed rows.

    `query_name` is a human label used only for error messages — pass
    the template name (e.g. "sessions") so DCQueryError identifies
    which query failed.
    """
    req = urllib.request.Request(
        f"{instance_url}{DC_API_PATH}",
        data=json.dumps({"sql": sql}).encode(),
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            body = json.loads(resp.read())
    except urllib.error.HTTPError as e:
        err_body = e.read().decode(errors="replace")
        raise DCQueryError(
            f"query={query_name or '?'} http={e.code}\n"
            f"--- response ({len(err_body)} bytes) ---\n{err_body}\n"
            f"--- sql (first 400 chars) ---\n{sql[:400]}"
        ) from None
    return parse(body)
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