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/cache_check.py

View on GitHub
#!/usr/bin/env python3
"""Cache hit/miss check for investigating-agentforce-architecture.

Replaces old agent Phase 0.5 (manifest read, schema-version check, TTL age
check, path-existence check, env export on hit, RESULT-block assembly).

Flow:
  1. If FORCE_REFRESH=true → emit CACHE_HIT=false, exit 0.
  2. Read $CACHE_DIR/manifest.json. Any I/O or parse failure → miss.
  3. if schema_version != config.SCHEMA_VERSION → miss,
     emit CACHE_INVALIDATED_REASON=schema-version-mismatch, and
     `shutil.rmtree` the cache dir (gated to paths under CACHE_ROOT).
  4. If data_path file missing → miss (atomic rename failed mid-write).
  5. If age > ttl_days (default 7) → miss (no rmtree — just stale).
  6. Hit path:
     - Copy {agent}_{ver}_metadata_tree.json from cache into DATA_DIR +
       WORK_DIR.
     - Copy `declared_action_tree.json` sidecar into WORK_DIR so emit ctx
       + downstream greps work.
     - Stdout: eval-able lines (CACHE_HIT=true, CACHED_AT_UTC, NODE_COUNT,
       DEPTH, AGENT_GENERATION, BOT_ID, VERSION_AUTO_PICKED, PARTIAL,
       UNRESOLVED_COUNT, OUTPUT_JSON_PATH, OUTPUT_SUMMARY_PATH).

`{tree_base}.summary.md` was dropped from the output contract.
Cache-hit no longer copies or regenerates a summary file; OUTPUT_SUMMARY_PATH
is emitted empty for RESULT-block shape stability.

Usage:
    eval "$(python3 cache_check.py)"

Inputs (env):
    CACHE_DIR        required — $CACHE_ROOT/$ORG_ID_15/$AGENT__$VER
    DATA_DIR         required — $DATA_ROOT/$ORG_ID_15/$AGENT__$VER
    WORK_DIR         required
    AGENT_API_NAME   required
    AGENT_VERSION    required
    FORCE_REFRESH    'true'|'false' (default false)

Outputs:
    stdout: eval-able K=V lines
    files (hit only): DATA_DIR/{tree_base}.json and matching copy in WORK_DIR
    exit 0 always (miss is not an error)
"""
import json
import os
import pathlib
import shlex
import shutil
import sys
import datetime as dt

import config  # for SCHEMA_VERSION + CACHE_ROOT path-guard 


# refuse to operate if CACHE_ROOT itself is a symlink.
# _safe_rmtree_under_cache_root calls resolve() on both target and root; a
# symlinked CACHE_ROOT collapses the is_relative_to check because both sides
# land on the symlink target, so rmtree would happily delete whatever lives
# there — outside the sanctioned cache subtree. The guard was designed to
# prevent rmtree escaping the cache; if the root itself can escape, the
# guard is moot. Fail fast at import time so the failure surfaces at the
# correct layer (configuration, not deletion).
#
# Path.is_symlink() returns False for non-existent paths, which is the
# correct behaviour for pristine installs (CACHE_ROOT hasn't been created
# yet; the script will mkdir it on first write and subsequent imports will
# validate the real directory).
if config.CACHE_ROOT.is_symlink():
    raise RuntimeError(
        f"CACHE_ROOT is a symlink ({config.CACHE_ROOT} -> "
        f"{config.CACHE_ROOT.resolve()}). This is rejected for safety; the "
        "_safe_rmtree_under_cache_root guard cannot protect against a "
        "symlinked-root escape. Resolve the symlink or update "
        "config.CACHE_ROOT to a real directory."
    )


def miss(reason: str | None = None):
    """Emit CACHE_HIT=false and exit 0.

    if `reason` is provided, emit a second K=V line
    `CACHE_INVALIDATED_REASON=<reason>` so downstream emit_result can
    surface the invalidation cause in the RESULT block.
    """
    sys.stdout.write("CACHE_HIT=false\n")
    if reason:
        sys.stdout.write(f"CACHE_INVALIDATED_REASON={shlex.quote(reason)}\n")
    sys.exit(0)


def _safe_rmtree_under_cache_root(target: pathlib.Path) -> bool:
    """`shutil.rmtree(target)` ONLY if `target` resolves under CACHE_ROOT.

    Defence against a miscomputed cache_dir that could point outside the
    sanctioned cache root (symlink shenanigans, env-var tampering, or a
    future refactor that forgets to run through `build_agent_cache_dir`).
    We resolve both sides to absolute paths and confirm CACHE_ROOT is a
    prefix before handing to rmtree.

    Returns True on successful deletion, False if the path was refused or
    the rmtree itself failed. Never raises — callers on the miss() path
    can't act on a failure anyway.
    """
    try:
        target_abs = target.resolve(strict=False)
        root_abs = config.CACHE_ROOT.resolve(strict=False)
    except (OSError, RuntimeError):
        return False
    # Path.is_relative_to exists on 3.9+. Explicit check is clearer than
    # a try/except on relative_to().
    try:
        if not target_abs.is_relative_to(root_abs):
            return False
    except AttributeError:  # pragma: no cover — safety for <3.9
        try:
            target_abs.relative_to(root_abs)
        except ValueError:
            return False
    if not target_abs.exists():
        return True  # nothing to do, treat as successful no-op
    try:
        shutil.rmtree(target_abs)
    except OSError:
        return False
    return True


def main() -> int:
    try:
        cache_dir = pathlib.Path(os.environ["CACHE_DIR"])
        data_dir = pathlib.Path(os.environ["DATA_DIR"])
        work_dir = pathlib.Path(os.environ["WORK_DIR"])
        agent_api_name = os.environ["AGENT_API_NAME"]
        agent_version = os.environ["AGENT_VERSION"]
    except KeyError as e:
        sys.stderr.write(f"cache_check.py: missing env {e}\n")
        miss()

    if (os.environ.get("FORCE_REFRESH", "").strip().lower() == "true"):
        miss()

    manifest_path = cache_dir / "manifest.json"
    if not manifest_path.is_file():
        miss()

    try:
        manifest = json.loads(manifest_path.read_text())
    except (OSError, json.JSONDecodeError):
        miss()

    # Schema version gate.
    # strict match against config.SCHEMA_VERSION. Any mismatch (too
    # old OR unexpected future/unknown value) invalidates the cache, and
    # we delete the cache directory so the next run starts clean — a
    # stale tree under a legacy schema is worse than no cache, because
    # downstream code may parse shapes it no longer understands. The
    # legacy `< 2.4` check is subsumed (anything that doesn't equal the
    # current SCHEMA_VERSION triggers this branch).
    schema = str(manifest.get("schema_version") or "0")
    if schema != config.SCHEMA_VERSION:
        _safe_rmtree_under_cache_root(cache_dir)
        miss("schema-version-mismatch")

    # data_path existence
    data_path_s = manifest.get("data_path") or ""
    data_path = pathlib.Path(data_path_s) if data_path_s else None
    if not data_path or not data_path.is_file():
        miss()

    # TTL age check
    try:
        built = dt.datetime.fromisoformat(
            (manifest.get("built_at_utc") or "").replace("Z", "+00:00")
        )
    except ValueError:
        miss()
    age_days = (dt.datetime.now(dt.timezone.utc) - built).days
    ttl = int(manifest.get("ttl_days") or 7)
    if age_days > ttl:
        miss()

    # --- Hit path ---
    tree_base = f"{agent_api_name}_{agent_version}_metadata_tree"
    data_dir.mkdir(parents=True, exist_ok=True)
    work_dir.mkdir(parents=True, exist_ok=True)

    dst_json = data_dir / f"{tree_base}.json"

    # The manifest's data_path points at the authoritative tree copy. Re-copy
    # to DATA_DIR + WORK_DIR so the filesystem layout is stable for callers.
    try:
        shutil.copy(data_path, dst_json)
    except OSError:
        miss()

    # Stage a declared_action_tree.json sidecar in WORK_DIR for any downstream
    # script that expects the generic name.
    try:
        shutil.copy(dst_json, work_dir / "declared_action_tree.json")
    except OSError:
        pass

    # no summary.md handling — dropped from the output contract.
    agent_meta = manifest.get("agent") or {}
    kind_counts = manifest.get("kind_counts") or {}

    exports = [
        ("CACHE_HIT", "true"),
        ("CACHED_AT_UTC", manifest.get("built_at_utc", "")),
        ("NODE_COUNT", str(manifest.get("node_count", 0))),
        ("DEPTH", str(manifest.get("depth", 0))),
        ("AGENT_GENERATION", agent_meta.get("generation") or "unknown"),
        ("BOT_ID", agent_meta.get("bot_id") or ""),
        ("BOT_MASTER_LABEL", agent_meta.get("master_label") or ""),
        ("VERSION_AUTO_PICKED", "true" if agent_meta.get("_version_auto_picked") else "false"),
        ("PARTIAL", "true" if manifest.get("partial") else "false"),
        ("UNRESOLVED_COUNT", str(manifest.get("unresolved_count", 0))),
        ("OUTPUT_JSON_PATH", str(dst_json)),
        # summary.md dropped from the output contract; field kept
        # empty for RESULT-block shape stability.
        ("OUTPUT_SUMMARY_PATH", ""),
        ("PLANNER_NAME", agent_meta.get("planner_name") or ""),
    ]
    # Pass kind counts too, in case finalize.py runs later without re-parsing
    # (it won't on cache hit, but the values keep the RESULT block complete).
    for k, v in kind_counts.items():
        exports.append((f"KC_{k}", str(v)))

    sys.stdout.write("\n".join(f"{k}={shlex.quote(v)}" for k, v in exports) + "\n")
    return 0


if __name__ == "__main__":
    sys.exit(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