@salesforce/afv-skills 1.22.0 → 1.23.0

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

@@ -1,265 +0,0 @@
-"""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

@@ -1,69 +0,0 @@
-"""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

@@ -1,215 +0,0 @@
-#!/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())