Skip to content

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

agentforce-architecture-analyze

Verified

Declared architecture snapshot for one Agentforce agent: planner, topics, actions, flows, Apex, prompt templates, and NGA plugins. Renders a human-readable architecture document and Mermaid invocation graph from design-time metadata (not runtime audit rows). TRIGGER when user asks to describe, diagram, inventory, audit, document, or diff (e.g. v3 vs v5) the architecture / action tree / topic structure / tool inventory of a specific agent by agent API name in a specific org. DO NOT TRIGGER for runtime session traces, conversation transcripts, generation timings, or gateway audit chains — this skill reads design-time metadata only (use agentforce-d360-analyze for session traces).

FileKindSize
README.mdmarkdown8.5 KB
SKILL.mdskill md17.5 KB
assets/cli/describe_sobject.yamlconfig317 B
assets/cli/describe_tooling_sobject.yamlconfig347 B
assets/cli/list_metadata_genaiprompttemplate.yamlconfig342 B
assets/cli/org_display.yamlconfig280 B
assets/cli/retrieve_genai_plugin.yamlconfig391 B
assets/cli/show_access_token.yamlconfig700 B
assets/mermaid/action_tree.mmdother986 B
assets/mermaid/data_flow.mmdother893 B
assets/mermaid/dependency_graph.mmdother810 B
assets/mermaid/invocation_sequence.mmdother1004 B
assets/mermaid/planner_state.mmdother813 B
assets/soql/apex_class_bodies_by_ids.soqlother103 B
assets/soql/apex_class_bodies_by_names.soqlother102 B
assets/soql/bot_definition_details.soqlother152 B
assets/soql/bot_version_lookup.soqlother186 B
assets/soql/flow_definition_by_ids.soqlother115 B
assets/soql/flow_definition_ids_by_names.soqlother146 B
assets/soql/flow_definition_view_by_durable_ids.soqlother180 B
assets/soql/flow_metadata_by_id.soqlother73 B
assets/soql/functions_by_plugins.soqlother317 B
assets/soql/planner_attrs_by_parent_ids.soqlother156 B
assets/soql/planner_bundle_functions.soqlother93 B
assets/soql/planner_definition_by_agent_chain.soqlother174 B
assets/soql/plugin_functions_by_plugin_ids.soqlother93 B
assets/soql/plugin_instructions_by_plugin_ids.soqlother168 B
assets/soql/plugins_by_planner.soqlother199 B
references/architecture_sections.mdmarkdown8.3 KB
references/contract.jsonconfig11.7 KB
references/soql_fields.mdmarkdown24.6 KB
scripts/_shared/__init__.pyscript82 B
scripts/_shared/fs_guard.pyexecutablescript12.8 KB
scripts/_shared/paths.pyscript3.9 KB
scripts/_shared/runtime.pyscript2.0 KB
scripts/_shared/sql.pyscript355 B
scripts/cache_check.pyexecutablescript8.9 KB
scripts/config.pyscript5.9 KB
scripts/emit_env.pyexecutablescript5.1 KB
scripts/emit_result.pyexecutablescript10.7 KB
scripts/fetch_soql.pyscript26.1 KB
scripts/finalize.pyexecutablescript11.8 KB
scripts/main.pyscript113.9 KB
scripts/metadata_listing.pyscript9.5 KB
scripts/parallel_retrieve.pyscript3.3 KB
scripts/parse_bundle.pyexecutablescript7.9 KB
scripts/parse_wave.pyexecutablescript36.1 KB
scripts/probe_channels.pyscript11.1 KB
scripts/render_architecture.pyscript40.0 KB
scripts/resolve_bot.pyexecutablescript9.4 KB
scripts/resolve_invocation_target.pyscript4.8 KB
scripts/rest_client.pyscript33.7 KB
scripts/retrieve_planner.pyscript464 B
scripts/sanitize.pyexecutablescript1013 B
scripts/sf_cli.pyscript12.3 KB
scripts/soql_loader.pyscript11.1 KB
scripts/summarize_tree.pyexecutablescript4.6 KB
scripts/tests/__init__.pyscript0 B
scripts/tests/_bootstrap.pyscript843 B
scripts/tests/fixtures/__init__.pyscript0 B
scripts/tests/fixtures/genai_payloads.pyscript12.5 KB
scripts/tests/test_cache_check.pyscript12.6 KB
scripts/tests/test_cache_check_main.pyscript10.4 KB
scripts/tests/test_config.pyscript3.8 KB
scripts/tests/test_end_to_end_fixture.pyscript26.2 KB
scripts/tests/test_finalize.pyscript11.2 KB
scripts/tests/test_flow_children_inflation.pyscript25.6 KB
scripts/tests/test_fs_guard.pyscript4.3 KB
scripts/tests/test_iterative_wave_b.pyscript19.0 KB
scripts/tests/test_main_pipeline.pyscript145.1 KB
scripts/tests/test_parallel_retrieve.pyscript4.8 KB
scripts/tests/test_parse_bundle.pyscript15.6 KB
scripts/tests/test_parse_wave.pyscript26.9 KB
scripts/tests/test_parse_wave_classifiers.pyscript8.6 KB
scripts/tests/test_parse_wave_helpers.pyscript14.3 KB
scripts/tests/test_parse_wave_main.pyscript16.4 KB
scripts/tests/test_per_branch_visited.pyscript9.5 KB
scripts/tests/test_probe_channels.pyscript13.3 KB
scripts/tests/test_probe_cli_recipes.pyscript8.2 KB
scripts/tests/test_render_architecture.pyscript32.7 KB
scripts/tests/test_resolve_bot.pyscript7.5 KB
scripts/tests/test_resolve_creds.pyscript12.0 KB
scripts/tests/test_resolve_invocation_target.pyscript5.2 KB
scripts/tests/test_rest_client.pyscript49.8 KB
scripts/tests/test_runtime_override.pyscript3.9 KB
scripts/tests/test_sf_cli.pyscript17.3 KB
scripts/tests/test_signature_stamping.pyscript18.0 KB
scripts/tests/test_skill_md_pipeline_block.pyscript12.7 KB
scripts/tests/test_soql_loader.pyscript21.3 KB
scripts/tests/test_summarize_tree.pyscript8.9 KB
scripts/tests/test_write_emit_ctx.pyscript19.2 KB
scripts/write_emit_ctx.pyexecutablescript14.1 KB

scripts/tests/test_parse_bundle.py

View on GitHub
"""Tests for ``parse_bundle`` — Bot.bot + GenAiPlannerBundle parsing.

Covers the four public functions:

- ``classify_generation``    pure str → str
- ``extract_planner_name``   reads bots/*.bot from a tmp WORK_DIR
- ``extract_bundle``         reads genAiPlannerBundles/*.genAiPlannerBundle
- ``atomic_write``           tmp-file + os.replace semantics

All filesystem fixtures are constructed inline under ``tmp_path`` — no
external fixture files needed. XML mirrors the real Salesforce metadata
shape (sf: namespace) so the parser exercises its real code path.
"""
from __future__ import annotations

import json
import os
import unittest
from pathlib import Path
from tempfile import TemporaryDirectory

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

import parse_bundle  # type: ignore


SF_NS = "http://soap.sforce.com/2006/04/metadata"


def _bot_xml(version: str, planner_name: str | None = "MyPlanner") -> str:
    """Minimal Bot.bot XML with one botVersions block.

    If ``planner_name`` is None, omit the <conversationDefinitionPlanners>
    block — caller can use this to exercise the empty-planner branch.
    """
    cdp_block = (
        f"""    <conversationDefinitionPlanners>
      <genAiPlannerName>{planner_name}</genAiPlannerName>
    </conversationDefinitionPlanners>"""
        if planner_name is not None
        else ""
    )
    return f"""<?xml version="1.0" encoding="UTF-8"?>
<Bot xmlns="{SF_NS}">
  <botVersions>
    <fullName>{version}</fullName>
{cdp_block}
  </botVersions>
</Bot>
"""


def _bundle_xml(
    *,
    planner_type: str = "Atlas__Reasoning",
    description: str = "demo",
    master_label: str = "Demo",
    topics: list[dict] | None = None,
    planner_actions: list[dict] | None = None,
) -> str:
    """Build a genAiPlannerBundle XML body.

    Each topic dict supports keys ``name``, ``actions`` (list of dicts with
    keys ``name``, ``invocationTarget``, ``invocationTargetType``).
    """
    topics = topics or []
    planner_actions = planner_actions or []

    def _topic_xml(t: dict) -> str:
        actions = "".join(
            f"""    <localActions>
      <developerName>{a['name']}</developerName>
      <invocationTarget>{a.get('invocationTarget', '')}</invocationTarget>
      <invocationTargetType>{a.get('invocationTargetType', '')}</invocationTargetType>
    </localActions>
"""
            for a in t.get("actions", [])
        )
        return f"""  <localTopics>
    <developerName>{t['name']}</developerName>
    <masterLabel>{t.get('masterLabel', '')}</masterLabel>
    <canEscalate>{str(t.get('canEscalate', False)).lower()}</canEscalate>
{actions}  </localTopics>
"""

    def _planner_action_xml(a: dict) -> str:
        return f"""  <plannerActions>
    <developerName>{a['name']}</developerName>
    <invocationTarget>{a.get('invocationTarget', '')}</invocationTarget>
    <invocationTargetType>{a.get('invocationTargetType', '')}</invocationTargetType>
  </plannerActions>
"""

    return f"""<?xml version="1.0" encoding="UTF-8"?>
<GenAiPlannerBundle xmlns="{SF_NS}">
  <plannerType>{planner_type}</plannerType>
  <description>{description}</description>
  <masterLabel>{master_label}</masterLabel>
{''.join(_topic_xml(t) for t in topics)}{''.join(_planner_action_xml(a) for a in planner_actions)}</GenAiPlannerBundle>
"""


# -----------------------------------------------------------------------------
# classify_generation — pure str → str
# -----------------------------------------------------------------------------


class ClassifyGenerationTests(unittest.TestCase):

    def test_aicopilot_prefix_classifies_as_classic(self):
        self.assertEqual(parse_bundle.classify_generation("AiCopilot__Foo"), "classic")

    def test_atlas_prefix_classifies_as_nga(self):
        self.assertEqual(parse_bundle.classify_generation("Atlas__Reasoning"), "nga")

    def test_unknown_prefix_classifies_as_unknown(self):
        self.assertEqual(parse_bundle.classify_generation("SomethingElse"), "unknown")

    def test_empty_string_classifies_as_unknown(self):
        self.assertEqual(parse_bundle.classify_generation(""), "unknown")

    def test_none_classifies_as_unknown(self):
        self.assertEqual(parse_bundle.classify_generation(None), "unknown")  # type: ignore[arg-type]


# -----------------------------------------------------------------------------
# extract_planner_name — reads bots/*.bot under WORK_DIR
# -----------------------------------------------------------------------------


class ExtractPlannerNameTests(unittest.TestCase):

    def _setup_bot(self, tmp: Path, version: str, planner_name: str | None = "MyPlanner") -> Path:
        bots_dir = tmp / "sf_meta" / "wave1_bot" / "unpackaged" / "bots"
        bots_dir.mkdir(parents=True)
        bot_file = bots_dir / "MyAgent.bot"
        bot_file.write_text(_bot_xml(version, planner_name))
        return tmp

    def test_returns_planner_name_when_botversion_matches(self):
        with TemporaryDirectory() as t:
            tmp = self._setup_bot(Path(t), "v1", "MyPlanner")
            self.assertEqual(parse_bundle.extract_planner_name(tmp, "v1"), "MyPlanner")

    def test_returns_empty_when_botversion_does_not_match(self):
        with TemporaryDirectory() as t:
            tmp = self._setup_bot(Path(t), "v1", "MyPlanner")
            self.assertEqual(parse_bundle.extract_planner_name(tmp, "v99"), "")

    def test_returns_empty_when_no_planner_block(self):
        # Bot has the right version but no <conversationDefinitionPlanners>
        with TemporaryDirectory() as t:
            tmp = self._setup_bot(Path(t), "v1", planner_name=None)
            self.assertEqual(parse_bundle.extract_planner_name(tmp, "v1"), "")

    def test_returns_empty_when_bots_dir_missing(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)  # no sf_meta/wave1_bot/...
            self.assertEqual(parse_bundle.extract_planner_name(tmp, "v1"), "")

    def test_returns_empty_when_xml_is_malformed(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            bots_dir = tmp / "sf_meta" / "wave1_bot" / "unpackaged" / "bots"
            bots_dir.mkdir(parents=True)
            (bots_dir / "Broken.bot").write_text("<<<not xml>>>")
            self.assertEqual(parse_bundle.extract_planner_name(tmp, "v1"), "")

    def test_falls_back_to_plannerName_then_fullName(self):
        # Build a bot with sf:plannerName instead of sf:genAiPlannerName.
        with TemporaryDirectory() as t:
            tmp = Path(t)
            bots_dir = tmp / "sf_meta" / "wave1_bot" / "unpackaged" / "bots"
            bots_dir.mkdir(parents=True)
            (bots_dir / "Fallback.bot").write_text(f"""<?xml version="1.0" encoding="UTF-8"?>
<Bot xmlns="{SF_NS}">
  <botVersions>
    <fullName>v1</fullName>
    <conversationDefinitionPlanners>
      <plannerName>FallbackPlanner</plannerName>
    </conversationDefinitionPlanners>
  </botVersions>
</Bot>
""")
            self.assertEqual(
                parse_bundle.extract_planner_name(tmp, "v1"),
                "FallbackPlanner",
            )


# -----------------------------------------------------------------------------
# extract_bundle — reads genAiPlannerBundles/*.genAiPlannerBundle
# -----------------------------------------------------------------------------


class ExtractBundleTests(unittest.TestCase):

    def _setup_bundle(self, tmp: Path, body: str, dirname: str = "MyPlanner") -> None:
        bundle_dir = (
            tmp / "sf_meta" / "wave1_bundle" / "unpackaged" / "genAiPlannerBundles" / dirname
        )
        bundle_dir.mkdir(parents=True)
        (bundle_dir / "MyPlanner.genAiPlannerBundle").write_text(body)

    def test_returns_skeleton_when_planner_dir_missing(self):
        with TemporaryDirectory() as t:
            out = parse_bundle.extract_bundle(Path(t), "MyPlanner")
        self.assertEqual(out["topics"], [])
        self.assertEqual(out["plannerActions"], [])
        self.assertEqual(out["plannerType"], None)
        self.assertEqual(out["plannerName"], "MyPlanner")
        self.assertEqual(out["generation"], "unknown")

    def test_extracts_planner_type_description_and_master_label(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            self._setup_bundle(tmp, _bundle_xml(
                planner_type="Atlas__Reasoning",
                description="My agent",
                master_label="My Agent",
            ))
            out = parse_bundle.extract_bundle(tmp, "MyPlanner")
        self.assertEqual(out["plannerType"], "Atlas__Reasoning")
        self.assertEqual(out["description"], "My agent")
        self.assertEqual(out["masterLabel"], "My Agent")
        self.assertEqual(out["generation"], "nga")

    def test_extracts_topics_with_localActions(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            self._setup_bundle(tmp, _bundle_xml(topics=[{
                "name": "Greetings",
                "masterLabel": "Greetings",
                "actions": [
                    {"name": "Hello", "invocationTarget": "say_hello",
                     "invocationTargetType": "apex"},
                    {"name": "Bye", "invocationTarget": "say_bye",
                     "invocationTargetType": "apex"},
                ],
            }]))
            out = parse_bundle.extract_bundle(tmp, "MyPlanner")
        self.assertEqual(len(out["topics"]), 1)
        self.assertEqual(out["topics"][0]["name"], "Greetings")
        self.assertEqual(len(out["topics"][0]["actions"]), 2)
        self.assertEqual(out["topics"][0]["actions"][0]["name"], "Hello")
        self.assertEqual(out["topics"][0]["actions"][0]["invocationTargetType"], "apex")

    def test_extracts_plannerActions_classic_shape(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            self._setup_bundle(tmp, _bundle_xml(
                planner_type="AiCopilot__Foo",
                planner_actions=[
                    {"name": "Search", "invocationTarget": "search",
                     "invocationTargetType": "flow"},
                ],
            ))
            out = parse_bundle.extract_bundle(tmp, "MyPlanner")
        self.assertEqual(out["generation"], "classic")
        self.assertEqual(len(out["plannerActions"]), 1)
        self.assertEqual(out["plannerActions"][0]["name"], "Search")

    def test_skips_topic_without_developerName(self):
        # Build XML where one topic has no <developerName> — should be dropped.
        with TemporaryDirectory() as t:
            tmp = Path(t)
            broken = f"""<?xml version="1.0" encoding="UTF-8"?>
<GenAiPlannerBundle xmlns="{SF_NS}">
  <plannerType>Atlas__Reasoning</plannerType>
  <localTopics>
    <masterLabel>NoName</masterLabel>
  </localTopics>
  <localTopics>
    <developerName>Good</developerName>
  </localTopics>
</GenAiPlannerBundle>
"""
            self._setup_bundle(tmp, broken)
            out = parse_bundle.extract_bundle(tmp, "MyPlanner")
        self.assertEqual(len(out["topics"]), 1)
        self.assertEqual(out["topics"][0]["name"], "Good")

    def test_returns_skeleton_when_xml_is_malformed(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            self._setup_bundle(tmp, "<<<broken>>>")
            out = parse_bundle.extract_bundle(tmp, "MyPlanner")
        # Malformed → no fields populated, but skeleton shape preserved.
        self.assertEqual(out["topics"], [])
        self.assertEqual(out["plannerActions"], [])
        self.assertEqual(out["plannerType"], None)


# -----------------------------------------------------------------------------
# atomic_write — tmp-file + os.replace
# -----------------------------------------------------------------------------


class AtomicWriteTests(unittest.TestCase):

    def test_writes_content_to_target_path(self):
        with TemporaryDirectory() as t:
            target = Path(t) / "out.txt"
            parse_bundle.atomic_write(target, "hello\n")
            self.assertEqual(target.read_text(), "hello\n")

    def test_overwrites_existing_file(self):
        with TemporaryDirectory() as t:
            target = Path(t) / "out.txt"
            target.write_text("old")
            parse_bundle.atomic_write(target, "new")
            self.assertEqual(target.read_text(), "new")

    def test_no_tmp_file_left_behind_after_success(self):
        with TemporaryDirectory() as t:
            target = Path(t) / "out.txt"
            parse_bundle.atomic_write(target, "x")
            # the .tmp sibling should NOT remain
            tmp_sibling = target.with_suffix(target.suffix + ".tmp")
            self.assertFalse(tmp_sibling.exists())


# -----------------------------------------------------------------------------
# main() — orchestration via env vars
# -----------------------------------------------------------------------------


class MainTests(unittest.TestCase):

    def _setup_full_workdir(self, tmp: Path) -> None:
        # Bot file
        bots_dir = tmp / "sf_meta" / "wave1_bot" / "unpackaged" / "bots"
        bots_dir.mkdir(parents=True)
        (bots_dir / "MyAgent.bot").write_text(_bot_xml("v1", "MyPlanner"))
        # Bundle file
        bundle_dir = (
            tmp / "sf_meta" / "wave1_bundle" / "unpackaged"
            / "genAiPlannerBundles" / "MyPlanner"
        )
        bundle_dir.mkdir(parents=True)
        (bundle_dir / "MyPlanner.genAiPlannerBundle").write_text(_bundle_xml())

    def test_main_writes_bundle_parsed_json_and_returns_zero(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            self._setup_full_workdir(tmp)
            old = dict(os.environ)
            os.environ["WORK_DIR"] = str(tmp)
            os.environ["AGENT_VERSION"] = "v1"
            try:
                rc = parse_bundle.main()
            finally:
                os.environ.clear()
                os.environ.update(old)
            self.assertEqual(rc, 0)
            parsed = json.loads((tmp / "_bundle_parsed.json").read_text())
            self.assertEqual(parsed["plannerName"], "MyPlanner")
            self.assertEqual(parsed["plannerType"], "Atlas__Reasoning")
            self.assertEqual(parsed["generation"], "nga")
            # _agent_generation.txt is newline-terminated for shell sourcing
            self.assertEqual(
                (tmp / "_agent_generation.txt").read_text(), "nga\n"
            )

    def test_main_returns_one_when_env_missing(self):
        # Both WORK_DIR and AGENT_VERSION required; remove WORK_DIR.
        old = dict(os.environ)
        os.environ.pop("WORK_DIR", None)
        os.environ["AGENT_VERSION"] = "v1"
        try:
            rc = parse_bundle.main()
        finally:
            os.environ.clear()
            os.environ.update(old)
        self.assertEqual(rc, 1)

    def test_main_emits_empty_skeleton_when_planner_unresolved(self):
        # Bot file has no <conversationDefinitionPlanners> → planner_name == ""
        with TemporaryDirectory() as t:
            tmp = Path(t)
            bots_dir = tmp / "sf_meta" / "wave1_bot" / "unpackaged" / "bots"
            bots_dir.mkdir(parents=True)
            (bots_dir / "MyAgent.bot").write_text(_bot_xml("v1", planner_name=None))
            old = dict(os.environ)
            os.environ["WORK_DIR"] = str(tmp)
            os.environ["AGENT_VERSION"] = "v1"
            try:
                rc = parse_bundle.main()
            finally:
                os.environ.clear()
                os.environ.update(old)
            self.assertEqual(rc, 0)
            parsed = json.loads((tmp / "_bundle_parsed.json").read_text())
            self.assertIsNone(parsed["plannerName"])
            self.assertEqual(parsed["topics"], [])
            self.assertEqual((tmp / "_agent_generation.txt").read_text(), "unknown\n")


if __name__ == "__main__":
    unittest.main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall