@salesforce/afv-skills 1.14.0 → 1.16.0

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

@@ -0,0 +1,265 @@
+"""Metadata API listMetadata wrappers — for sObjects that are NOT
+exposed via SOQL on Tooling or Data API (e.g. GenAiPromptTemplate).
+
+Wraps the sf CLI `sf org list metadata` recipe. Not a REST client call —
+uses subprocess via sf_cli.run_sf. Failure semantics mirror the rest:
+returns [] on known-missing + surfaces unresolved reasons upstream;
+raises SfCliError / AuthRequired on unknown failures.
+"""
+from __future__ import annotations
+
+import subprocess
+import xml.etree.ElementTree as ET
+import zipfile
+from pathlib import Path
+from typing import Any, Dict, List
+
+from rest_client import redact_error
+from sf_cli import (
+    AuthRequired,
+    _redact_subprocess_stderr,
+    _stderr_matches_auth,
+    run_sf,
+)
+
+
+# Metadata XML default namespace — same as parse_bundle.NS. Duplicated
+# (rather than imported) to keep the "no intra-skill imports" convention
+# documented throughout the pipeline.
+_NS = {"sf": "http://soap.sforce.com/2006/04/metadata"}
+
+
+def list_prompt_template_metadata(org_alias: str) -> List[Dict[str, str]]:
+    """Return every GenAiPromptTemplate metadata component in the org.
+
+    Each row has the shape produced by `sf org list metadata --json`:
+      {"id": "0hfUv...", "fullName": "AGNT_...", "type": "GenAiPromptTemplate",
+       "namespacePrefix": "...", ...}
+
+    Empty list on success with no templates. Raises SfCliError on CLI
+    failure (caller decides whether to treat as fatal).
+    """
+    data = run_sf("list_metadata_genaiprompttemplate", ORG_ALIAS=org_alias)
+    result = data.get("result")
+    if not isinstance(result, list):
+        return []
+    return [r for r in result if isinstance(r, dict)]
+
+
+def _find_text(el: ET.Element | None, path: str) -> str | None:
+    if el is None:
+        return None
+    found = el.find(path, _NS)
+    if found is None:
+        return None
+    return found.text
+
+
+def _parse_prompt_template_xml(xml_bytes: bytes) -> Dict[str, Any] | None:
+    """Parse a single .genAiPromptTemplate XML file into a body dict.
+
+    Returns None on parse failure so the caller can log + skip. The
+    returned dict carries developerName/masterLabel/activeVersionIdentifier/
+    content/inputs — absent optional fields become None or empty lists.
+
+    Version selection: if multiple <templateVersions> elements exist,
+    prefer the one whose `versionIdentifier` matches the template-level
+    `activeVersionIdentifier`; otherwise fall back to the first version.
+    """
+    try:
+        root = ET.fromstring(xml_bytes)
+    except ET.ParseError:
+        return None
+
+    developer_name = _find_text(root, "sf:developerName")
+    master_label = _find_text(root, "sf:masterLabel")
+    active_version = _find_text(root, "sf:activeVersionIdentifier")
+
+    versions = root.findall("sf:templateVersions", _NS)
+    picked: ET.Element | None = None
+    if versions:
+        if active_version:
+            for v in versions:
+                vid = _find_text(v, "sf:versionIdentifier")
+                if vid and vid == active_version:
+                    picked = v
+                    break
+        if picked is None:
+            picked = versions[0]
+
+    content = _find_text(picked, "sf:content") if picked is not None else None
+
+    inputs: List[Dict[str, str]] = []
+    if picked is not None:
+        for inp in picked.findall("sf:inputs", _NS):
+            name = _find_text(inp, "sf:apiName") or _find_text(inp, "sf:name")
+            data_type = _find_text(inp, "sf:dataType")
+            if name is None and data_type is None:
+                continue
+            entry: Dict[str, str] = {}
+            if name is not None:
+                entry["name"] = name
+            if data_type is not None:
+                entry["dataType"] = data_type
+            inputs.append(entry)
+
+    return {
+        "developerName": developer_name,
+        "masterLabel": master_label,
+        "activeVersionIdentifier": active_version,
+        "content": content,
+        "inputs": inputs,
+    }
+
+
+# Timeout for `sf project retrieve start` — matches the prior YAML recipe's
+# `timeout_seconds: 300`. Kept as a module constant (rather than a literal
+# at the call site) so future adjustments have a single home.
+_RETRIEVE_TIMEOUT_SECONDS = 300
+
+# stderr patterns that mean "the CLI ran but there is no authenticated org
+# for this alias" — reraised as AuthRequired. Mirrors the prior recipe's
+# `auth_required_stderr_patterns` field.
+_RETRIEVE_AUTH_PATTERNS = ("NoOrgAuthenticationError", "AuthInfoError")
+
+
+def _run_retrieve(argv: List[str], timeout: int) -> "subprocess.CompletedProcess[str]":
+    """Thin wrapper over `subprocess.run` for the retrieve-start call.
+
+    Exists so tests can mock the subprocess boundary without also mocking
+    the argv-construction logic — see `RetrievePromptTemplatesTests`.
+    """
+    return subprocess.run(
+        argv,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+
+
+def retrieve_prompt_templates(
+    org_alias: str,
+    template_names: List[str],
+    work_dir: Path,
+) -> Dict[str, Dict[str, Any]]:
+    """Retrieve GenAiPromptTemplate bodies via `sf project retrieve start`.
+
+    The sf plugin's `--metadata` flag is REPEATED once per requested
+    template (`--metadata GenAiPromptTemplate:A --metadata
+    GenAiPromptTemplate:B ...`). A comma-joined value is NOT a valid list;
+    the CLI treats the whole comma-joined string as a single malformed
+    member name, silently skips it, and the resulting zip contains only
+    `package.xml` (observed 2026-05-05 against my-org-alias). Hence we
+    bypass the YAML recipe loader here — `run_sf` substitutes
+    `{{METADATA_SPEC}}` single-shot and has no list-expansion primitive.
+
+    The resulting `unpackaged.zip` carries one `.genAiPromptTemplate` XML
+    file per template under `unpackaged/genAiPromptTemplates/`.
+
+    Returns a dict keyed by `developerName`. Templates the retrieve
+    didn't produce a file for are OMITTED (caller handles missing by
+    leaving them in `_pending_fetches`).
+
+    Failure modes:
+      - Empty `template_names` → short-circuits with `{}` and no sf call.
+      - `AuthRequired` (stderr matches auth patterns) → re-raised.
+      - `SfCliError` (any other non-zero exit, timeout, etc) → swallowed;
+        returns `{}`. Caller logs the retrieval-failure reason at the
+        call site.
+      - Zip missing or malformed → returns `{}`.
+      - XML parse failure on a specific file → that file is skipped; the
+        other templates in the same zip still parse and return.
+    """
+    if not template_names:
+        return {}
+
+    retrieve_dir = work_dir / "prompt_template_retrieve"
+    retrieve_dir.mkdir(parents=True, exist_ok=True)
+    # Nuke stale files from a prior invocation so we don't trust an old
+    # unpackaged.zip if this run's sf call fails before writing one.
+    for path in retrieve_dir.iterdir():
+        if path.is_file():
+            path.unlink()
+        elif path.is_dir():
+            _rm_tree(path)
+
+    argv: List[str] = [
+        "sf",
+        "project",
+        "retrieve",
+        "start",
+        "--target-org",
+        org_alias,
+        "--target-metadata-dir",
+        str(retrieve_dir),
+        "--json",
+    ]
+    for name in template_names:
+        argv.extend(["--metadata", f"GenAiPromptTemplate:{name}"])
+
+    try:
+        cp = _run_retrieve(argv, _RETRIEVE_TIMEOUT_SECONDS)
+    except subprocess.TimeoutExpired as e:
+        # timeout exceptions may carry stderr; route through
+        # redact_error before surfacing — then swallow as non-fatal, same
+        # contract the old run_sf-based path had for SfCliError.
+        _ = redact_error(e)
+        return {}
+    except (OSError, subprocess.SubprocessError) as e:
+        _ = redact_error(e)
+        return {}
+
+    if cp.returncode != 0:
+        # Classify: auth failure re-raises, everything else is non-fatal.
+        if _stderr_matches_auth(cp.stderr, _RETRIEVE_AUTH_PATTERNS):
+            safe_stderr = _redact_subprocess_stderr(cp.stderr)
+            raise AuthRequired(safe_stderr or "auth required")
+        return {}
+
+    zip_path = retrieve_dir / "unpackaged.zip"
+    if not zip_path.exists():
+        return {}
+
+    results: Dict[str, Dict[str, Any]] = {}
+    try:
+        with zipfile.ZipFile(zip_path) as zf:
+            for info in zf.infolist():
+                name = info.filename
+                if not name.endswith(".genAiPromptTemplate"):
+                    continue
+                if "genAiPromptTemplates/" not in name:
+                    continue
+                try:
+                    xml_bytes = zf.read(info)
+                except (KeyError, zipfile.BadZipFile):
+                    continue
+                body = _parse_prompt_template_xml(xml_bytes)
+                if not body:
+                    continue
+                dev_name = body.get("developerName")
+                if not dev_name:
+                    # Fall back to the file stem if the XML somehow lacks
+                    # a <developerName> element — keeps the caller's
+                    # lookup working.
+                    stem = Path(name).stem
+                    if stem:
+                        body["developerName"] = stem
+                        dev_name = stem
+                if dev_name:
+                    results[dev_name] = body
+    except zipfile.BadZipFile:
+        return {}
+
+    return results
+
+
+def _rm_tree(path: Path) -> None:
+    """Recursively delete a directory tree. stdlib-only, no shutil import
+    at module top to keep the import surface minimal."""
+    for child in path.iterdir():
+        if child.is_dir():
+            _rm_tree(child)
+        else:
+            child.unlink()
+    path.rmdir()

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

@@ -0,0 +1,69 @@
+"""ThreadPoolExecutor orchestrator for Wave B body fetches.
+
+one failure MUST NOT abort the whole run. Callers merge failed kinds
+into `_unresolved[]` with `reason=f'{kind}-fetch-failed:{redact_error(exc)}'`
+and emit STATUS=PARTIAL_OK. We return a mixed list of (ok, result_or_exc)
+tuples instead of raising on the first failure — which is what
+`ThreadPoolExecutor.map` would do (and silently cancel remaining work in
+the process).
+
+Exception identity is preserved on the failure path: callers get the exact
+exception object back so they can run it through `rest_client.redact_error`
+at the point of logging. We intentionally do NOT stringify here — doing so
+would lose structured info (urllib.error.HTTPError.code, etc.) and could
+leak tokens into intermediate strings before redaction runs.
+"""
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Callable
+
+
+def fetch_bodies_parallel(
+    tasks: list[Callable[[], object]],
+    *,
+    max_workers: int = 5,
+) -> list[tuple[bool, object]]:
+    """Run zero-arg callables in parallel; return (ok, result_or_exc) per task.
+
+    contract:
+      * Each `task` is a zero-arg callable (use `functools.partial` to bind
+        args at the call site).
+      * On success, `(True, return_value)` is appended.
+      * On any exception, `(False, exc)` is appended — the EXC object itself,
+        not a stringification. Callers run it through `rest_client.redact_error`
+        before logging.
+      * Results are returned in INPUT ORDER, not completion order. Callers
+        frequently zip results back to their input tasks to identify which
+        target failed; completion order would break that contract.
+      * Empty task list returns `[]` without spinning up a pool.
+      * `max_workers=1` serializes — tasks run sequentially but the as_completed
+        path is still used (deterministic ordering preserved via index map).
+      * This function NEVER raises on a task failure. It may propagate
+        programmer errors (e.g., a non-callable in `tasks`) at submit time;
+        that's a bug surface, not a runtime failure mode.
+    """
+    if not tasks:
+        return []
+
+    # Pre-size the results list so we can assign by input index. This keeps
+    # output ordering deterministic and independent of completion timing,
+    # which matters for callers that identify failures positionally.
+    results: list[tuple[bool, object] | None] = [None] * len(tasks)
+
+    with ThreadPoolExecutor(max_workers=max_workers) as pool:
+        future_to_idx = {pool.submit(task): i for i, task in enumerate(tasks)}
+        for fut in as_completed(future_to_idx):
+            idx = future_to_idx[fut]
+            try:
+                results[idx] = (True, fut.result())
+            except Exception as exc:  # noqa: BLE001 — see contract above
+                # Preserve exc identity; do NOT stringify here. Callers run
+                # this through rest_client.redact_error at log time .
+                # We catch Exception (not BaseException) so KeyboardInterrupt
+                # / SystemExit still propagate — those signal shutdown, not a
+                # task failure.
+                results[idx] = (False, exc)
+
+    # All slots filled by construction — futures/indexes are 1:1 with input.
+    return [r for r in results if r is not None]  # type: ignore[return-value]

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

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Parse Bot.bot + GenAiPlannerBundle → _bundle_parsed.json + PLANNER_NAME.
+
+Replaces old agent Phase 2a (Bot.bot planner-name extraction via XPath-ish
+walk) + Phase 2c (bundle XML → topics/plannerActions + generation classifier).
+
+Step 1 — planner name:
+  Read $WORK_DIR/sf_meta/wave1_bot/unpackaged/bots/*.bot XML.
+  Path: /Bot/botVersions[fullName==$AGENT_VERSION]/conversationDefinitionPlanners[0]
+         /genAiPlannerName (fallback: plannerName, fullName)
+
+Step 2 — bundle (only if planner name resolved AND bundle dir exists):
+  Read $WORK_DIR/sf_meta/wave1_bundle/unpackaged/genAiPlannerBundles/<plannerName>/
+       *.genAiPlannerBundle
+  Extract: plannerType, description, masterLabel, localTopics[] with inline
+  localActions[], and (classic-only) plannerActions[].
+  Classify generation:
+    plannerType startswith "AiCopilot__"  → classic
+    plannerType startswith "Atlas__"      → nga
+    else                                   → unknown
+
+Emits:
+  $WORK_DIR/_bundle_parsed.json   (full structured extraction)
+  $WORK_DIR/_agent_generation.txt (generation string, newline-terminated)
+  stdout: `PLANNER_NAME=<shlex-quoted>\nAGENT_GENERATION=<shlex-quoted>`
+          + log lines (topic counts, action counts) for human readability.
+
+If Bot.bot has no <conversationDefinitionPlanners>, prints `PLANNER_NAME=''`
+and exits 0 — caller treats the tree as partial.
+
+Usage:
+    eval "$(python3 parse_bundle.py)"
+
+Inputs (env):
+    WORK_DIR       required
+    AGENT_VERSION  required — used to pin the right <botVersions> element
+
+Outputs:
+    files (above)
+    stdout eval-friendly K=V lines
+    exit 0 always (no recoverable error condition; missing XML → empty planner)
+"""
+import json
+import os
+import pathlib
+import shlex
+import sys
+import xml.etree.ElementTree as ET
+
+
+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_generation(planner_type: str) -> str:
+    if not planner_type:
+        return "unknown"
+    if planner_type.startswith("AiCopilot__"):
+        return "classic"
+    if planner_type.startswith("Atlas__"):
+        return "nga"
+    return "unknown"
+
+
+def extract_planner_name(work_dir: pathlib.Path, target_ver: str) -> str:
+    bots_dir = work_dir / "sf_meta" / "wave1_bot" / "unpackaged" / "bots"
+    if not bots_dir.exists():
+        return ""
+    for bot_file in bots_dir.glob("*.bot"):
+        try:
+            root = ET.parse(bot_file).getroot()
+        except ET.ParseError:
+            continue
+        for bv in root.findall("sf:botVersions", NS):
+            full = _t(bv, "sf:fullName") or _t(bv, "sf:developerName")
+            if target_ver and full != target_ver:
+                continue
+            for cdp in bv.findall("sf:conversationDefinitionPlanners", NS):
+                n = (_t(cdp, "sf:genAiPlannerName")
+                     or _t(cdp, "sf:plannerName")
+                     or _t(cdp, "sf:fullName"))
+                if n:
+                    return n
+    return ""
+
+
+def extract_bundle(work_dir: pathlib.Path, planner_name: str) -> dict:
+    bundle = {
+        "plannerType": None,
+        "plannerName": planner_name or None,
+        "generation": "unknown",
+        "description": None,
+        "masterLabel": None,
+        "topics": [],
+        "plannerActions": [],
+    }
+
+    planner_root = work_dir / "sf_meta" / "wave1_bundle" / "unpackaged" / "genAiPlannerBundles"
+    if not planner_root.exists():
+        return bundle
+
+    for bundle_dir in planner_root.iterdir():
+        if not bundle_dir.is_dir():
+            continue
+        bundle_xml = list(bundle_dir.glob("*.genAiPlannerBundle"))
+        if not bundle_xml:
+            continue
+        try:
+            root = ET.parse(bundle_xml[0]).getroot()
+        except ET.ParseError as e:
+            sys.stderr.write(f"parse_bundle.py: XML parse error on {bundle_xml[0]}: {e}\n")
+            continue
+
+        bundle["plannerType"] = _t(root, "sf:plannerType")
+        bundle["generation"] = classify_generation(bundle["plannerType"])
+        bundle["description"] = _t(root, "sf:description")
+        bundle["masterLabel"] = _t(root, "sf:masterLabel")
+
+        for lt in root.findall("sf:localTopics", NS):
+            tname = _t(lt, "sf:developerName") or _t(lt, "sf:fullName")
+            if not tname:
+                continue
+            topic = {
+                "name": tname,
+                "localDeveloperName": _t(lt, "sf:localDeveloperName"),
+                "masterLabel": _t(lt, "sf:masterLabel"),
+                "description": _t(lt, "sf:description"),
+                "canEscalate": (_t(lt, "sf:canEscalate") or "false").lower() == "true",
+                "pluginType": _t(lt, "sf:pluginType"),
+                "actions": [],
+            }
+            for la in lt.findall("sf:localActions", NS):
+                aname = _t(la, "sf:developerName") or _t(la, "sf:fullName")
+                if not aname:
+                    continue
+                topic["actions"].append({
+                    "name": aname,
+                    "localDeveloperName": _t(la, "sf:localDeveloperName"),
+                    "masterLabel": _t(la, "sf:masterLabel"),
+                    "description": _t(la, "sf:description"),
+                    "invocationTarget": _t(la, "sf:invocationTarget"),
+                    "invocationTargetType": (_t(la, "sf:invocationTargetType") or "").strip(),
+                    "source": _t(la, "sf:source"),
+                })
+            bundle["topics"].append(topic)
+
+        for pa in root.findall("sf:plannerActions", NS):
+            aname = _t(pa, "sf:developerName") or _t(pa, "sf:fullName")
+            if not aname:
+                continue
+            bundle["plannerActions"].append({
+                "name": aname,
+                "localDeveloperName": _t(pa, "sf:localDeveloperName"),
+                "masterLabel": _t(pa, "sf:masterLabel"),
+                "description": _t(pa, "sf:description"),
+                "invocationTarget": _t(pa, "sf:invocationTarget"),
+                "invocationTargetType": (_t(pa, "sf:invocationTargetType") or "").strip(),
+                "source": _t(pa, "sf:source"),
+            })
+        break  # first bundle dir is enough
+    return bundle
+
+
+def atomic_write(path: pathlib.Path, content: str) -> None:
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(content)
+    os.replace(tmp, path)
+
+
+def main() -> int:
+    try:
+        work_dir = pathlib.Path(os.environ["WORK_DIR"])
+        agent_version = os.environ["AGENT_VERSION"]
+    except KeyError as e:
+        sys.stderr.write(f"parse_bundle.py: missing env {e}\n")
+        return 1
+
+    # Step 1: planner name
+    planner_name = extract_planner_name(work_dir, agent_version)
+
+    # Step 2: bundle (only if planner resolved)
+    bundle = extract_bundle(work_dir, planner_name) if planner_name else {
+        "plannerType": None, "plannerName": None, "generation": "unknown",
+        "description": None, "masterLabel": None, "topics": [], "plannerActions": [],
+    }
+
+    atomic_write(work_dir / "_bundle_parsed.json", json.dumps(bundle, indent=2))
+    atomic_write(work_dir / "_agent_generation.txt", bundle["generation"] + "\n")
+
+    # Log lines (stderr would be lost via eval; use stderr for logs not shell-consumed)
+    total_actions = (
+        sum(len(t["actions"]) for t in bundle["topics"]) + len(bundle["plannerActions"])
+    )
+    sys.stderr.write(
+        f"[parse_bundle] plannerName={planner_name!r} "
+        f"plannerType={bundle['plannerType']!r} generation={bundle['generation']}\n"
+        f"[parse_bundle]   topics={len(bundle['topics'])} "
+        f"topic-scope-actions={sum(len(t['actions']) for t in bundle['topics'])} "
+        f"bundle-scope-actions={len(bundle['plannerActions'])} total={total_actions}\n"
+    )
+
+    # Eval-friendly stdout
+    sys.stdout.write(f"PLANNER_NAME={shlex.quote(planner_name)}\n")
+    sys.stdout.write(f"AGENT_GENERATION={shlex.quote(bundle['generation'])}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())