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

View on GitHub
"""Tests for `main._iterate_wave_b` — iterative subflow + apex discovery.

The initial `_run_wave_b` only enumerates top-level flow refs from
`bundle_parsed`. When those flow bodies reference subflows (shared
utility flows like `handleFlowFault`) or new Apex classes, their bodies
were never fetched. `_iterate_wave_b` drives Wave B to a fixed point so
every reachable flow/apex body lands in the tree.

Assertions focus on observable behavior:
  * Convergence shape — no extra fetches when there are no new refs.
  * Correctness — a utility flow referenced from the top-level round is
    fetched in the next round and its metadata lands in the merged dict.
  * Safety — iteration cap surfaces remaining unfetched names via
    `unresolved`; fetch failures are tolerated without crashing.
  * Cross-kind discovery — a subflow's actionCall referencing a new
    Apex class adds that class to `apex_rows`.
  * Deduplication — the same subflow referenced twice is fetched once.
"""
from __future__ import annotations

import unittest
from unittest import mock

from . import _bootstrap  # noqa: F401

import main  # type: ignore


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


def _creds_provider():
    return ("https://example.my.salesforce.com", "fake_token")


def _refresh_fn():
    return _creds_provider()


def _flow_def_row(dev_name: str, version_id: str) -> dict:
    """Shape matches what `fetch_flow_definition_ids_by_names` returns —
    the fields `_build_flow_children` + the pipeline downstream expect."""
    return {
        "Id": f"300{dev_name}",
        "DeveloperName": dev_name,
        "ActiveVersionId": version_id,
    }


def _flow_metadata_record(
    version_id: str,
    full_name: str,
    *,
    subflows: list[tuple[str, str]] | None = None,
    action_calls: list[dict] | None = None,
) -> dict:
    """Shape a synthetic Flow.Metadata record the way `fetch_flow_metadata`
    returns it — a dict with Id/FullName/Metadata. Subflow tuples are
    `(element_name, flow_name)`; action_calls are raw dicts."""
    md: dict = {}
    if subflows is not None:
        md["subflows"] = [
            {"name": elem, "flowName": target} for elem, target in subflows
        ]
    if action_calls is not None:
        md["actionCalls"] = action_calls
    return {"Id": version_id, "FullName": full_name, "Metadata": md}


def _apex_row(name: str) -> dict:
    """Shape matches `fetch_apex_bodies_by_names` output — `_iterate_wave_b`
    tracks already-fetched by `Name`."""
    return {"Id": f"01p_{name}", "Name": name, "Body": "public class ..."}


# ---------------------------------------------------------------------------
# Tests
# ---------------------------------------------------------------------------


class IterativeWaveBTests(unittest.TestCase):
    def test_single_round_when_no_subflows(self):
        """Round 1 flow body references no subflows and no new apex →
        `_extract_refs_from_flow_metadata` returns empty sets →
        `_fetch_wave_b_by_names` is never invoked → initial wave_b passes
        through unchanged."""
        initial = {
            "apex_rows": [],
            "flow_def_rows": [_flow_def_row("TopFlow", "301TOP")],
            "flow_metadata": {
                "301TOP": _flow_metadata_record(
                    "301TOP", "TopFlow-1", subflows=[], action_calls=[],
                ),
            },
            "unresolved": [],
        }

        with mock.patch.object(main, "_fetch_wave_b_by_names") as mocked:
            out = main._iterate_wave_b(
                initial, _creds_provider, _refresh_fn,
                api_version="v60.0", org_alias="test-org",
                parallelism=2, max_iterations=5,
            )

        mocked.assert_not_called()
        self.assertEqual(
            {r["DeveloperName"] for r in out["flow_def_rows"]},
            {"TopFlow"},
        )
        self.assertEqual(out["unresolved"], [])

    def test_two_rounds_for_shared_utility_flow(self):
        """Round 1: a top-level flow body references subflow `handleFlowFault`.
        Round 2: fetches `handleFlowFault`'s metadata. Round 3: no new refs.
        Converges. Final flow_metadata contains BOTH flows.

        This is the real-org `MyAgent__v5` shape — `handleFlowFault`
        is shared across every flow and should be fetched in one extra
        round.
        """
        initial = {
            "apex_rows": [],
            "flow_def_rows": [_flow_def_row("AGNT_Top_Flow", "301TOP")],
            "flow_metadata": {
                "301TOP": _flow_metadata_record(
                    "301TOP", "AGNT_Top_Flow-1",
                    subflows=[("Handle_Flow_Fault", "handleFlowFault")],
                ),
            },
            "unresolved": [],
        }

        # Mock `_fetch_wave_b_by_names` for two rounds:
        # Round 1: flow_names=[handleFlowFault] → returns metadata whose
        # actionCalls reference a NEW apex (XCSF_FlowFaultMessage).
        # Round 2: apex_names=[XCSF_FlowFaultMessage] → apex row returned.
        # Round 3: no new refs → converge.
        calls: list[dict] = []

        def fake_fetch(**kwargs):
            calls.append({
                "flow_names": list(kwargs["flow_names"]),
                "apex_names": list(kwargs["apex_names"]),
            })
            if kwargs["flow_names"] == ["handleFlowFault"]:
                return {
                    "apex_rows": [],
                    "flow_def_rows": [
                        _flow_def_row("handleFlowFault", "301UTIL"),
                    ],
                    "flow_metadata": {
                        "301UTIL": _flow_metadata_record(
                            "301UTIL", "handleFlowFault-1",
                            subflows=[],
                            action_calls=[{
                                "name": "Parse_and_log_fault",
                                "actionType": "apex",
                                "actionName": "XCSF_FlowFaultMessage",
                            }],
                        ),
                    },
                    "unresolved": [],
                }
            if kwargs["apex_names"] == ["XCSF_FlowFaultMessage"]:
                return {
                    "apex_rows": [_apex_row("XCSF_FlowFaultMessage")],
                    "flow_def_rows": [],
                    "flow_metadata": {},
                    "unresolved": [],
                }
            raise AssertionError(f"unexpected fetch call: {kwargs}")

        with mock.patch.object(
            main, "_fetch_wave_b_by_names", side_effect=fake_fetch,
        ) as mocked:
            out = main._iterate_wave_b(
                initial, _creds_provider, _refresh_fn,
                api_version="v60.0", org_alias="test-org",
                parallelism=2, max_iterations=5,
            )

        # Exactly two rounds: round 1 picks up handleFlowFault, round 2
        # picks up the apex discovered in round 1's subflow body, round 3
        # converges without invoking the fetcher.
        self.assertEqual(mocked.call_count, 2)
        dev_names = {r["DeveloperName"] for r in out["flow_def_rows"]}
        self.assertEqual(dev_names, {"AGNT_Top_Flow", "handleFlowFault"})
        self.assertIn("301UTIL", out["flow_metadata"])
        apex_names_out = {r["Name"] for r in out["apex_rows"]}
        self.assertIn("XCSF_FlowFaultMessage", apex_names_out)
        # Call-order sanity: flow round precedes apex round.
        self.assertEqual(calls[0]["flow_names"], ["handleFlowFault"])
        self.assertEqual(calls[1]["apex_names"], ["XCSF_FlowFaultMessage"])

    def test_actioncall_discovers_new_apex(self):
        """A subflow body carries an actionCall referencing a new Apex
        class. Round 2 fetches that Apex. `wave_b["apex_rows"]` grows."""
        initial = {
            "apex_rows": [],
            "flow_def_rows": [_flow_def_row("TopFlow", "301TOP")],
            "flow_metadata": {
                "301TOP": _flow_metadata_record(
                    "301TOP", "TopFlow-1",
                    subflows=[],
                    action_calls=[{
                        "name": "Invoke_Helper",
                        "actionType": "apex",
                        "actionName": "NewApexHelper",
                    }],
                ),
            },
            "unresolved": [],
        }

        def fake_fetch(**kwargs):
            # Must be the apex-only round — no new flow names.
            self.assertEqual(kwargs["flow_names"], [])
            self.assertEqual(kwargs["apex_names"], ["NewApexHelper"])
            return {
                "apex_rows": [_apex_row("NewApexHelper")],
                "flow_def_rows": [],
                "flow_metadata": {},
                "unresolved": [],
            }

        with mock.patch.object(
            main, "_fetch_wave_b_by_names", side_effect=fake_fetch,
        ) as mocked:
            out = main._iterate_wave_b(
                initial, _creds_provider, _refresh_fn,
                api_version="v60.0", org_alias="test-org",
                parallelism=2, max_iterations=5,
            )

        self.assertEqual(mocked.call_count, 1)
        apex_names_seen = {r["Name"] for r in out["apex_rows"]}
        self.assertEqual(apex_names_seen, {"NewApexHelper"})

    def test_dedup_across_rounds(self):
        """The same subflow referenced from two parent flows is fetched
        exactly once. `_iterate_wave_b` diffs against already-fetched
        names — duplicates are filtered before dispatch."""
        initial = {
            "apex_rows": [],
            "flow_def_rows": [
                _flow_def_row("ParentA", "301A"),
                _flow_def_row("ParentB", "301B"),
            ],
            "flow_metadata": {
                "301A": _flow_metadata_record(
                    "301A", "ParentA-1",
                    subflows=[("Handle_A", "SharedUtility")],
                ),
                "301B": _flow_metadata_record(
                    "301B", "ParentB-1",
                    subflows=[("Handle_B", "SharedUtility")],
                ),
            },
            "unresolved": [],
        }

        call_log: list[list[str]] = []

        def fake_fetch(**kwargs):
            call_log.append(list(kwargs["flow_names"]))
            return {
                "apex_rows": [],
                "flow_def_rows": [_flow_def_row("SharedUtility", "301UTIL")],
                "flow_metadata": {
                    "301UTIL": _flow_metadata_record(
                        "301UTIL", "SharedUtility-1", subflows=[],
                    ),
                },
                "unresolved": [],
            }

        with mock.patch.object(
            main, "_fetch_wave_b_by_names", side_effect=fake_fetch,
        ) as mocked:
            main._iterate_wave_b(
                initial, _creds_provider, _refresh_fn,
                api_version="v60.0", org_alias="test-org",
                parallelism=2, max_iterations=5,
            )

        # Exactly ONE round of fetching — round 1 queries [SharedUtility]
        # (deduped across the two parents); round 2 finds no new refs.
        self.assertEqual(mocked.call_count, 1)
        self.assertEqual(call_log[0], ["SharedUtility"])

    def test_iteration_cap_surfaces_pending(self):
        """Pathological graph where every round introduces a new subflow
        reference (chain: F1 → F2 → F3 → ...). After `max_iterations`
        rounds, remaining unfetched names are surfaced in `unresolved`
        so the pipeline can degrade to PARTIAL_OK with a clear cause.

        Use `max_iterations=3` to keep the test fast; the shape is
        identical to the production cap of 5.
        """
        initial = {
            "apex_rows": [],
            "flow_def_rows": [_flow_def_row("F0", "301_V0")],
            "flow_metadata": {
                "301_V0": _flow_metadata_record(
                    "301_V0", "F0-1", subflows=[("Chain", "F1")],
                ),
            },
            "unresolved": [],
        }

        round_counter = {"i": 1}

        def fake_fetch(**kwargs):
            """Each round returns a flow whose body references the next
            flow in the chain — unbounded growth."""
            requested = kwargs["flow_names"][0]
            next_flow = f"F{round_counter['i'] + 1}"
            round_counter["i"] += 1
            return {
                "apex_rows": [],
                "flow_def_rows": [_flow_def_row(requested, f"301_V{requested}")],
                "flow_metadata": {
                    f"301_V{requested}": _flow_metadata_record(
                        f"301_V{requested}", f"{requested}-1",
                        subflows=[("Chain", next_flow)],
                    ),
                },
                "unresolved": [],
            }

        with mock.patch.object(
            main, "_fetch_wave_b_by_names", side_effect=fake_fetch,
        ) as mocked:
            out = main._iterate_wave_b(
                initial, _creds_provider, _refresh_fn,
                api_version="v60.0", org_alias="test-org",
                parallelism=2, max_iterations=3,
            )

        # We exhausted exactly max_iterations rounds.
        self.assertEqual(mocked.call_count, 3)
        # The unfetched chain-tail lands in `unresolved` with the cap
        # reason so the pipeline can reflect it in the RESULT block.
        iter_cap_entries = [
            u for u in out["unresolved"]
            if "wave-b-iteration-cap" in (u.get("reason") or "")
        ]
        self.assertTrue(iter_cap_entries)
        # The next-round flow reference (F4, unfetched) must be among them.
        pending_names = {u.get("api_name") for u in iter_cap_entries}
        self.assertIn("F4", pending_names)

    def test_fetch_failure_tolerated(self):
        """If the round-N fetch raises (managed-package flow not readable,
        permission denied, etc.), the iteration doesn't crash. The
        affected name stays absent from `flow_def_rows` and surfaces via
        the pending-fetches path downstream; other rounds continue.

        Concretely: we simulate the failure by having the mocked
        `_fetch_wave_b_by_names` append an `unresolved` entry instead of
        returning metadata for the troubled name, which is exactly the
        contract `_fetch_wave_b_by_names` follows internally (it
        catches RestClientError / SoqlParamError and logs to
        `unresolved` without raising).
        """
        initial = {
            "apex_rows": [],
            "flow_def_rows": [_flow_def_row("TopFlow", "301TOP")],
            "flow_metadata": {
                "301TOP": _flow_metadata_record(
                    "301TOP", "TopFlow-1",
                    subflows=[
                        ("Good_Sub", "GoodSubflow"),
                        ("Bad_Sub", "UnreachableFlow"),
                    ],
                ),
            },
            "unresolved": [],
        }

        def fake_fetch(**kwargs):
            # Only the reachable one resolves. The unreachable one is
            # reported via the `unresolved` channel by the inner fetcher.
            return {
                "apex_rows": [],
                "flow_def_rows": [_flow_def_row("GoodSubflow", "301GOOD")],
                "flow_metadata": {
                    "301GOOD": _flow_metadata_record(
                        "301GOOD", "GoodSubflow-1", subflows=[],
                    ),
                },
                "unresolved": [{
                    "kind": "FLOW",
                    "reason": "flow-def-by-name-failed:managed-package-403",
                }],
            }

        with mock.patch.object(
            main, "_fetch_wave_b_by_names", side_effect=fake_fetch,
        ):
            out = main._iterate_wave_b(
                initial, _creds_provider, _refresh_fn,
                api_version="v60.0", org_alias="test-org",
                parallelism=2, max_iterations=5,
            )

        dev_names = {r["DeveloperName"] for r in out["flow_def_rows"]}
        # GoodSubflow made it in; UnreachableFlow did not.
        self.assertIn("GoodSubflow", dev_names)
        self.assertNotIn("UnreachableFlow", dev_names)
        # The inner-fetch's unresolved entry propagates.
        reasons = [u.get("reason") or "" for u in out["unresolved"]]
        self.assertTrue(
            any("managed-package-403" in r for r in reasons),
            f"expected propagated failure reason; got {reasons}",
        )
        # UnreachableFlow is still referenced but not fetched — after
        # iteration converges on subsequent rounds (no new discoveries
        # because GoodSubflow is leaf), it lands as iteration-cap
        # pending. In this test max_iterations=5 and the chain stops at
        # round 1; UnreachableFlow is still missing from fetched names,
        # so the convergence scan at the end flags it? Actually no —
        # convergence only surfaces via the cap. Let's verify that the
        # pipeline's parse_wave path would still mark it as pending via
        # visited-vs-referenced — but that's out of scope for this unit
        # test. The contract here is: iteration doesn't crash, good
        # flows are merged, bad-flow signal propagates.


class ExtractRefsFromFlowMetadataTests(unittest.TestCase):
    """Direct coverage for `_extract_refs_from_flow_metadata` — the
    load-bearing extractor that drives iteration. Its permissiveness
    (tolerating missing/None/malformed records) is a correctness
    property: if it raised on edge cases, iteration would crash on any
    flow with a weird metadata shape."""

    def test_extracts_subflow_and_apex_names(self):
        flow_metadata = {
            "301A": _flow_metadata_record(
                "301A", "A-1",
                subflows=[("E1", "SubA"), ("E2", "SubB")],
                action_calls=[
                    {"name": "ApexCall", "actionType": "apex",
                     "actionName": "MyApex"},
                    # non-apex actionCall shouldn't appear in apex set
                    {"name": "StdCall", "actionType": "emailSimple",
                     "actionName": "SendEmail"},
                ],
            ),
        }
        subs, apex = main._extract_refs_from_flow_metadata(flow_metadata)
        self.assertEqual(subs, {"SubA", "SubB"})
        self.assertEqual(apex, {"MyApex"})

    def test_tolerates_missing_fields(self):
        """None records, non-dict metadata, missing keys, blank names —
        none of these should raise; they all drop silently."""
        flow_metadata = {
            "301A": None,
            "301B": {"Metadata": None},
            "301C": {"Metadata": "not-a-dict"},
            "301D": {"Metadata": {}},
            "301E": {"Metadata": {
                "subflows": [{"name": "noName"}, "not-a-dict",
                             {"name": "E", "flowName": ""}],
                "actionCalls": [{"actionType": "apex", "actionName": ""},
                                "not-a-dict"],
            }},
        }
        subs, apex = main._extract_refs_from_flow_metadata(flow_metadata)
        self.assertEqual(subs, set())
        self.assertEqual(apex, set())


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