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

View on GitHub
#!/usr/bin/env python3
"""Idempotent wave parser — builds `$WORK_DIR/declared_action_tree.json`.

Replaces old agent Phase 4 (wave-2 init) + Phase 5/6 re-parse + MAX_WAVE cap.
One script, one code path. The "init vs re-parse" distinction is keyed on the
presence of `declared_action_tree.json` at call time.

Flow:
  1. Load bundle JSON, bot_definition JSON, existing tree (if any).
  2. Walk every $WORK_DIR/sf_meta/*/unpackaged/ dir:
     - flows/*.flow: parse actionCalls → APEX/PROMPT_TEMPLATE/STANDARD_ACTION/
       UNKNOWN children; subflows → FLOW children. Record flow_children[flow_name].
       Mark ("FLOW", flow_name) visited.
     - classes/*.cls-meta.xml: mark ("APEX", name) visited.
     - genAiPromptTemplates/*.genAiPromptTemplate: mark ("PROMPT_TEMPLATE", name).
  3. Build tree if missing (Phase-4 init):
     - agent metadata from bot_definition + bundle
     - root BOT_DEFINITION node with children = topics[] only
       (plannerActions[] retained in the bundle shape for back-compat but
       always empty — a planner never has direct functions, 2026-05-05)
     - each topic → TOPIC node with GEN_AI_FUNCTION children (from inline actions)
     - each GEN_AI_FUNCTION → unwraps_to + leaf child (Flow/Apex/Prompt/Std/Unk)
  4. Inflate every FLOW leaf recursively (depth ≤ 6) with flow_children data.
  5. Recompute `_pending_fetches` (names not yet in visited set).
  6. Walk tree for `node_count`, `depth`, `_kind_counts`.
  7. Atomic write.

With --finalize-cap: after loading tree, move all remaining _pending_fetches
items to _unresolved[] with reason "max-wave-depth exceeded".

Usage:
    python3 parse_wave.py                  # init or re-parse
    python3 parse_wave.py --finalize-cap   # drain _pending_fetches → _unresolved

Inputs (env):
    WORK_DIR, AGENT_API_NAME, AGENT_VERSION, BOT_ID, BOT_MASTER_LABEL,
    VERSION_AUTO_PICKED

Outputs:
    $WORK_DIR/declared_action_tree.json (atomic write)
    stderr: log lines (node counts, pending counts, etc.)
    exit 0 on success, 1 on write failure
"""
import json
import os
import pathlib
import sys
import xml.etree.ElementTree as ET
from collections import Counter


NS = {"sf": "http://soap.sforce.com/2006/04/metadata"}


def _t(el, p):
    if el is None:
        return None
    x = el.find(p, NS)
    return x.text if x is not None else None


def classify_bundle_action(action: dict) -> dict:
    """Bundle-action classifier — duplicated in plan_wave.py per 'no
    intra-skill imports' convention. Matches old agent's Phase 3/4 logic.

    Returns (unwraps_dict, leaf_dict) as in the old agent Phase 4's
    action_node(). leaf_dict is the child appended under the GEN_AI_FUNCTION
    node; unwraps_dict is the compact form stored on the function itself.
    """
    tgt = action.get("invocationTarget")
    ttype = (action.get("invocationTargetType") or "").lower()
    if not tgt:
        return None, None
    if ttype == "flow":
        return ({"kind": "FLOW", "api_name": tgt},
                {"kind": "FLOW", "api_name": tgt, "children": []})
    if ttype == "apex":
        return ({"kind": "APEX", "api_name": tgt},
                {"kind": "APEX", "api_name": tgt})
    if ttype == "generatepromptresponse" or ttype.startswith("prompt") or ttype.startswith("genai"):
        return ({"kind": "PROMPT_TEMPLATE", "api_name": tgt},
                {"kind": "PROMPT_TEMPLATE", "api_name": tgt})
    # Canonical field name is `invocation_type` (schema 3.1). Prior
    # versions wrote `raw_invocation_type` on bundle-sourced nodes and
    # `raw_action_type` on flow-actionCall-sourced nodes — downstream
    # readers (render_architecture._display_name, summarize_tree) fall
    # back to both legacy keys for one release.
    if ttype == "standardinvocableaction":
        return ({"kind": "STANDARD_ACTION", "api_name": tgt, "invocation_type": ttype},
                {"kind": "STANDARD_ACTION", "api_name": tgt, "invocation_type": ttype})
    return ({"kind": "UNKNOWN", "api_name": tgt, "invocation_type": ttype},
            {"kind": "UNKNOWN", "api_name": tgt, "invocation_type": ttype})


def classify_action_call(at: str, an: str, element_name: str) -> dict:
    """Flow actionCall classifier (old Phase 4 logic).

    Canonical field name is `invocation_type` (schema 3.1). Legacy readers
    still fall back to `raw_action_type` for one release.
    """
    at = at or ""
    if at == "apex" and an:
        return {"kind": "APEX", "element_name": element_name, "api_name": an}
    if at == "generatePromptResponse" and an:
        return {"kind": "PROMPT_TEMPLATE", "element_name": element_name, "api_name": an}
    if at:
        # Any other non-empty actionType → STANDARD_ACTION; preserve raw.
        return {"kind": "STANDARD_ACTION", "element_name": element_name,
                "api_name": an or at, "invocation_type": at}
    return {"kind": "UNKNOWN", "element_name": element_name,
            "api_name": an or "?", "invocation_type": at or ""}


# ---------------------------------------------------------------------------
# pure BFS step helper. Visited sets are tuple-keyed on
# (kind, canonical_name). Pending is a dict-by-kind so cross-kind collisions
# (Flow Foo vs Apex Foo) stay distinct.
#
# this is the single source of truth for wave-level BFS. Both
# `harvest_waves` and `main()` route through here so the tuple-keyed
# semantics are active on the production path — not just under unit tests.
#
# kind tokens match the runtime tree's `kind` field
# (FLOW/APEX/PROMPT_TEMPLATE/STANDARD_ACTION). The persisted
# `_pending_fetches` dict uses the SAME tokens so internal + on-disk
# conventions don't diverge.
#
# promoted from `_BFS_KINDS` → `BFS_KINDS` so
# cross-module callers (main.py's in-process orchestrator) import a stable
# public symbol instead of reaching across a leading-underscore boundary.
# Same pattern as rest_client.redact_text's promotion. The underscore
# alias below is retained for backwards compatibility and will be removed
# in the next minor version; new code MUST use `BFS_KINDS`.
# unified node-truncation annotation. When a node is not fully
# expanded (either because of a cycle back to an ancestor, or because the
# MAX_BFS_DEPTH cap tripped), we annotate it with a `_truncated` sub-
# object of shape `{"reason": <str>, "target": <str>}`. `reason` is one
# of the values below; `target` is a `"KIND:name"` path pointing at the
# first encounter (cycle) or the unreached leaf (depth-cap). Downstream
# consumers check `_truncated["reason"]` once; no per-reason pattern
# matching.
#
# Backcompat: `_cycle_back_to` is emitted alongside `_truncated` for any
# consumer that hasn't migrated (render_architecture, summarize_tree,
# third-party tooling). Will be removed in the next minor version.
TRUNCATION_CYCLE = "cycle"
TRUNCATION_MAX_DEPTH = "max-depth"
TRUNCATION_REASONS = frozenset({TRUNCATION_CYCLE, TRUNCATION_MAX_DEPTH})


BFS_KINDS = ("FLOW", "APEX", "PROMPT_TEMPLATE", "STANDARD_ACTION")

# STANDARD_ACTION is a Salesforce-owned builtin (e.g.
# `streamKnowledgeSearch`, `createRecord`, `sendEmail`). These are never
# fetched — they're declared-only leaves, with the action name carrying
# all the identity. Keeping STANDARD_ACTION in BFS_KINDS lets the tree's
# _kind_counts tally include them and visited-bookkeeping dedup against
# them, but they must never accumulate into `_pending_fetches`. A name
# like `streamKnowledgeSearch` landing in _pending_fetches.STANDARD_ACTION
# is pollution — the pipeline isn't "missing" anything; the action is
# simply declared and never materialized.
#
# Callers: when collecting refs into `new_refs`, gate on FETCHABLE_KINDS
# rather than BFS_KINDS to avoid polluting pending buckets with leaves.
FETCHABLE_KINDS = ("FLOW", "APEX", "PROMPT_TEMPLATE")

# deprecated alias. Retained so existing tests and any lingering
# `from parse_wave import _BFS_KINDS` imports keep working. New code MUST
# use `BFS_KINDS` (public). Planned removal in the next minor version.
_BFS_KINDS = BFS_KINDS


def bfs_step(
    pending_by_kind: dict[str, set[str]],
    visited_by_kind: dict[str, set[str]],
    new_refs_by_kind: dict[str, set[str]],
) -> tuple[dict[str, set[str]], list[tuple[str, str]]]:
    """Advance one BFS wave. Returns (new_pending_by_kind, cycles).

    `cycles` is a list of (kind, name) tuples for refs that were already
    visited on this wave — callers use these to annotate `_cycle_back_to`.

    Self-cycles (a ref pointing at something already visited) are filtered
    out of pending. Cross-type tuples (Flow Foo + Apex Foo) are distinct —
    both land in their respective pending buckets.

    unknown kinds RAISE — this is an internal API; a typo in a caller
    is a programming error, not a recoverable runtime condition. Silent drop
    produced false confidence (the dropped ref never got fetched and no log
    ever mentioned it). Callers must filter to `BFS_KINDS` upstream.
    """
    new_pending: dict[str, set[str]] = {k: set() for k in BFS_KINDS}
    cycles: list[tuple[str, str]] = []
    for kind, refs in new_refs_by_kind.items():
        if kind not in BFS_KINDS:
            raise ValueError(
                f"unknown BFS kind {kind!r}; must be one of {sorted(BFS_KINDS)}"
            )
        visited = visited_by_kind.get(kind, set())
        for name in refs:
            if name in visited:
                cycles.append((kind, name))
                continue
            # Not yet visited AND not already pending on a prior wave:
            # OR-in unconditionally — `pending |= (new - visited)` semantics.
            new_pending[kind].add(name)
    # Merge with the caller's existing pending. Caller passes the authoritative
    # pending buckets; we return the delta merged in so they can just replace.
    merged: dict[str, set[str]] = {k: set(pending_by_kind.get(k, set())) for k in BFS_KINDS}
    for kind, names in new_pending.items():
        merged[kind] |= names
    return merged, cycles


def empty_kind_sets() -> dict[str, set[str]]:
    """Build a fresh {kind: set()} dict covering every BFS_KINDS entry.

    callers use this to seed per-kind visited / pending
    buckets. Keeping it centralized means new kinds added to BFS_KINDS
    automatically flow through harvest_waves, bfs_step, and main().

    promoted from `_empty_kind_sets` → public so
    cross-module callers (main.py) can import a stable name instead of
    reaching into a private symbol. The underscore alias below is kept
    for backwards compatibility; it will be removed in the next minor
    version.
    """
    return {k: set() for k in BFS_KINDS}


# deprecated alias. Retained for backwards compatibility with any
# lingering `from parse_wave import _empty_kind_sets` imports; new code
# MUST use `empty_kind_sets` (public). Planned removal in the next minor
# version.
_empty_kind_sets = empty_kind_sets


def harvest_waves(
    work_dir: pathlib.Path,
) -> tuple[dict[str, list[dict]], dict[str, set[str]], dict[str, set[str]], list[tuple[str, str]]]:
    """Walk sf_meta/*/unpackaged/ dirs.

    Returns (flow_children, visited_by_kind, pending_by_kind, cycles).

    every ref collected from Flow XML (actionCalls + subflows)
    is routed through `bfs_step` per-flow. The tuple-keyed visited set is
    the authoritative record; flat per-name sets have been removed.

    the two dicts are keyed by `BFS_KINDS` tokens
    (FLOW/APEX/PROMPT_TEMPLATE/STANDARD_ACTION) — matching the runtime
    tree's `kind` field and the on-disk `_pending_fetches` layout.
    """
    flow_children: dict[str, list[dict]] = {}
    visited_by_kind: dict[str, set[str]] = empty_kind_sets()
    pending_by_kind: dict[str, set[str]] = empty_kind_sets()
    cycles: list[tuple[str, str]] = []

    sf_meta = work_dir / "sf_meta"
    if not sf_meta.exists():
        return flow_children, visited_by_kind, pending_by_kind, cycles

    all_wave_dirs = sorted(
        p / "unpackaged" for p in sf_meta.iterdir()
        if p.is_dir() and (p / "unpackaged").exists()
    )

    # Pass 1: flows (+ route per-flow refs through bfs_step).
    for wave_dir in all_wave_dirs:
        flows_dir = wave_dir / "flows"
        if not flows_dir.exists():
            continue
        for f in sorted(flows_dir.glob("*.flow")):
            flow_name = f.stem
            if flow_name in flow_children:
                continue  # already harvested this wave dir (earlier iter)
            visited_by_kind["FLOW"].add(flow_name)
            try:
                root = ET.parse(f).getroot()
            except ET.ParseError:
                flow_children[flow_name] = []
                continue
            children: list[dict] = []
            # Collect per-flow refs into kind-bucketed sets for one bfs_step.
            new_refs: dict[str, set[str]] = empty_kind_sets()
            for ac in root.findall("sf:actionCalls", NS):
                n = _t(ac, "sf:name")
                at = _t(ac, "sf:actionType") or ""
                an = _t(ac, "sf:actionName")
                item = classify_action_call(at, an, n)
                children.append(item)
                k = item["kind"]
                api = item["api_name"]
                # Only route FETCHABLE kinds into `new_refs` — STANDARD_ACTION
                # items stay as leaf children with no further fetching implied
                # . UNKNOWN items are similarly skipped.
                if k in FETCHABLE_KINDS and api:
                    new_refs[k].add(api)
            for sub in root.findall("sf:subflows", NS):
                n = _t(sub, "sf:name")
                fn = _t(sub, "sf:flowName")
                if fn:
                    children.append({"kind": "FLOW", "element_name": n, "api_name": fn})
                    new_refs["FLOW"].add(fn)
            flow_children[flow_name] = children
            # bfs_step is the canonical merge point.
            pending_by_kind, step_cycles = bfs_step(
                pending_by_kind, visited_by_kind, new_refs
            )
            cycles.extend(step_cycles)

    # Pass 2: APEX classes (mark visited).
    for wave_dir in all_wave_dirs:
        apex_dir = wave_dir / "classes"
        if apex_dir.exists():
            for f in sorted(apex_dir.glob("*.cls-meta.xml")):
                visited_by_kind["APEX"].add(f.name.replace(".cls-meta.xml", ""))

    # Pass 3: Prompt templates (mark visited).
    for wave_dir in all_wave_dirs:
        prompt_dir = wave_dir / "genAiPromptTemplates"
        if prompt_dir.exists():
            for f in sorted(prompt_dir.glob("*.genAiPromptTemplate")):
                visited_by_kind["PROMPT_TEMPLATE"].add(f.stem)

    # Passes 2/3 may have added visited entries AFTER pass-1 pending routing;
    # prune anything that's now visited. This preserves the invariant that
    # `pending ∩ visited = ∅` without needing a second bfs_step.
    for kind in BFS_KINDS:
        pending_by_kind[kind] -= visited_by_kind[kind]

    return flow_children, visited_by_kind, pending_by_kind, cycles


def init_tree(work_dir: pathlib.Path, bundle: dict) -> dict:
    bd_rec = {}
    bd_file = work_dir / "_bot_definition.json"
    if bd_file.exists():
        try:
            recs = (json.loads(bd_file.read_text()).get("result") or {}).get("records") or []
            if recs:
                bd_rec = recs[0]
        except (OSError, json.JSONDecodeError):
            pass

    tree = {
        # 3.0 bumps the _pending_fetches key convention from
        # Metadata-API tokens (Flow/ApexClass/GenAiPromptTemplate) to the
        # runtime-tree `kind` tokens (FLOW/APEX/PROMPT_TEMPLATE/
        # STANDARD_ACTION). `cache_check.py`'s schema-version gate busts any
        # pre-3.0 cache on first run.
        #
        # 3.1 (2026-05-05) canonicalizes `invocation_type` on STANDARD_ACTION
        # nodes (formerly split across `raw_invocation_type` on bundle-
        # sourced nodes and `raw_action_type` on flow-actionCall-sourced
        # nodes). Readers fall back to the two legacy keys for one release.
        "_schema_version": "3.1",
        "agent": {
            "api_name": os.environ["AGENT_API_NAME"],
            "version": os.environ["AGENT_VERSION"],
            "bot_id": os.environ.get("BOT_ID", ""),
            "master_label": bd_rec.get("MasterLabel") or os.environ.get("BOT_MASTER_LABEL", ""),
            "description": bd_rec.get("Description"),
            "agent_type": bd_rec.get("AgentType"),
            "type": bd_rec.get("Type"),
            "agent_template": bd_rec.get("AgentTemplate"),
            "bot_source": bd_rec.get("BotSource"),
            "generation": bundle.get("generation", "unknown"),
            "planner_name": bundle.get("plannerName"),
            "planner_type": bundle.get("plannerType"),
            "_version_auto_picked": (os.environ.get("VERSION_AUTO_PICKED", "") == "true"),
        },
        "root": {
            "kind": "BOT_DEFINITION",
            "api_name": os.environ["AGENT_API_NAME"],
            "children": [],
        },
        "node_count": 0,
        "depth": 0,
        # `_partial` + `_partial_reason` propagate from parse_wave's
        # depth-cap detection through to emit_result's PARTIAL_OK status.
        # `_partial_reason` values: "max-depth-cap" | "pending-refs" | null.
        "_partial": True,
        "_partial_reason": None,
        "_pending_fetches": {k: [] for k in BFS_KINDS},
        "_unresolved": [],
        "_visited": [],
    }
    return tree


def build_root_children(
    bundle: dict,
    visited_by_kind: dict[str, set[str]],
    aux_visited: set[tuple[str, str]],
) -> tuple[list[dict], dict[str, set[str]]]:
    """Build the root's topic / plannerAction children.

    bundle-scoped FLOW/APEX/PROMPT_TEMPLATE refs are collected
    into a kind-keyed `new_refs` dict and returned to the caller, which runs
    them through `bfs_step` for uniform pending-merge + cycle tracking.
    This used to directly mutate three flat sets — split out so the tuple-
    keyed semantics apply to bundle-derived refs too, not just wave-derived
    ones.

    `aux_visited` tracks non-BFS node identity (GEN_AI_FUNCTION / TOPIC) so
    the persisted `_visited` list still represents every node the walker
    has laid hands on. It is NOT consulted by bfs_step.
    """
    children: list[dict] = []
    new_refs: dict[str, set[str]] = empty_kind_sets()

    def action_node(action: dict) -> dict:
        unwraps, leaf = classify_bundle_action(action)
        aux_visited.add(("GEN_AI_FUNCTION", action["name"]))
        node = {
            "kind": "GEN_AI_FUNCTION",
            "api_name": action["name"],
            "unwraps_to": unwraps,
            "children": [leaf] if leaf else [],
        }
        if unwraps:
            tgt = unwraps.get("api_name")
            kind = unwraps.get("kind")
            # STANDARD_ACTION is declared-only, never
            # fetched; routing it into `new_refs` would pollute
            # `_pending_fetches.STANDARD_ACTION`. Gate on FETCHABLE_KINDS.
            if kind in FETCHABLE_KINDS and tgt and tgt not in visited_by_kind[kind]:
                new_refs[kind].add(tgt)
        return node

    for topic in bundle.get("topics", []) or []:
        aux_visited.add(("TOPIC", topic["name"]))
        children.append({
            "kind": "TOPIC",
            "api_name": topic["name"],
            "children": [action_node(a) for a in topic.get("actions", []) or []],
        })

    # bundle["plannerActions"] is always [] now (a planner never has
    # direct functions — 2026-05-05). The key stays in the bundle dict
    # for back-compat with consumers that still call `.get("plannerActions")`.

    return children, new_refs


# ---------------------------------------------------------------------------
# cycle-safe inflate with (kind, canonical_name) tuple-keyed tracking.
#
# Visited tracking uses tuple keys so a Flow `Foo` and an Apex `Foo` are
# distinct nodes — a flat name-only set would silently drop the second one.
# Flow→subflow cycles (direct or cross-type A→B→A) are annotated with
# `_cycle_back_to` on the repeat node and recursion terminates immediately.
#
# , revised 2026-05-03: `MAX_BFS_DEPTH` is a DEFENSIVE termination
# guard, not a functional constraint on chain depth. Must stay in sync
# with `scripts/config.py::MAX_BFS_DEPTH` — duplicated (rather than
# imported) because this module runs as a standalone subprocess under
# `python3 parse_wave.py` (see `main()`) and the module has a long-standing
# "no intra-skill imports" convention (search `no intra-skill imports'
# convention`).
#
# Real cycle detection is per-branch via `visited_in_path`: a flow that
# appears on sibling branches is NOT a cycle (e.g. `handleFlowFault`,
# invoked from many parents), but the same flow recurring along its own
# ancestor chain IS. Textbook DFS cycle detection.
#
# Before the revision this was `5` and the cap itself tripped on shared
# utility flows (`handleFlowFault`, logging subflows) — those landed in
# `_pending_fetches["FLOW"]` and the user saw `PARTIAL_REASON=max-depth-cap`
# on trees that were in fact fully knowable. Bumping to 20 keeps a safety
# net for pathological graphs while letting per-branch cycle detection do
# the real work. On every real bot tree observed to date, the per-branch
# check terminates well below depth 20.
#
# When this cap *does* trip (truly exceptional), the unreached FLOW lands
# in `pending_out["FLOW"]` and the leaf is annotated `_truncated =
# {reason: "max-depth", target: "FLOW:<name>"}`, exactly as before.
MAX_BFS_DEPTH = 20

# Retained alias so the `MAX_INFLATE_DEPTH` symbol (referenced in older
# agent notes / docs) still resolves. Tracks `MAX_BFS_DEPTH` exactly; the
# 2026-05-03 revision reinterpreted this as a defensive guard rather than
# a functional cap, but the alias semantics are unchanged.
MAX_INFLATE_DEPTH = MAX_BFS_DEPTH
_FLOW_CYCLE_KINDS = frozenset({"FLOW"})  # the only kind that recurses here


def _cycle_key(node: dict) -> tuple[str, str]:
    """Tuple key for visited / cycle detection. Flows use canonical api_name.

    keying on `(kind, api_name)` — NOT just name — so cross-kind
    collisions (Flow Foo + Apex Foo) stay distinct.
    """
    return (node.get("kind") or "", node.get("api_name") or "")


def inflate_flow_leaf(
    leaf: dict,
    flow_children: dict,
    depth: int = 0,
    visited_in_path: frozenset[tuple[str, str]] | None = None,
    pending_out: dict[str, set[str]] | None = None,
) -> None:
    """Recursively expand a FLOW leaf's subflow tree.

    `visited_in_path` is threaded through the recursion as an
    IMMUTABLE frozenset — siblings at the same depth must NOT observe
    each other's descent. Mutating a shared set would cause the second
    sibling to be pruned as a false cycle.

    `pending_out` is an OPTIONAL mutable accumulator keyed by
    `BFS_KINDS` tokens. When the depth cap trips (`depth >= MAX_BFS_DEPTH`)
    and the current leaf still has subflow children we'd normally expand,
    those unreached targets are added to `pending_out[kind]` so a caller
    can surface them as `_pending_fetches` on the tree with
    `_partial=True` + `_partial_reason="max-depth-cap"`. When `pending_out`
    is None (legacy callers), the cap behaves as before — silently skip.
    """
    # depth-cap check. We use `>=` (not `>`) so the cap matches
    # `MAX_BFS_DEPTH` exactly — at depth 5 we do NOT expand the current
    # leaf, and the leaf's own (kind, api_name) is recorded in
    # `pending_out` as "unreached". Rationale: this node was supposed
    # to be fully explored but we hit the cap on the way in. Naming
    # the leaf itself (not its kids) is what downstream callers need
    # to surface as `_pending_fetches["FLOW"] = [<unreached>]`.
    if depth >= MAX_BFS_DEPTH:
        if leaf.get("kind") == "FLOW":
            flow_name = leaf.get("api_name")
            if flow_name:
                if pending_out is not None:
                    pending_out.setdefault("FLOW", set()).add(flow_name)
                # annotate the truncated leaf with the unified
                # `_truncated` sub-object so rendered tree views can
                # mark depth-capped nodes alongside cycle nodes using
                # one predicate. The target points at the leaf itself
                # (it was supposed to be fully explored but the cap
                # tripped on the way in).
                leaf["_truncated"] = {
                    "reason": TRUNCATION_MAX_DEPTH,
                    "target": f"FLOW:{flow_name}",
                }
        return
    if leaf.get("kind") != "FLOW":
        return
    flow_name = leaf.get("api_name")
    if not flow_name:
        return
    kids = flow_children.get(flow_name)
    if not kids:
        return  # no data this wave; preserve any existing children

    # Extend the path-visited set with this node. Frozenset keeps sibling
    # branches independent — mutation would cross-contaminate.
    leaf_key = _cycle_key(leaf)
    path_set = (visited_in_path or frozenset()) | {leaf_key}

    new_children: list[dict] = []
    for k in kids:
        item = {"kind": k["kind"], "element_name": k.get("element_name"), "api_name": k["api_name"]}
        # Carry the STANDARD_ACTION / UNKNOWN invocation-type qualifier
        # through to the expanded child. Canonical key is `invocation_type`
        # (schema 3.1); legacy `raw_action_type` kept for one release so
        # caches built by an older parse_wave still render cleanly.
        if "invocation_type" in k:
            item["invocation_type"] = k["invocation_type"]
        if "raw_action_type" in k:
            item["raw_action_type"] = k["raw_action_type"]
        if k["kind"] == "FLOW":
            item["children"] = []
            child_key = _cycle_key(item)
            if child_key in path_set:
                # cycle detected — annotate and do NOT recurse.
                # Path format: "<KIND>:<name>" of the first encounter.
                # unified `_truncated` sub-object + legacy
                # `_cycle_back_to` for backcompat.
                target_path = f"{child_key[0]}:{child_key[1]}"
                item["_truncated"] = {
                    "reason": TRUNCATION_CYCLE,
                    "target": target_path,
                }
                item["_cycle_back_to"] = target_path  # deprecated alias
                new_children.append(item)
                continue
            new_children.append(item)
            inflate_flow_leaf(item, flow_children, depth + 1, path_set, pending_out)
        else:
            new_children.append(item)
    leaf["children"] = new_children


def walk_and_inflate(
    node: dict,
    flow_children: dict,
    depth: int = 0,
    pending_out: dict[str, set[str]] | None = None,
) -> None:
    """Walk the tree and inflate every FLOW leaf we encounter.

    Each inflate call starts with an empty path-visited set — tree-walk
    descent is not itself a Flow recursion, so ancestor GEN_AI_FUNCTION
    or TOPIC nodes don't count toward cycle detection.

    `pending_out` (optional) is threaded into every `inflate_flow_leaf`
    call so depth-cap truncations accumulate into a single shared dict,
    which `main()` merges into `tree["_pending_fetches"]` + flips
    `tree["_partial"]` with reason `max-depth-cap`.
    """
    if node.get("kind") == "GEN_AI_FUNCTION":
        for child in node.get("children", []) or []:
            if child.get("kind") == "FLOW":
                inflate_flow_leaf(child, flow_children, depth, pending_out=pending_out)
    elif node.get("kind") == "FLOW":
        inflate_flow_leaf(node, flow_children, depth, pending_out=pending_out)
    for c in node.get("children", []) or []:
        walk_and_inflate(c, flow_children, depth + 1, pending_out)


def compute_stats(root: dict) -> tuple[int, int, dict]:
    counts: Counter = Counter()

    def walk(node: dict, d: int = 0) -> int:
        k = node.get("kind")
        if k:
            counts[k] += 1
        max_d = d
        for c in node.get("children", []) or []:
            max_d = max(max_d, walk(c, d + 1))
        return max_d

    depth = walk(root)
    return sum(counts.values()), depth, dict(counts)


def atomic_write_json(path: pathlib.Path, obj: dict) -> None:
    tmp = path.with_suffix(path.suffix + ".tmp")
    tmp.write_text(json.dumps(obj, indent=2))
    os.replace(tmp, path)


def finalize_cap(tree: dict) -> dict:
    """Move remaining _pending_fetches items to _unresolved[].

    pending and unresolved both use the same kind tokens now
    (FLOW/APEX/PROMPT_TEMPLATE/STANDARD_ACTION) — matching the runtime
    tree's `kind` field.

    depth-cap truncation writes `_partial=True` +
    `_partial_reason="max-depth-cap"` earlier in the pipeline. Finalize
    preserves those signals when it drains pending → unresolved so the
    downstream emit_result.py can still surface PARTIAL_OK with the
    correct reason. If BOTH the depth cap AND finalize-cap fire on the
    same run, depth-cap wins priority (set first, not overwritten).
    """
    pending = tree.get("_pending_fetches") or {}
    unresolved = tree.setdefault("_unresolved", [])
    drained_any = False
    for kind, items in pending.items():
        for n in items:
            drained_any = True
            unresolved.append({
                "kind": kind,
                "api_name": n,
                "reason": "max-wave-depth exceeded",
            })
    tree["_pending_fetches"] = {k: [] for k in BFS_KINDS}

    # if pending was drained but no `_partial_reason` is set yet,
    # mark it as wave-depth exhaustion. DO NOT overwrite an existing
    # `max-depth-cap` reason — the depth-cap trigger is strictly earlier
    # and more specific.
    if drained_any:
        tree["_partial"] = True
        if not tree.get("_partial_reason"):
            tree["_partial_reason"] = "max-wave-depth"
    return tree


def main() -> int:
    finalize_cap_mode = "--finalize-cap" in sys.argv

    try:
        work_dir = pathlib.Path(os.environ["WORK_DIR"])
    except KeyError as e:
        sys.stderr.write(f"parse_wave.py: missing env {e}\n")
        return 1

    tree_path = work_dir / "declared_action_tree.json"

    # --finalize-cap: trivial; just drain pending → unresolved on existing tree
    if finalize_cap_mode:
        if not tree_path.is_file():
            sys.stderr.write("parse_wave.py: --finalize-cap with no tree file; noop\n")
            return 0
        try:
            tree = json.loads(tree_path.read_text())
        except (OSError, json.JSONDecodeError) as e:
            sys.stderr.write(f"parse_wave.py: cannot read tree: {e}\n")
            return 1
        tree = finalize_cap(tree)
        try:
            atomic_write_json(tree_path, tree)
        except OSError as e:
            sys.stderr.write(f"parse_wave.py: write failed: {e}\n")
            return 1
        sys.stderr.write(
            f"[parse_wave] finalize-cap: {len(tree.get('_unresolved', []))} nodes unresolved\n"
        )
        return 0

    # Standard init-or-reparse path
    bundle_path = work_dir / "_bundle_parsed.json"
    if not bundle_path.is_file():
        sys.stderr.write(f"parse_wave.py: missing {bundle_path}\n")
        return 1
    try:
        bundle = json.loads(bundle_path.read_text())
    except (OSError, json.JSONDecodeError) as e:
        sys.stderr.write(f"parse_wave.py: bundle parse error: {e}\n")
        return 1

    # Harvest wave dirs. Returns kind-keyed visited + pending dicts plus
    # the list of (kind, name) cycles detected during per-flow BFS merges.
    flow_children, wave_visited_by_kind, pending_by_kind, _wave_cycles = harvest_waves(work_dir)

    # Load-or-init tree
    if tree_path.is_file():
        try:
            tree = json.loads(tree_path.read_text())
        except (OSError, json.JSONDecodeError) as e:
            sys.stderr.write(f"parse_wave.py: cannot re-parse; reinitializing ({e})\n")
            tree = init_tree(work_dir, bundle)
    else:
        tree = init_tree(work_dir, bundle)

    # Rehydrate tuple-keyed visited from the persisted _visited list and
    # union with wave-derived visited. Non-BFS kinds (TOPIC/GEN_AI_FUNCTION)
    # live in `aux_visited` — they're persisted in _visited but do NOT
    # participate in BFS routing.
    visited_by_kind: dict[str, set[str]] = empty_kind_sets()
    for kind, names in wave_visited_by_kind.items():
        visited_by_kind[kind] |= names
    aux_visited: set[tuple[str, str]] = set()
    for pair in (tree.get("_visited") or []):
        if not pair or len(pair) != 2:
            continue
        k, n = pair[0], pair[1]
        if k in BFS_KINDS:
            visited_by_kind[k].add(n)
        else:
            aux_visited.add((k, n))

    # If the tree was just initialized, populate root children (only once).
    # bundle-derived refs now flow through bfs_step via
    # build_root_children's new_refs return value — same code path as
    # wave-derived refs.
    is_fresh = not (tree.get("root", {}).get("children"))
    if is_fresh:
        children, bundle_new_refs = build_root_children(
            bundle, visited_by_kind, aux_visited
        )
        tree["root"]["children"] = children
        pending_by_kind, _bundle_cycles = bfs_step(
            pending_by_kind, visited_by_kind, bundle_new_refs
        )

    # Inflate Flow leaves wherever possible.
    # `depth_cap_pending` captures subflow refs we skipped because
    # the depth cap tripped — these get merged into `_pending_fetches`
    # below so downstream emit_result.py can surface `PARTIAL_OK`.
    depth_cap_pending: dict[str, set[str]] = empty_kind_sets()
    walk_and_inflate(tree["root"], flow_children, pending_out=depth_cap_pending)

    # Merge depth-cap-suppressed refs back into pending_by_kind so they
    # land in `_pending_fetches`. Preserve any existing (already-visited)
    # exclusion semantics — refs already fetched this run MUST NOT be
    # re-reported as pending.
    for kind in BFS_KINDS:
        pending_by_kind[kind] |= depth_cap_pending.get(kind, set())

    depth_cap_tripped = any(depth_cap_pending[k] for k in BFS_KINDS)

    # Recompute pending (exclude anything now visited). the
    # persisted dict uses the same `BFS_KINDS` tokens as the runtime tree
    # and the in-memory buckets — no more Metadata-API-style aliasing.
    tree["_pending_fetches"] = {
        k: sorted(pending_by_kind.get(k, set()) - visited_by_kind.get(k, set()))
        for k in BFS_KINDS
    }

    # surface a `_partial` signal when:
    # (a) depth-cap-pending refs exist (we suppressed deep subflows), OR
    # (b) any `_pending_fetches` bucket is non-empty at write time.
    # `_partial_reason` identifies which of the two tripped — `max-depth-cap`
    # takes priority when depth_cap_pending is non-empty, since the cap is
    # the reason pending refs weren't drained to `_unresolved` yet.
    any_pending = any(tree["_pending_fetches"][k] for k in BFS_KINDS)
    if depth_cap_tripped:
        tree["_partial"] = True
        tree["_partial_reason"] = "max-depth-cap"
    elif any_pending:
        # Still incomplete but NOT because of the depth cap. Leave any
        # existing reason intact if prior run set it; default to a neutral
        # marker so emit_result.py can still flip to PARTIAL_OK.
        tree["_partial"] = True
        if not tree.get("_partial_reason"):
            tree["_partial_reason"] = "pending-refs"
    else:
        tree["_partial"] = False
        tree["_partial_reason"] = None

    # Recompute node_count + depth + kind_counts
    node_count, depth, kind_counts = compute_stats(tree["root"])
    tree["node_count"] = node_count
    tree["depth"] = depth
    tree["_kind_counts"] = kind_counts

    # Persist visited as sorted list of [kind, name] pairs. Includes aux
    # kinds (TOPIC/GEN_AI_FUNCTION) so the replay surface is complete.
    all_visited: set[tuple[str, str]] = set(aux_visited)
    for kind, names in visited_by_kind.items():
        for n in names:
            all_visited.add((kind, n))
    tree["_visited"] = [list(v) for v in sorted(all_visited)]

    try:
        atomic_write_json(tree_path, tree)
    except OSError as e:
        sys.stderr.write(f"parse_wave.py: write failed: {e}\n")
        return 1

    # log line mirrors the persisted dict's kind tokens.
    pending_total = sum(len(v) for v in tree["_pending_fetches"].values())
    sys.stderr.write(
        f"[parse_wave] parsed: {node_count} nodes, depth {depth}, counts={kind_counts}, "
        f"pending={pending_total} "
        f"(flow={len(tree['_pending_fetches']['FLOW'])} "
        f"apex={len(tree['_pending_fetches']['APEX'])} "
        f"prompt_template={len(tree['_pending_fetches']['PROMPT_TEMPLATE'])} "
        f"standard_action={len(tree['_pending_fetches']['STANDARD_ACTION'])})\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