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

View on GitHub
"""In-process tests for ``cache_check.main``.

The existing ``test_cache_check.py`` drives main via subprocess (so its
Python branches don't show up in coverage). This file calls main()
directly, patching ``os.environ`` + ``config.CACHE_ROOT`` so all the
hit/miss decision branches register.
"""
from __future__ import annotations

import datetime as dt
import io
import json
import os
import unittest
from pathlib import Path
from tempfile import TemporaryDirectory
from unittest import mock

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

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


def _build_valid_manifest(*, data_path: str,
                          built_at_utc: str | None = None,
                          schema_version: str = "3.1",
                          node_count: int = 5,
                          depth: int = 2,
                          ttl_days: int = 7,
                          partial: bool = False,
                          unresolved_count: int = 0,
                          generation: str = "nga",
                          bot_id: str = "0Xx000000000Demo",
                          master_label: str = "Demo Agent",
                          version_auto_picked: bool = False,
                          planner_name: str = "DemoPlanner",
                          kind_counts: dict | None = None) -> dict:
    if built_at_utc is None:
        built_at_utc = (
            dt.datetime.now(dt.timezone.utc)
            .isoformat().replace("+00:00", "Z")
        )
    return {
        "schema_version": schema_version,
        "built_at_utc": built_at_utc,
        "node_count": node_count,
        "depth": depth,
        "ttl_days": ttl_days,
        "data_path": data_path,
        "partial": partial,
        "unresolved_count": unresolved_count,
        "agent": {
            "generation": generation,
            "bot_id": bot_id,
            "master_label": master_label,
            "_version_auto_picked": version_auto_picked,
            "planner_name": planner_name,
        },
        "kind_counts": kind_counts or {"TOPIC": 2, "STANDARD_ACTION": 3},
    }


class _CacheHarness:
    """Patch CACHE_ROOT + os.environ + capture stdout."""

    def __init__(self, *, env_overrides: dict | None = None,
                 manifest: dict | None = None,
                 plant_data_file: bool = True):
        self.env_overrides = env_overrides or {}
        self.manifest = manifest
        self.plant_data_file = plant_data_file

    def __enter__(self):
        self._tmp = TemporaryDirectory()
        self.tmpdir = Path(self._tmp.name)
        # Build a 4-deep CACHE_ROOT so cache_dir lives strictly inside it
        # (the rmtree guard refuses paths NOT under CACHE_ROOT).
        self.cache_root = self.tmpdir / "cache" / "investigating-agentforce-architecture"
        self.cache_root.mkdir(parents=True)
        self.cache_dir = self.cache_root / "ALPHA0000000000" / "MyAgent__v1"
        self.cache_dir.mkdir(parents=True)
        self.data_dir = self.tmpdir / "data" / "ALPHA0000000000" / "MyAgent__v1"
        self.work_dir = self.tmpdir / "work"
        self.work_dir.mkdir(parents=True)

        # Plant the authoritative tree file UNDER cache_dir (where
        # finalize.py originally wrote it). cache_check copies it INTO
        # data_dir on hit, so source and dest must be different files.
        self.tree_path = self.cache_dir / "MyAgent_v1_metadata_tree.json"
        if self.plant_data_file:
            self.tree_path.write_text(json.dumps({
                "agent": {"api_name": "MyAgent", "version": "v1"},
                "session": {"_schema_version": 1},
            }))

        # Plant the manifest under cache_dir
        if self.manifest is not None:
            (self.cache_dir / "manifest.json").write_text(
                json.dumps(self.manifest)
            )
        elif self.manifest is None and self.plant_data_file:
            # Default valid manifest pointing at the planted tree
            (self.cache_dir / "manifest.json").write_text(json.dumps(
                _build_valid_manifest(data_path=str(self.tree_path))
            ))

        self._env = {
            "CACHE_DIR": str(self.cache_dir),
            "DATA_DIR": str(self.data_dir),
            "WORK_DIR": str(self.work_dir),
            "AGENT_API_NAME": "MyAgent",
            "AGENT_VERSION": "v1",
        }
        self._env.update(self.env_overrides)

        self._saved_env = dict(os.environ)
        os.environ.update(self._env)

        self._patches = [
            mock.patch.object(config, "CACHE_ROOT", self.cache_root),
        ]
        for p in self._patches:
            p.start()
        return self

    def __exit__(self, *exc):
        for p in self._patches:
            p.stop()
        # Restore env
        for k in self._env:
            os.environ.pop(k, None)
        os.environ.update(self._saved_env)
        self._tmp.cleanup()


def _run_main_capture() -> tuple[int, str]:
    """Call main() with stdout captured. Translates SystemExit into rc."""
    buf = io.StringIO()
    rc: int
    try:
        with mock.patch("sys.stdout", buf):
            rc = cache_check.main()
    except SystemExit as e:
        rc = e.code if isinstance(e.code, int) else 0
    return rc, buf.getvalue()


# -----------------------------------------------------------------------------
# Hit path
# -----------------------------------------------------------------------------


class CacheHitTests(unittest.TestCase):

    def test_hit_emits_cache_hit_true_with_full_export_block(self):
        with _CacheHarness():
            rc, out = _run_main_capture()
        self.assertEqual(rc, 0)
        self.assertIn("CACHE_HIT=true", out)
        # Full hit block has these signature fields
        self.assertIn("CACHED_AT_UTC=", out)
        self.assertIn("NODE_COUNT=", out)
        self.assertIn("DEPTH=", out)
        self.assertIn("AGENT_GENERATION=", out)
        self.assertIn("BOT_ID=", out)
        self.assertIn("PLANNER_NAME=", out)

    def test_hit_copies_tree_into_data_dir(self):
        with _CacheHarness() as h:
            rc, _ = _run_main_capture()
            self.assertEqual(rc, 0)
            dst = h.data_dir / "MyAgent_v1_metadata_tree.json"
            # File search across resolved tree to dodge /private/var ↔ /var.
            written = list(h.tmpdir.rglob("MyAgent_v1_metadata_tree.json"))
        self.assertGreaterEqual(len(written), 1)

    def test_hit_stages_declared_action_tree_in_work_dir(self):
        with _CacheHarness() as h:
            _run_main_capture()
            staged = list(h.tmpdir.rglob("declared_action_tree.json"))
        self.assertGreaterEqual(len(staged), 1)

    def test_hit_emits_kind_counts_with_kc_prefix(self):
        with _CacheHarness():
            _, out = _run_main_capture()
        self.assertIn("KC_TOPIC=", out)
        self.assertIn("KC_STANDARD_ACTION=", out)


# -----------------------------------------------------------------------------
# Miss paths (each one exits 0 with CACHE_HIT=false)
# -----------------------------------------------------------------------------


class CacheMissTests(unittest.TestCase):

    def test_miss_when_force_refresh_true(self):
        with _CacheHarness(env_overrides={"FORCE_REFRESH": "true"}):
            rc, out = _run_main_capture()
        self.assertEqual(rc, 0)
        self.assertIn("CACHE_HIT=false", out)

    def test_miss_when_manifest_missing(self):
        # Build harness without auto-planted manifest
        with _CacheHarness(manifest={}, plant_data_file=False) as h:
            (h.cache_dir / "manifest.json").unlink()
            rc, out = _run_main_capture()
        self.assertEqual(rc, 0)
        self.assertIn("CACHE_HIT=false", out)

    def test_miss_when_manifest_malformed(self):
        with _CacheHarness(manifest={}) as h:
            (h.cache_dir / "manifest.json").write_text("<<<not json>>>")
            rc, out = _run_main_capture()
        self.assertEqual(rc, 0)
        self.assertIn("CACHE_HIT=false", out)

    def test_miss_with_invalidated_reason_on_schema_mismatch(self):
        # Schema version != config.SCHEMA_VERSION → rmtree + miss
        with _CacheHarness(manifest=_build_valid_manifest(
            data_path="/tmp/x", schema_version="2.0",
        )) as h:
            rc, out = _run_main_capture()
        self.assertEqual(rc, 0)
        self.assertIn("CACHE_HIT=false", out)
        self.assertIn("CACHE_INVALIDATED_REASON=schema-version-mismatch", out)
        # Cache dir got rmtree'd
        self.assertFalse(h.cache_dir.exists())

    def test_miss_when_data_path_missing(self):
        with _CacheHarness(manifest=_build_valid_manifest(
            data_path="/nope/not-a-real-path.json",
        )):
            rc, out = _run_main_capture()
        self.assertEqual(rc, 0)
        self.assertIn("CACHE_HIT=false", out)

    def test_miss_when_built_at_unparseable(self):
        with _CacheHarness() as h:
            (h.cache_dir / "manifest.json").write_text(json.dumps(
                _build_valid_manifest(
                    data_path=str(h.tree_path),
                    built_at_utc="not-a-timestamp",
                ),
            ))
            rc, out = _run_main_capture()
        self.assertEqual(rc, 0)
        self.assertIn("CACHE_HIT=false", out)

    def test_miss_when_ttl_expired(self):
        # built_at_utc is far in the past + ttl_days=1 → age > ttl → miss
        ancient = (dt.datetime.now(dt.timezone.utc)
                   - dt.timedelta(days=30)).isoformat().replace("+00:00", "Z")
        with _CacheHarness(manifest=None) as h:
            (h.cache_dir / "manifest.json").write_text(json.dumps(
                _build_valid_manifest(
                    data_path=str(h.tree_path),
                    built_at_utc=ancient,
                    ttl_days=1,
                ),
            ))
            rc, out = _run_main_capture()
        self.assertEqual(rc, 0)
        self.assertIn("CACHE_HIT=false", out)

    def test_miss_when_required_env_missing(self):
        with _CacheHarness() as h:
            os.environ.pop("CACHE_DIR", None)
            buf = io.StringIO()
            rc: int
            try:
                with mock.patch("sys.stdout", buf):
                    with mock.patch("sys.stderr", io.StringIO()):
                        rc = cache_check.main()
            except SystemExit as e:
                rc = e.code if isinstance(e.code, int) else 0
        self.assertEqual(rc, 0)
        self.assertIn("CACHE_HIT=false", buf.getvalue())


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