@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/investigating-agentforce-architecture/scripts/fetch_soql.py

@@ -0,0 +1,689 @@
+"""SOQL-based body fetchers for Wave A (GenAi normalized DAG) + Wave B
+(Flow / Apex body bodies).
+
+Phase 2 Batch 1: this module is the single surface `main.py`'s orchestrator
+composes against. Every function in this module is a thin wrapper over
+`soql_loader` + `rest_client.{tooling_query, data_query}`. Three invariants:
+
+    1. Credentials always flow through a `creds_provider` closure
+       (`Callable[[], tuple[str, str]]`) so `retry_on_401`'s refresh path
+       can deliver fresh creds into the retry. See rest_client 
+    2. Empty list inputs short-circuit to `[]` WITHOUT firing a SOQL call.
+       `load_soql_in` refuses empty lists (SF syntax error), so callers
+       upstream shouldn't have to guard every batch site — guard once here.
+    3. `api_version` (.4-R4, 2026-05-02) is REQUIRED on every fetcher.
+       The prior `rest_client.tooling_query` pinned `v60.0` and that
+       floor was the source of on orgs running v66 — which
+       genuinely expose fields v60 does not (`BotDefinition.Description`
+       is the observed case). Callers read the version once via
+       `main._derive_org_ids` (from `sf org display --json`) and thread
+       it through here. Same defensive pattern as for
+       `on_401_refresh`: no default, so a missed call-site is a
+       TypeError at call time, not a silent regression.
+
+All failure paths use `rest_client.redact_error` implicitly: the helpers
+raise `RestClientError` with pre-redacted messages. Callers that log should
+call `redact_error(exc)` themselves rather than `str(exc)` on any wrapped
+urllib/subprocess exception — redaction at the reporting site is
+defence-in-depth.
+
+`on_401_refresh` is a REQUIRED keyword-only arg
+on every fetcher in this module. The previous default (`on_401_refresh
+or creds_provider`) silently collapsed to "re-read the same stale token"
+when a caller passed `None` — the retry would hit the identical stale
+token on the second attempt and 401 again, bypassing entirely.
+Making the parameter required surfaces that misuse as a TypeError at
+import/call time instead of as a silent auth failure under load.
+"""
+from __future__ import annotations
+
+import logging
+import urllib.error
+from typing import Callable, Tuple
+
+from rest_client import data_query, tooling_query
+from soql_loader import load_soql, load_soql_in
+
+logger = logging.getLogger(__name__)
+
+
+CredsProvider = Callable[[], Tuple[str, str]]
+
+
+# ---------------------------------------------------------------------------
+# Small record-extraction helper. SF REST query responses wrap the row list
+# under `.records`; tooling + data surfaces agree on this shape. One helper
+# keeps the Wave A/B fetchers trivial — they call `_records(tooling_query(...))`
+# and return a list[dict].
+# ---------------------------------------------------------------------------
+
+
+def _records(response: dict) -> list[dict]:
+    """Extract records list from a SOQL query response.
+
+    SF REST returns `{"totalSize": N, "done": true, "records": [...]}` on
+    both Data and Tooling APIs. A missing `records` key (malformed response,
+    empty result) degrades to `[]` — callers that need a single record
+    slice the list themselves; callers that batch don't have to branch on
+    "records missing".
+    """
+    if not isinstance(response, dict):
+        return []
+    recs = response.get("records")
+    if not isinstance(recs, list):
+        return []
+    return recs
+
+
+# ===========================================================================
+# Wave A — GenAi normalized fetchers (Tooling API only)
+# ===========================================================================
+# DAG, per plan section B.5:
+#
+# A1 planner_definition_by_agent_chain scalar: AGENT_NAME [+ VERSION]
+# A2 plugins_by_planner scalar: PLANNER_ID
+# A3 planner_bundle_functions scalar: PLANNER_ID
+# A4 functions_by_plugins list: PLUGIN_IDS
+# A5 plugin_instructions_by_plugin_ids list: PLUGIN_IDS
+# A6 plugin_functions_by_plugin_ids list: PLUGIN_IDS
+# A7 planner_attrs_by_parent_ids list: PARENT_IDS
+#
+# Ordering: A1 first (provides planner_id). Then A2 + A3 can parallelize.
+# Once A2 yields plugin_ids, A4 / A5 / A6 parallelize. A7 last once A4
+# yields function_ids.
+# ---------------------------------------------------------------------------
+
+
+def fetch_planner_definition(
+    agent_api_name: str,
+    version: str | None,
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> dict | None:
+    """Wave A1: resolve the live GenAiPlannerDefinition for (agent, version).
+
+    Agentforce generates an accretive chain of planner DeveloperNames as
+    agents version up — v1 = `<Agent>`, v2 = `<Agent>_v2`, v3 =
+    `<Agent>_v2_v3`, ... The chain shape is unpredictable from
+    (agent, version) alone, but an invariant holds: for vN the
+    DeveloperName always starts with `<agent_api_name>` and ends with
+    `_v<N>` for N>=2; for v1 it is exactly `<agent_api_name>`. A single
+    SOQL LIKE lookup pinned to that shape lands on the correct row
+    regardless of chain depth.
+
+    Branching:
+      * `version` is None / empty / "v1" → exact match. SOQL built
+        inline as `LIKE '<agent_api_name>'` (no wildcards — degenerate
+        LIKE is equivalent to `=`). The v1 branch bypasses the chain
+        template because the template's `%\\_{{VERSION}}` tail has no
+        sensible empty-version rendering.
+      * v2+ → LIKE `<agent_api_name>%\\_<version>`. The backslash escapes
+        the single-char wildcard `_` so `_v2` matches literally, not as
+        "any character then v2".
+
+    Escaping note (2026-05-05): the SOQL template on disk carries `\\_`
+    (one backslash, one underscore) because the REST Query endpoint
+    consumes the body verbatim — no shell, no extra quoting layer. If a
+    future caller ever shells this through `bash -c`, the backslash would
+    need doubling; we don't currently have that call path.
+
+    Disambiguation: if the LIKE returns multiple rows (e.g. a longer
+    chain name ALSO matches the pattern because it happens to end in
+    `_v2` too), pick the shortest DeveloperName — the canonical chain
+    ends at exactly `<agent_api_name>...<_v{version}>` with no suffix,
+    so shortest always wins.
+
+    Returns the planner dict or `None` if no row matches.
+
+    `load_soql` revalidates each substituted value against
+    `[A-Za-z0-9_]+` . `agent_api_name` and `version` satisfy that
+    regex; the `%\\_` literals live in the SOQL template, not in a
+    substituted variable, so they never traverse the validator.
+    """
+    v = (version or "").strip()
+    if v in ("", "v1"):
+        # v1 branch: DeveloperName is exactly `<agent_api_name>`. A LIKE
+        # with no wildcards is equivalent to `=`. We can't re-use the
+        # chain template with an empty VERSION (load_soql rejects empty
+        # strings AND the template's trailing `%\_{{VERSION}}` wouldn't
+        # collapse cleanly), so build the SOQL directly here. We still
+        # run the agent_api_name through the same validator load_soql
+        # uses, so the v1 path has no weaker injection surface than the
+        # v2+ path.
+        from config import fs_guard  # re-exported from _shared/
+        from soql_loader import SoqlParamError as _SoqlParamError
+        try:
+            fs_guard.validate_api_name(agent_api_name, label="AGENT_NAME")
+        except fs_guard.ValidationError as e:
+            raise _SoqlParamError("AGENT_NAME", agent_api_name, e.reason) from None
+        soql = (
+            "SELECT Id, DeveloperName, MasterLabel, Description, "
+            "PlannerType, Capabilities, AgentGraph\n"
+            "FROM GenAiPlannerDefinition\n"
+            f"WHERE DeveloperName LIKE '{agent_api_name}'"
+        )
+    else:
+        soql = load_soql(
+            "planner_definition_by_agent_chain",
+            AGENT_NAME=agent_api_name,
+            VERSION=v,
+        )
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    recs = _records(resp)
+    if not recs:
+        return None
+    # Disambiguate on shortest DeveloperName — the canonical chain row
+    # has no suffix beyond `_v<N>`. A longer row means the LIKE also
+    # matched a deeper-chain planner that happens to share the suffix.
+    recs.sort(key=lambda r: len(r.get("DeveloperName") or ""))
+    return recs[0]
+
+
+def fetch_plugins_by_planner(
+    planner_id: str,
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave A2: topic list for a planner."""
+    soql = load_soql("plugins_by_planner", PLANNER_ID=planner_id)
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_planner_bundle_functions(
+    planner_id: str,
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave A3: planner-bundle-scope function join rows (classic).
+
+    NGA planners have no bundle-scope functions (PlannerId is null on
+    every row); this query returns [] on NGA orgs. Caller doesn't have
+    to branch.
+    """
+    soql = load_soql("planner_bundle_functions", PLANNER_ID=planner_id)
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_functions_by_plugins(
+    plugin_ids: list[str],
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave A4: actions (GenAiFunctionDefinition) under a planner's plugins.
+
+    User invariant: a planner never has direct functions (PlannerId-only
+    rows with no PluginId are orphan data, not live actions). The prior
+    `PlannerId = '<id>' OR ...` leg dragged in those orphans and
+    surfaced them as stray root-level children. The query is now a
+    single IN-list over plugin_ids; the PlannerId + ParentId columns
+    stay in the SELECT for downstream consumers (parse_bundle, etc.)
+    that still read them.
+
+    Empty `plugin_ids` short-circuits — a SequentialPlannerIntent-
+    Classifier bot with zero plugins has no plugin-scope functions to
+    fetch. `load_soql_in` refuses empty lists; we guard here so callers
+    don't have to.
+    """
+    if not plugin_ids:
+        return []
+    soql = load_soql_in(
+        "functions_by_plugins",
+        list_params={"PLUGIN_IDS": plugin_ids},
+    )
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_plugin_instructions(
+    plugin_ids: list[str],
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave A5: per-topic instruction rows.
+
+    Empty `plugin_ids` → []; no SOQL fired. SequentialPlannerIntent-
+    Classifier bots and NGA single-planner shapes hit this path.
+    """
+    if not plugin_ids:
+        return []
+    soql = load_soql_in(
+        "plugin_instructions_by_plugin_ids",
+        list_params={"PLUGIN_IDS": plugin_ids},
+    )
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_plugin_functions(
+    plugin_ids: list[str],
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave A6: plugin → function join rows."""
+    if not plugin_ids:
+        return []
+    soql = load_soql_in(
+        "plugin_functions_by_plugin_ids",
+        list_params={"PLUGIN_IDS": plugin_ids},
+    )
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_planner_attrs(
+    parent_ids: list[str],
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave A7: attribute mappings for a list of parent ids.
+
+    Polymorphic ParentId: pass the UNION of function_ids + planner_id.
+    Bot shape with zero functions (no actions registered) → []; no SOQL
+    fired. Caller must include the planner_id even when function_ids is
+    empty — this helper doesn't fabricate it.
+    """
+    if not parent_ids:
+        return []
+    soql = load_soql_in(
+        "planner_attrs_by_parent_ids",
+        list_params={"PARENT_IDS": parent_ids},
+    )
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+# ===========================================================================
+# Wave B — body fetchers (Flow, Apex). Tooling API.
+# ===========================================================================
+# These are the leaves: once Wave A gives us the function rows, we resolve
+# every InvocationTarget into one of flow / apex / prompt (prompt body
+# lands via retrieve in Batch 2, not here).
+#
+# The single-row Flow.Metadata path is the big parallelism opportunity —
+# `fetch_flow_metadata` is called N times (one per version id) and
+# dispatched through `parallel_retrieve.fetch_bodies_parallel`.
+# ---------------------------------------------------------------------------
+
+
+def fetch_apex_bodies_by_names(
+    names: list[str],
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave B3 classic: Apex bodies keyed by DeveloperName.
+
+    Returns `[{Id, Name, Body, SymbolTable, ApiVersion, IsValid}, ...]`.
+    Batch-safe on `Name IN (...)` even though SymbolTable is
+    complexvalue (confirmed live — see references/soql_fields.md).
+    """
+    if not names:
+        return []
+    soql = load_soql_in(
+        "apex_class_bodies_by_names",
+        list_params={"NAMES_LIST": names},
+    )
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_apex_bodies_by_ids(
+    ids: list[str],
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave B3 NGA: Apex bodies keyed by Id.
+
+    NGA functions store InvocationTarget as Salesforce Ids (e.g. `01p...`);
+    this is the reverse-lookup path that translates back to Name + Body.
+    """
+    if not ids:
+        return []
+    soql = load_soql_in(
+        "apex_class_bodies_by_ids",
+        list_params={"APEX_IDS_LIST": ids},
+    )
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_flow_definition_view_by_durable_ids(
+    durable_ids: list[str],
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Data API fallback: resolve managed-installed flow names via
+    `FlowDefinitionView`.
+
+    `FlowDefinition` (Tooling) does not index managed-installed flows for
+    subscriber orgs — the Tooling query for a `ns__BareName` returns zero
+    rows even when the flow genuinely exists. `FlowDefinitionView` (Data
+    API only, NOT Tooling) does expose those rows via its `DurableId`
+    column, which for managed-installed flows IS the qualified
+    `ns__BareName` string.
+
+    Caveats baked into the consumer contract (see
+    `fetch_flow_definition_ids_by_names` downstream projection):
+      * `FlowDefinitionView.ActiveVersionId` is a composite display
+        string (e.g. `SvcCopilotTmpl__VerifyCode-1`), not a real
+        `Flow.Id`. It cannot be used to fetch the flow body XML —
+        managed flow bodies are IP-protected and not retrievable.
+      * Callers must project these rows with `ActiveVersionId=None` and
+        `_body_available=False` so the Wave B metadata fetcher skips
+        body retrieval for them.
+
+    Empty input short-circuits to `[]` without firing a SOQL call —
+    matches the contract on every other list-shaped fetcher in this
+    module.
+    """
+    if not durable_ids:
+        return []
+    soql = load_soql_in(
+        "flow_definition_view_by_durable_ids",
+        list_params={"DURABLE_IDS_LIST": durable_ids},
+    )
+    resp = data_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_flow_definition_ids_by_names(
+    names: list[str],
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave B1 classic: resolve Flow DeveloperName list → FlowDefinition rows.
+
+    Returns `[{Id, DeveloperName, NamespacePrefix, ActiveVersionId,
+    _bare_developer_name, _source, _body_available, ...}, ...]`.
+    Two-hop to `Flow` via `ActiveVersionId`; this is the first hop.
+
+    Resolution path (2026-05-05, post-retirement of the managed-ns
+    Tooling bucket): fire ONE Tooling `FlowDefinition` query for every
+    input name verbatim — the template filters `NamespacePrefix IS NULL`
+    so only unmanaged rows come back. Managed names like
+    `ns__BareName` return zero rows from Tooling on subscriber orgs
+    regardless of how we bucket them (live scouting confirmed Tooling
+    FlowDefinition simply does not index managed-installed flows for
+    subscribers), so attempting per-namespace Tooling queries adds cost
+    and returns nothing useful. Anything the unmanaged query doesn't
+    resolve falls through to `FlowDefinitionView` (Data API), which DOES
+    expose managed-installed flows via `DurableId = ns__BareName`.
+
+    FlowDefinitionView rows carry `Id=None`, `ActiveVersionId=None`,
+    `_body_available=False`, and `_source="FlowDefinitionView"` so
+    downstream flow metadata retrieval short-circuits (there's no real
+    version Id to fetch a body with, and managed flow bodies are
+    IP-protected regardless).
+
+    Real Tooling rows carry `_source="FlowDefinition"` and
+    `_body_available=True` set explicitly — consumers can dispatch on
+    source rather than inferring from absence.
+    """
+    if not names:
+        return []
+
+    rows: list[dict] = []
+    # Track every input name we successfully resolve via the Tooling
+    # FlowDefinition path. Anything left over goes through the
+    # FlowDefinitionView fallback.
+    resolved_names: set[str] = set()
+
+    # Unmanaged Tooling query: template explicitly filters
+    # `NamespacePrefix = NULL`. Managed-qualified names (`ns__BareName`)
+    # passed through here will simply return zero rows — which is fine,
+    # the view fallback below catches them. The null-ns filter is
+    # load-bearing: dropping it would widen to unrelated managed rows
+    # that happen to collide on a bare DeveloperName.
+    #
+    # Bug G fix: the SOQL template uses `= NULL`, NOT `IS NULL`. Tooling
+    # Query API rejects `IS NULL` with `MALFORMED_QUERY: unexpected
+    # token: 'NamespacePrefix IS'`. Only the Data API parser accepts
+    # both forms. Commit aa01d52 mistakenly switched this template to
+    # `IS NULL` (to silence a Prizm scanner false-positive) on the
+    # premise that "both forms parse identically" — true for Data API,
+    # false for Tooling. That broke wave-B subflow resolution: every
+    # call here 400'd, the FDV fallback below also returned zero
+    # because it filters by Salesforce Id (300...), and BFS hit the
+    # iteration cap. Do NOT re-introduce `IS NULL` in this template.
+    soql = load_soql_in(
+        "flow_definition_ids_by_names",
+        list_params={"NAMES_LIST": list(names)},
+    )
+    # Bug D.2 fix: tolerate HTTPError on the Tooling call. A single name
+    # in `names` that violates Salesforce's DeveloperName limits (e.g.
+    # length >40 chars, or chars Salesforce treats as non-identifier
+    # despite passing fs_guard.validate_api_name) causes the WHOLE batch
+    # to 400. Without this `try`, the entire wave-B round failed and the
+    # FDV fallback below was never reached — managed names were never
+    # resolved, BFS hit the iteration cap, operator saw cryptic
+    # `wave-b-iteration-cap` entries instead of the actual root cause.
+    # On HTTPError, fall through with `resolved_names` empty so every
+    # input is re-tried via FDV; FDV uses Data API (different validation)
+    # and tends to accept names Tooling rejects.
+    try:
+        resp = tooling_query(
+            creds_provider, soql,
+            api_version=api_version,
+            on_401_refresh=on_401_refresh,
+        )
+        for r in _records(resp):
+            dev_name = r.get("DeveloperName")
+            if dev_name:
+                r["_bare_developer_name"] = dev_name
+                r["_source"] = "FlowDefinition"
+                r["_body_available"] = True
+                rows.append(r)
+                resolved_names.add(dev_name)
+    except urllib.error.HTTPError as exc:
+        # Don't propagate — the FDV fallback below handles every
+        # unresolved name. Log enough for triage; rest_client already
+        # attached `_response_body_preview` (Bug D.1) so the body is
+        # available downstream if a caller wants to inspect.
+        logger.debug(
+            "fetch_flow_definition_ids_by_names: Tooling batch failed "
+            "(HTTP %d); falling through to FlowDefinitionView for all %d names",
+            getattr(exc, "code", 0), len(names),
+        )
+
+    # FlowDefinitionView fallback — Data API. Any input name Tooling
+    # didn't resolve is re-queried as a DurableId. Managed-installed
+    # flows are the motivating case; the view also covers unmanaged
+    # rows the Tooling surface misses for any other reason.
+    unresolved_names = [n for n in names if n not in resolved_names]
+    if unresolved_names:
+        view_rows = fetch_flow_definition_view_by_durable_ids(
+            sorted(set(unresolved_names)),
+            creds_provider,
+            api_version=api_version,
+            on_401_refresh=on_401_refresh,
+        )
+        for view_row in view_rows:
+            durable_id = view_row.get("DurableId")
+            if not durable_id:
+                continue
+            rows.append({
+                "Id": None,
+                # Qualified ns__bare (matches bundle invocationTarget +
+                # parse_wave visited-set dedupe key).
+                "DeveloperName": durable_id,
+                "NamespacePrefix": view_row.get("NamespacePrefix"),
+                # ActiveVersionId on FlowDefinitionView is a composite
+                # display string (`ns__Name-<n>`), NOT a real Flow.Id.
+                # Null it so downstream `fetch_flow_metadata` dispatch
+                # skips body retrieval for these rows.
+                "ActiveVersionId": None,
+                "_bare_developer_name": view_row.get("ApiName"),
+                "_body_available": False,
+                "_source": "FlowDefinitionView",
+                "_flow_view_label": view_row.get("Label"),
+                "_flow_view_manageable_state": view_row.get("ManageableState"),
+            })
+
+    return rows
+
+
+def fetch_flow_definition_by_ids(
+    ids: list[str],
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Wave B1 NGA: reverse-lookup FlowDefinition Id → DeveloperName.
+
+    NGA functions store Ids (`300...`). This resolves them back to names
+    so the tree's leaf nodes can carry the human-readable DeveloperName
+    and the active version id for Wave B2.
+    """
+    if not ids:
+        return []
+    soql = load_soql_in(
+        "flow_definition_by_ids",
+        list_params={"FLOW_DEF_IDS_LIST": ids},
+    )
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_flow_metadata(
+    flow_version_id: str,
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> dict | None:
+    """Wave B2: single-row Flow.Metadata fetch.
+
+    `complexvalue` fields (Metadata + FullName) force a single-row
+    retrieval (`WHERE Id = '<id>'`). Returns the row dict or `None` on
+    miss. Called once per version id; parallelism happens in `main.py`
+    via `parallel_retrieve.fetch_bodies_parallel`.
+    """
+    soql = load_soql("flow_metadata_by_id", FLOW_VERSION_ID=flow_version_id)
+    resp = tooling_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    recs = _records(resp)
+    return recs[0] if recs else None
+
+
+# ===========================================================================
+# Bot resolution (Data API) — Phase 4 of main.py. Separate from Wave A/B
+# because the routing is DATA_QUERY not tooling, and the shape is simpler.
+# ===========================================================================
+
+
+def fetch_bot_versions(
+    agent_api_name: str,
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> list[dict]:
+    """Data API: resolve bot versions for a given bot DeveloperName.
+
+    Mirrors `resolve_bot.py` step 1 but routed through `data_query` so
+    the 401-refresh path is active. `resolve_bot.py` itself shells out
+    to `sf data query` and is retained as the env-var-driven entry-point
+    for Bash harness callers; `main.py` uses this in-process variant.
+    """
+    soql = load_soql("bot_version_lookup", AGENT_API_NAME=agent_api_name)
+    resp = data_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    return _records(resp)
+
+
+def fetch_bot_definition_details(
+    agent_api_name: str,
+    creds_provider: CredsProvider,
+    *,
+    api_version: str,
+    on_401_refresh: Callable[[], Tuple[str, str]],
+) -> dict | None:
+    """Data API: BotDefinition metadata (MasterLabel, AgentTemplate, ...).
+
+    Returns the single matching BotDefinition row or None. Feeds the
+    `tree["agent"]` fields in parse_wave's init_tree.
+    """
+    soql = load_soql("bot_definition_details", AGENT_API_NAME=agent_api_name)
+    resp = data_query(
+        creds_provider, soql,
+        api_version=api_version,
+        on_401_refresh=on_401_refresh,
+    )
+    recs = _records(resp)
+    return recs[0] if recs else None
+
+