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

View on GitHub
"""Tests for ``resolve_bot`` — Bot + version resolution helpers + main flow.

Covers the small pure helpers (``scrub``, ``natural_key``,
``emit_error_block``) plus a happy-path ``main`` end-to-end with
``subprocess.run`` mocked.
"""
from __future__ import annotations

import json
import os
import unittest
from pathlib import Path
from tempfile import TemporaryDirectory
from types import SimpleNamespace
from unittest import mock

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

import resolve_bot  # type: ignore


# -----------------------------------------------------------------------------
# scrub
# -----------------------------------------------------------------------------


class ScrubTests(unittest.TestCase):

    def test_strips_dangerous_shell_chars(self):
        # ` $ " \\ \r \t \0 \n all stripped; safe chars kept verbatim.
        self.assertEqual(
            resolve_bot.scrub("hello`bad$\"" + "\n" + "world"),
            "hellobadworld",
        )

    def test_strips_carriage_return_and_tab(self):
        self.assertEqual(resolve_bot.scrub("a\tb\rc"), "abc")

    def test_returns_empty_string_for_none(self):
        self.assertEqual(resolve_bot.scrub(None), "")

    def test_coerces_non_strings(self):
        self.assertEqual(resolve_bot.scrub(42), "42")

    def test_passes_safe_chars_through(self):
        self.assertEqual(resolve_bot.scrub("Customer_Support_Agent"),
                         "Customer_Support_Agent")


# -----------------------------------------------------------------------------
# natural_key — version sorting
# -----------------------------------------------------------------------------


class NaturalKeyTests(unittest.TestCase):

    def test_sorts_v10_after_v9(self):
        keys = ["v9", "v10", "v2", "v1"]
        keys.sort(key=resolve_bot.natural_key, reverse=True)
        self.assertEqual(keys, ["v10", "v9", "v2", "v1"])

    def test_handles_none_and_empty_string(self):
        # Both should be safe (empty list)
        self.assertEqual(resolve_bot.natural_key(""), [""])
        self.assertEqual(resolve_bot.natural_key(None), [""])


# -----------------------------------------------------------------------------
# emit_error_block — terminal RESULT block + sys.exit
# -----------------------------------------------------------------------------


class EmitErrorBlockTests(unittest.TestCase):

    def test_emits_result_block_and_exits_one(self):
        old_env = dict(os.environ)
        os.environ["AGENT_API_NAME"] = "MyAgent"
        os.environ["ORG_ID_15"] = "00D000000000000"
        os.environ["ORG_ID_18"] = "00D000000000000EAA"
        os.environ.pop("ERROR_TEE", None)
        try:
            with mock.patch.object(resolve_bot.sys, "stdout") as out:
                with self.assertRaises(SystemExit) as ctx:
                    resolve_bot.emit_error_block(
                        "AGENT_NOT_FOUND", "details here", {"AVAILABLE_BOTS": "A,B"},
                    )
            self.assertEqual(ctx.exception.code, 1)
            written = "".join(c.args[0] for c in out.write.call_args_list)
            self.assertIn("STATUS=AGENT_NOT_FOUND", written)
            self.assertIn("ERROR_DETAIL=details here", written)
            self.assertIn("AGENT_API_NAME=MyAgent", written)
            self.assertIn("AVAILABLE_BOTS=A,B", written)
        finally:
            os.environ.clear()
            os.environ.update(old_env)

    def test_writes_error_tee_when_env_set(self):
        with TemporaryDirectory() as t:
            tee_path = Path(t) / "subdir" / "tee.txt"
            old_env = dict(os.environ)
            os.environ["ERROR_TEE"] = str(tee_path)
            os.environ["AGENT_API_NAME"] = "MyAgent"
            os.environ["ORG_ID_15"] = "x"
            os.environ["ORG_ID_18"] = "y"
            try:
                with mock.patch.object(resolve_bot.sys, "stdout"):
                    with self.assertRaises(SystemExit):
                        resolve_bot.emit_error_block("X", "y", {})
                # tee_path got the same content
                self.assertTrue(tee_path.is_file())
                self.assertIn("STATUS=X", tee_path.read_text())
            finally:
                os.environ.clear()
                os.environ.update(old_env)


# -----------------------------------------------------------------------------
# main — happy path with mocked sf data query
# -----------------------------------------------------------------------------


def _versions_payload() -> str:
    return json.dumps({
        "result": {
            "records": [
                {"DeveloperName": "v3", "Status": "Active",
                 "BotDefinitionId": "0Xx000000000ABC",
                 "BotDefinition": {"DeveloperName": "MyAgent",
                                   "MasterLabel": "My Agent"}},
                {"DeveloperName": "v2", "Status": "Inactive",
                 "BotDefinitionId": "0Xx000000000ABC",
                 "BotDefinition": {"DeveloperName": "MyAgent",
                                   "MasterLabel": "My Agent"}},
            ],
        },
    })


def _bot_def_payload() -> str:
    return json.dumps({
        "result": {
            "records": [
                {"DeveloperName": "MyAgent", "MasterLabel": "My Agent",
                 "Description": "demo", "AgentType": "Internal",
                 "Type": "AiCopilot", "AgentTemplate": "T",
                 "BotSource": "AgentforceAgentCopilot"},
            ],
        },
    })


class MainTests(unittest.TestCase):

    def _run_main(self, *, agent_version: str = "") -> tuple[int, str]:
        old_env = dict(os.environ)
        with TemporaryDirectory() as t:
            tmp = Path(t)
            os.environ["ORG_ALIAS"] = "my-org"
            os.environ["AGENT_API_NAME"] = "MyAgent"
            os.environ["WORK_DIR"] = str(tmp)
            os.environ["AGENT_VERSION"] = agent_version

            calls: list = []

            def fake_run(argv, **kw):
                # Two distinct sf data queries: BotVersion then BotDefinition
                calls.append(argv)
                if "BotVersion" in argv[-1]:
                    return SimpleNamespace(returncode=0, stdout=_versions_payload(), stderr="")
                if "BotDefinition" in argv[-1]:
                    return SimpleNamespace(returncode=0, stdout=_bot_def_payload(), stderr="")
                return SimpleNamespace(returncode=0, stdout="{}", stderr="")

            stdout_buf: list[str] = []

            try:
                with mock.patch.object(resolve_bot.subprocess, "run", side_effect=fake_run):
                    with mock.patch.object(resolve_bot.sys, "stdout") as out:
                        out.write = lambda s: stdout_buf.append(s)
                        rc = resolve_bot.main()
            finally:
                os.environ.clear()
                os.environ.update(old_env)
        return rc, "".join(stdout_buf)

    def test_main_succeeds_with_auto_pick(self):
        rc, written = self._run_main()
        self.assertEqual(rc, 0)
        # v3 is Active and lexically highest → auto-picked
        self.assertIn("AGENT_VERSION=v3", written)
        self.assertIn("VERSION_AUTO_PICKED=true", written)
        self.assertIn("BOT_FOUND=true", written)
        self.assertIn("BOT_ID=0Xx000000000ABC", written)

    def test_main_succeeds_with_explicit_version_match(self):
        rc, written = self._run_main(agent_version="v2")
        self.assertEqual(rc, 0)
        self.assertIn("AGENT_VERSION=v2", written)
        self.assertIn("VERSION_AUTO_PICKED=false", written)


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