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

View on GitHub
"""cache_check.py schema-version mismatch → delete-on-read + MISS.

Covers:
  * manifest.schema_version == config.SCHEMA_VERSION → HIT
  * manifest.schema_version != config.SCHEMA_VERSION → MISS +
    CACHE_INVALIDATED_REASON=schema-version-mismatch + cache dir deleted
  * missing manifest → MISS (existing behavior preserved)
  * expired TTL + correct schema → MISS + dir NOT deleted
  * _safe_rmtree_under_cache_root refuses paths outside CACHE_ROOT
  * module import raises if CACHE_ROOT is a symlink

The script reads env vars + writes eval-able K=V lines to stdout +
exits 0 on both HIT and MISS. We drive it via subprocess so we exercise
the real stdout stream and exit code.
"""
from __future__ import annotations

import datetime as dt
import importlib
import json
import os
import pathlib
import shutil
import subprocess
import sys
import tempfile
import unittest

from . import _bootstrap  # noqa: F401

import config  # type: ignore
import cache_check  # type: ignore


SCRIPTS_DIR = pathlib.Path(__file__).resolve().parent.parent
CACHE_CHECK = SCRIPTS_DIR / "cache_check.py"


def _parse_kv(stdout: str) -> dict[str, str]:
    """Parse the shlex-quoted K=V lines cache_check emits.

    cache_check writes one `K=V` per line, V shlex-quoted. For our tests
    we don't need full shell parsing — we just strip one surrounding
    single-quote layer if present.
    """
    out: dict[str, str] = {}
    for line in stdout.splitlines():
        if "=" not in line:
            continue
        k, _, v = line.partition("=")
        if v.startswith("'") and v.endswith("'") and len(v) >= 2:
            v = v[1:-1]
        out[k] = v
    return out


class CacheCheckSchemaVersionTests(unittest.TestCase):
    """strict schema-version match, delete-on-mismatch."""

    def setUp(self) -> None:
        # Isolated tempdir mirroring CACHE_ROOT so we can safely rmtree
        # anything under it. We override config.CACHE_ROOT for the
        # duration of each test — the script reads config.CACHE_ROOT at
        # rmtree-validation time, and we drive the script via subprocess
        # with CACHE_ROOT propagated through env only via a wrapper
        # below (subprocess-style overrides).
        self.tmp = tempfile.TemporaryDirectory()
        self.root = pathlib.Path(self.tmp.name).resolve()
        self.cache_root = self.root / "cache"
        self.data_root = self.root / "data"
        self.work_dir = self.root / "work"
        self.cache_root.mkdir()
        self.data_root.mkdir()
        self.work_dir.mkdir()
        # Agent-keyed sub-path under cache_root.
        self.agent = "TestAgent_v1"
        self.version = "v1"
        self.cache_dir = self.cache_root / "00D000000000ABC" / f"{self.agent}__{self.version}"
        self.data_dir = self.data_root / "00D000000000ABC" / f"{self.agent}__{self.version}"
        self.cache_dir.mkdir(parents=True)
        # Data file manifest points at — must exist for the HIT path.
        self.data_file = self.cache_dir / "metadata_tree.json"
        self.data_file.write_text(json.dumps({"root": {"kind": "Bot"}}))
        # summary.md dropped from the output contract — no
        # longer written by cache seeding.

    def tearDown(self) -> None:
        self.tmp.cleanup()

    def _write_manifest(self, schema_version: str, age_days: int = 0) -> None:
        built = dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=age_days)
        manifest = {
            "schema_version": schema_version,
            "data_path": str(self.data_file),
            "built_at_utc": built.isoformat().replace("+00:00", "Z"),
            "ttl_days": 7,
            "node_count": 1,
            "depth": 1,
            "agent": {
                "generation": "Einstein",
                "bot_id": "0Xx000000000000",
                "master_label": "TestAgent",
                "planner_name": "p1",
            },
            "kind_counts": {"Bot": 1},
            "partial": False,
            "unresolved_count": 0,
        }
        (self.cache_dir / "manifest.json").write_text(json.dumps(manifest))

    def _run_with_patched_cache_root(self, extra_env: dict | None = None) -> subprocess.CompletedProcess:
        """Patch config.CACHE_ROOT via a small wrapper — simpler than the
        HOME-redirect dance and keeps the test local to the module under
        test. We write a tiny entry-point that monkeypatches config
        before invoking cache_check.main, then runs it.
        """
        wrapper = self.root / "wrapper.py"
        wrapper.write_text(
            "import sys; sys.path.insert(0, %r); sys.path.insert(0, %r)\n"
            "import config\n"
            "config.CACHE_ROOT = __import__('pathlib').Path(%r)\n"
            "import cache_check\n"
            "sys.exit(cache_check.main())\n"
            % (str(SCRIPTS_DIR), str(SCRIPTS_DIR.parent / 'tools'), str(self.cache_root))
        )
        env = os.environ.copy()
        env.update({
            "CACHE_DIR": str(self.cache_dir),
            "DATA_DIR": str(self.data_dir),
            "WORK_DIR": str(self.work_dir),
            "AGENT_API_NAME": self.agent,
            "AGENT_VERSION": self.version,
        })
        if extra_env:
            env.update(extra_env)
        return subprocess.run(
            [sys.executable, str(wrapper)],
            env=env,
            capture_output=True,
            text=True,
            timeout=10,
        )

    def test_matching_schema_version_hits(self):
        self._write_manifest(config.SCHEMA_VERSION)
        cp = self._run_with_patched_cache_root()
        self.assertEqual(cp.returncode, 0, cp.stderr)
        kv = _parse_kv(cp.stdout)
        self.assertEqual(kv.get("CACHE_HIT"), "true", cp.stdout)
        self.assertNotIn("CACHE_INVALIDATED_REASON", kv)
        # Cache dir survives.
        self.assertTrue(self.cache_dir.exists())

    def test_legacy_schema_version_misses_and_deletes(self):
        """schema_version=2.4 (legacy) != 3.0 (current) → MISS + rmtree."""
        self._write_manifest("2.4")
        self.assertTrue(self.cache_dir.exists())
        cp = self._run_with_patched_cache_root()
        self.assertEqual(cp.returncode, 0, cp.stderr)
        kv = _parse_kv(cp.stdout)
        self.assertEqual(kv.get("CACHE_HIT"), "false")
        self.assertEqual(kv.get("CACHE_INVALIDATED_REASON"), "schema-version-mismatch")
        # Cache dir deleted by the safety-gated rmtree.
        self.assertFalse(self.cache_dir.exists(),
                         "cache_dir must be removed on schema-version mismatch")

    def test_unexpected_future_schema_version_misses_and_deletes(self):
        """Any value != current SCHEMA_VERSION invalidates (not just legacy)."""
        self._write_manifest("99.99")
        cp = self._run_with_patched_cache_root()
        kv = _parse_kv(cp.stdout)
        self.assertEqual(kv.get("CACHE_HIT"), "false")
        self.assertEqual(kv.get("CACHE_INVALIDATED_REASON"), "schema-version-mismatch")
        self.assertFalse(self.cache_dir.exists())

    def test_missing_manifest_misses_no_deletion(self):
        """Existing behavior: no manifest → MISS, NO rmtree, no reason emit."""
        # Don't write any manifest.
        cp = self._run_with_patched_cache_root()
        self.assertEqual(cp.returncode, 0, cp.stderr)
        kv = _parse_kv(cp.stdout)
        self.assertEqual(kv.get("CACHE_HIT"), "false")
        # Missing manifest is a different reason class — no invalidation
        # reason emitted here (cache is simply cold, not corrupt).
        self.assertNotIn("CACHE_INVALIDATED_REASON", kv)
        self.assertTrue(self.cache_dir.exists(),
                        "missing manifest must NOT trigger rmtree")

    def test_expired_ttl_with_matching_schema_misses_no_deletion(self):
        """TTL-expired cache with CURRENT schema → MISS but dir stays intact."""
        self._write_manifest(config.SCHEMA_VERSION, age_days=30)  # 30 > 7
        cp = self._run_with_patched_cache_root()
        kv = _parse_kv(cp.stdout)
        self.assertEqual(kv.get("CACHE_HIT"), "false")
        # No schema-mismatch reason — it's a stale cache, not a corrupt one.
        self.assertNotIn("CACHE_INVALIDATED_REASON", kv)
        self.assertTrue(self.cache_dir.exists(),
                        "expired TTL must NOT rmtree — just mark stale")


class SafeRmtreeUnderCacheRootTests(unittest.TestCase):
    """defensive: `_safe_rmtree_under_cache_root` refuses out-of-root paths."""

    def setUp(self) -> None:
        self.tmp = tempfile.TemporaryDirectory()
        self.root = pathlib.Path(self.tmp.name).resolve()
        self.cache_root = self.root / "cache"
        self.cache_root.mkdir()
        # In-scope victim dir.
        self.in_scope = self.cache_root / "agent_v1"
        self.in_scope.mkdir()
        (self.in_scope / "some.txt").write_text("x")
        # Out-of-scope victim dir (sibling to cache_root).
        self.out_of_scope = self.root / "other"
        self.out_of_scope.mkdir()
        (self.out_of_scope / "important.txt").write_text("do not delete")

        # Monkeypatch config.CACHE_ROOT for the duration of each test.
        self._orig_root = config.CACHE_ROOT
        config.CACHE_ROOT = self.cache_root

    def tearDown(self) -> None:
        config.CACHE_ROOT = self._orig_root
        self.tmp.cleanup()

    def test_rmtree_under_cache_root_succeeds(self):
        ok = cache_check._safe_rmtree_under_cache_root(self.in_scope)
        self.assertTrue(ok)
        self.assertFalse(self.in_scope.exists())

    def test_rmtree_outside_cache_root_refused(self):
        ok = cache_check._safe_rmtree_under_cache_root(self.out_of_scope)
        self.assertFalse(ok, "out-of-root path must be refused")
        # File still present.
        self.assertTrue((self.out_of_scope / "important.txt").exists())

    def test_nonexistent_under_root_is_noop_success(self):
        """A caller asking to delete a path that doesn't exist under the
        root gets a silent success — matches rmtree's semantics for
        already-gone targets and avoids spurious error branches on the
        miss() path."""
        ghost = self.cache_root / "never_existed"
        ok = cache_check._safe_rmtree_under_cache_root(ghost)
        self.assertTrue(ok)


class SymlinkedCacheRootRejectedAtImportTests(unittest.TestCase):
    """module import raises if CACHE_ROOT is a symlink.

    A symlinked CACHE_ROOT would defeat the rmtree safety gate — both
    sides of `target.resolve().is_relative_to(root.resolve())` would
    collapse to the same symlink target, so the gate would approve
    deletion of arbitrary paths the attacker aimed the symlink at.
    The defence is a fail-fast guard at cache_check import time.
    """

    def setUp(self) -> None:
        self.tmp = tempfile.TemporaryDirectory()
        self.root = pathlib.Path(self.tmp.name).resolve()
        self.real_target = self.root / "evil_target"
        self.real_target.mkdir()
        self.symlinked_root = self.root / "symlinked_cache_root"
        self.symlinked_root.symlink_to(self.real_target)
        self._orig_root = config.CACHE_ROOT

    def tearDown(self) -> None:
        # Restore and reload so the rest of the suite sees a clean module.
        config.CACHE_ROOT = self._orig_root
        importlib.reload(cache_check)
        self.tmp.cleanup()

    def test_symlinked_cache_root_raises_on_import(self):
        """Reloading cache_check with a symlinked CACHE_ROOT must raise
        RuntimeError — proof that the guard actually fires and the fix
        is load-bearing."""
        config.CACHE_ROOT = self.symlinked_root
        with self.assertRaises(RuntimeError) as ctx:
            importlib.reload(cache_check)
        msg = str(ctx.exception)
        # Message must name the offending path so operators can fix it
        # without spelunking the source. Don't over-specify wording —
        # future maintainers may clarify the phrasing.
        self.assertIn(str(self.symlinked_root), msg)
        self.assertIn("symlink", msg.lower())

    def test_real_directory_cache_root_passes(self):
        """Sanity: the guard is not over-broad — a real directory (the
        common case) reloads cleanly."""
        real_dir = self.root / "real_cache_root"
        real_dir.mkdir()
        config.CACHE_ROOT = real_dir
        # No raise.
        importlib.reload(cache_check)

    def test_nonexistent_cache_root_passes(self):
        """Pristine install: CACHE_ROOT hasn't been created yet.
        Path.is_symlink() returns False on non-existent paths, so import
        must succeed — the directory will be materialized on first write."""
        ghost = self.root / "does_not_exist_yet"
        self.assertFalse(ghost.exists())
        config.CACHE_ROOT = ghost
        # No raise.
        importlib.reload(cache_check)


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